Skip to content

Area: Developers

Campaigns API overview

The campaigns API has one endpoint under https://releva.ai/api/v0:

Endpoint Purpose
POST /campaigns/{id}/runs Run a triggered campaign or workflow whose trigger is Webhook

Campaigns and workflows are created, edited, launched and switched on or off in the admin only; there is no public API for that. For what a campaign is, read How campaigns work.

Your system knows that something happened which Releva does not see as an event: a product is back in stock, a batch job finished, a webinar starts tomorrow. Call this endpoint and Releva evaluates the campaign’s Target Segment now and lets every eligible profile enter the campaign. One call is one run for the whole segment, not for one profile. To react to something one customer did, send an event instead and use an event-triggered workflow.

The campaign must be a triggered workflow with Trigger on set to Webhook (Workflows › Triggered). Its card shows a webhook instructions link with a ready-made request for its id.

Send your shop’s secret key as a bearer token:

authorization: Bearer $RELEVA_SECRET_KEY

The key is a UUID and identifies the shop. Find it in the admin under Settings › Shop & Integration; see Find your API keys. Authentication runs before anything else and failures answer 400, not 401:

Problem Message
No authorization header Authorization header is missing.
Header is not Bearer <token> Authorization header is malformed. It should look like `Bearer <string>`.
Token is not a UUID Authorization header contains an invalid Bearer token.
No shop has this key Domain with the provided secret key cannot be found.

A shop that has been switched off answers 402 with Domain is disabled. Please reach out to support@releva.ai to enable it.

POST /api/v0/campaigns/{id}/runs with content-type: application/json.

Parameter In Type Notes
id path integer The campaign or workflow id: the number in the admin URL .../workflows/<id>/details, also filled in on the webhook instructions request. The campaign must belong to the shop of the secret key.

Body:

Field Type Required Notes
trigger object yes Only custom is allowed inside it. {} is accepted.
trigger.custom object no Custom fields for this run, in the same shape as custom on products, profiles and events: optional string, numeric and date lists of { "key", "values" }. date values are ISO-8601 dates with optional time and offset, for example 2026-10-21 or 2026-10-21T09:00:00Z.

The body is validated strictly at every level: any other key is rejected.

curl -X POST 'https://releva.ai/api/v0/campaigns/123/runs' \
-H "authorization: Bearer $RELEVA_SECRET_KEY" \
-H 'content-type: application/json' \
-d '{
"trigger": {
"custom": {
"string": [{ "key": "restockedSku", "values": ["DEMO-1001-M"] }],
"numeric": [{ "key": "restockedQuantity", "values": [25] }],
"date": [{ "key": "restockedAt", "values": ["2026-10-21T09:00:00Z"] }]
}
}
}'

The smallest valid body is {"trigger": {"custom": {}}}.

202 Accepted with the body {}. The run is queued, not done.

A 202 means the request was valid and the campaign is a webhook-triggered one in your shop. It does not check that the campaign is switched on: a run for a campaign whose switch is off, or for a paused shop, is dropped silently. Switch the campaign on in the admin before calling.

  1. Releva evaluates the campaign’s Target Segment at that moment.
  2. It keeps the profiles the campaign’s Repeat Entry setting allows: with repeat entry off, only profiles that never entered this campaign; with a cooldown, only profiles whose last entry is older than the cooldown; with repeat entry on and no cooldown, everyone in the segment, on every call.
  3. Campaign Scope and channel consent apply as for any campaign run.
  4. Each kept profile enters the campaign and receives its messages.

Two identical calls (same id, same body) made while the first run is still being set up are de-duplicated: the second is dropped. Calls with different custom fields are not.

The trigger you send becomes the run’s trigger event. In the campaign’s email templates its custom fields are available as:

{{triggerEvent.custom.string.restockedSku}}
{{triggerEvent.custom.numeric.restockedQuantity}}
{{triggerEvent.custom.date.restockedAt}}

When a key has several values they are joined with , . Note that {{custom.string.<key>}} without the triggerEvent. prefix refers to the profile’s own custom fields, not to the run’s. {{triggerEvent.…}} tags are only accepted in triggered campaigns and workflows.

Outbound Webhook steps in the workflow receive the same trigger as triggerEvent in their payload; see the Webhooks API overview.

Errors have one shape, { "message": "..." }. Several validation errors are joined with a space.

Status When Message
400 Authentication failed See Authentication
400 No body, or content-type is not application/json The '' field is required.
400 trigger missing The 'trigger' field is required.
400 trigger is not an object The 'trigger' must be an Object.
400 Unknown key in trigger The object 'trigger' contains forbidden keys: 'products'.
400 Unknown key in trigger.custom The object 'trigger.custom' contains forbidden keys: 'text'.
400 Wrong value type The 'trigger.custom.string[0].values[0]' field must be a string.
400 Date not ISO-8601 trigger.custom.date[0].values[0] must be a valid ISO-8601 date such as 2020-01-01 with optional time in hours, minutes, seconds and timezone offset with optional milliseconds such as 2020-01-01T23:59:59.999Z or 2020-01-01T23:59:59.999-0500 or 2020-01-01T23:59:59-0500. Got 21/10/2026 instead.
400 Body is not valid JSON Expected ',' or '}' after property value in JSON at position 26 (line 2 column 1) (text depends on the input)
400 The campaign is triggered by an event, not a webhook This campaign is configured to use event trigger and cannot be triggered via webhook!
400 Plain HTTP We do not support non-HTTPS requests.
402 Shop disabled Domain is disabled. Please reach out to support@releva.ai to enable it.
404 No triggered campaign with this id in your shop: unknown id, a one-off or continuous campaign, or another shop’s campaign No Triggered campaign found for id: 999
413 Body larger than 800 KB request entity too large
500 Unexpected error, including a non-numeric id An internal error occurred.

A GET on the path answers 404 with an HTML body.

  • Body size: 800 KB per request.
  • Rate limits: none. Identical concurrent calls are de-duplicated only while the first run is being set up.
  • Runs are asynchronous and there is no endpoint to read a run’s status. Results show on the campaign’s Statistics page in the admin.

The endpoint is under /api/v0. For how versions and changes are handled, see Authentication, errors and limits.