# Campaigns API overview

> Run a webhook-triggered campaign or workflow from your own system with POST /api/v0/campaigns/{id}/runs: authentication, request body, custom fields as merge tags, responses, errors and limits.

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](https://releva.ai/documentation/learn/campaigns/how-campaigns-work/).

## 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](https://releva.ai/documentation/reference/events/overview/) 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

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

```plaintext
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](https://releva.ai/documentation/guides/shop-settings/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

`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.

```plaintext
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

`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

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.

### 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:

```plaintext
{{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](https://releva.ai/documentation/reference/webhooks/overview/).

## Errors

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

| Status | When                                                                                                                      | Message                                                                                                                                                                                                                                                                                                |
| ------ | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | Authentication failed                                                                                                     | See [Authentication](https://releva.ai/documentation/reference/campaigns/overview/#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

* 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

The endpoint is under `/api/v0`. For how versions and changes are handled, see [Authentication, errors and limits](https://releva.ai/documentation/reference/get-started/authentication-errors-and-limits/#versioning).

## Next steps

* [How campaigns work](https://releva.ai/documentation/learn/campaigns/how-campaigns-work/): Learn how One Off and Continuous campaigns differ and how launch, statuses and goals work.
* [Events API overview](https://releva.ai/documentation/reference/events/overview/): Send custom events from your system, with a working request for each endpoint.
* [Webhooks API overview](https://releva.ai/documentation/reference/webhooks/overview/): See what Releva sends to your webhook URL and how to record opens and clicks.
* [Find your Access Token and Secret Key](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/): Copy the Secret Key these calls authenticate with.