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.
When to use it
Section titled “When to use it”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.
Authentication
Section titled “Authentication”Send your shop’s secret key as a bearer token:
authorization: Bearer $RELEVA_SECRET_KEYThe 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.
Request
Section titled “Request”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": {}}}.
Response
Section titled “Response”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.
What a run does
Section titled “What a run does”- Releva evaluates the campaign’s Target Segment at that moment.
- 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.
- Campaign Scope and channel consent apply as for any campaign run.
- 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.
Custom fields in messages
Section titled “Custom fields in messages”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
Section titled “Errors”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.
Limits
Section titled “Limits”- 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.
Versioning
Section titled “Versioning”The endpoint is under /api/v0. For how versions and changes are handled, see Authentication, errors and limits.