Enter a user into a flow

Use this endpoint to start a flow for one person at a moment your backend chooses, such as after a loan application is approved.

POST https://api.true-engage.com/v1/flows/{id}/enter

Before you start

• The flow must have API as its entry type and be running (published).
• The user must already have a profile.
• Use a server key with the flows.create_manage scope. See API keys.

{id} is the flow's id. It is in the console URL when you open the flow, /flows/<id>.

Request body

Field	Type	Required	Notes
userId	string (UUID)	One of userId or externalId	The TrueEngage profile id.
externalId	string	One of userId or externalId	Your id for the customer. Up to 255 characters.
properties	object	No	Values the flow can read as {{event.*}} for this entry.

Example

curl -X POST https://api.true-engage.com/v1/flows/a1b2c3d4-0000-4000-8000-000000000001/enter \
  -u "test_xxxxxxxx:YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "C10093", "properties": { "loanAmount": 250000 } }'

const auth = Buffer.from(`${process.env.TE_APP_KEY}:${process.env.TE_SECRET}`).toString('base64');
const flowId = 'a1b2c3d4-0000-4000-8000-000000000001';

const res = await fetch(`https://api.true-engage.com/v1/flows/${flowId}/enter`, {
  method: 'POST',
  headers: { Authorization: `Basic ${auth}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ externalId: 'C10093', properties: { loanAmount: 250000 } }),
});

Response

Status 202 Accepted.

{
  "requestId": "0b1c6f2e-6a1d-4c58-9f47-2b7d6d1f8a10",
  "data": { "queued": true, "userId": "3d2c1b0a-5e4f-4a3b-9c8d-7e6f5a4b3c2d" }
}

queued: true means the entry request is accepted. The flow's own rules still apply afterwards: entry filters and re-entry limits can stop the person from entering, and the send gate applies to every message. Check the flow's runs in the console to see the outcome.

Errors

Status	Code	Cause
404	FLOW_NOT_FOUND	No flow with this id in the key's environment.
409	FLOW_STATE_INVALID	The flow is not running.
422	FLOW_ENTRY_INVALID	The flow does not use API entry.
404	USER_NOT_FOUND	No profile matches userId or externalId.
429	RATE_LIMITED	Over 3,000 requests per minute per key.
401 or 403	INVALID_API_KEY, INSUFFICIENT_SCOPE, KEY_KIND_NOT_ALLOWED	Credential problem. Only server keys may call this endpoint.

See Errors.

This call is not idempotent. A second successful call can queue a second entry, subject to the flow's re-entry rules.