Activate a business event

A business event is a named signal that is not about one person, such as market_open or sale_started. You define it in the console and bind flows to it. One activation starts every running flow bound to it.

POST https://api.true-engage.com/v1/business-events/{name}/activate

Before you start

1. In the console, go to Engage, then Business events, and define the event. Names are lowercase letters, digits and underscores, starting with a letter, 2 to 64 characters.
2. Build a flow whose entry is that business event, and publish it.
3. Create a server key with the flows.create_manage scope. See API keys.

Request body

Field	Type	Required	Notes
attributes	object	No	Values for this activation. Flows read them as {{business_event.*}} and in business-event conditions.

Example

curl -X POST https://api.true-engage.com/v1/business-events/market_open/activate \
  -u "test_xxxxxxxx:YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "attributes": { "index": "NIFTY 50", "openingLevel": 24810.35 } }'

const auth = Buffer.from(`${process.env.TE_APP_KEY}:${process.env.TE_SECRET}`).toString('base64');

const res = await fetch('https://api.true-engage.com/v1/business-events/market_open/activate', {
  method: 'POST',
  headers: { Authorization: `Basic ${auth}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ attributes: { index: 'NIFTY 50', openingLevel: 24810.35 } }),
});

Response

Status 202 Accepted.

{
  "requestId": "0b1c6f2e-6a1d-4c58-9f47-2b7d6d1f8a10",
  "data": {
    "activationId": "5f0b7a3e-2c1d-4a9b-8e6f-3d4c5b6a7f80",
    "flowIds": ["a1b2c3d4-0000-4000-8000-000000000001"]
  }
}

flowIds lists the flows that started a run. It is empty when no running flow is bound to the event.

Limits

Activations are limited to 5 per hour and 20 per day in each environment by default (self-hosted: BUSINESS_EVENT_LIMIT_PER_HOUR, BUSINESS_EVENT_LIMIT_PER_DAY). Beyond that you get 429 with BUSINESS_EVENT_THROTTLED and a Retry-After header giving the seconds until a slot frees. Wait that long; do not retry in a loop.

Retrying safely

Send an idempotencyKey (up to 200 characters) with the body. A retry with the same key and the same attributes within 24 hours returns the first response with deduplicated: true and starts no second run. Use one key per intended activation, for example market_open:2026-10-21.

• The same key with different attributes is refused with 409.
• A retry that arrives while the first call is still being processed gets 409 REQUEST_IN_PROGRESS. Retry after a moment.
• Without a key the call is not idempotent. If a request times out, check the flow's runs in the console before you call again.

Errors

Status	Code	Cause
404	BUSINESS_EVENT_NOT_FOUND	No event with this name, or it is archived.
429	BUSINESS_EVENT_THROTTLED	The hourly or daily limit is reached. See Retry-After.
409	REQUEST_IN_PROGRESS, CONFLICT	The idempotencyKey is in use by an unfinished call, or was used with different attributes.
401 or 403	INVALID_API_KEY, INSUFFICIENT_SCOPE, KEY_KIND_NOT_ALLOWED	Credential problem. Only server keys may call this endpoint.

See Errors.