Campaigns API - RevRag.ai

Overview

A campaign in RevRag is a workspace-scoped definition that bundles an agent, a schedule, retry/follow-up rules, and concurrency limits. This page documents the two endpoints you use to push records into an already-running campaign:

Endpoint	Use when
`POST /records/push`	You want to push records in realtime, one at a time as events happen on your side
`POST /records/push-bulk`	You batch records on your side and flush many in a single call

The campaign itself — name, agent, schedule, end date, retry rules, concurrency — is configured and launched in the RevRag dashboard. By the time you call these APIs, the campaign should already be running. The dashboard’s Campaign → Settings tab shows a copy-pasteable curl with your campaign’s id pre-filled.

Base URLs

Production: https://api.revrag.ai
Staging: https://staging-api.revrag.ai

Authentication

All requests require a workspace-scoped API key in the X-API-Key header:

X-API-Key: YOUR_API_KEY

The workspace is resolved from the API key itself — you do not pass a workspace header. The campaign in the path must belong to the same workspace as the API key, otherwise the request returns 404 Not Found.

Before You Push

The campaign is fully created, configured, and started from the RevRag dashboard. From the API caller’s side you only need:

The campaign_id — copy it from the dashboard’s Campaign → Settings tab (it’s also in the URL of the campaign detail page).
Your X-API-Key — issued for your workspace.
The agent’s variable names, if the agent expects per-call variables. Variable names are visible on the campaign’s Settings tab.

Endpoints

1. Push a Single Record

POST /v1/campaigns/{campaign_id}/records/push Queue one record for calling. The runner picks it up on its next polling cycle (typically within ~1 second) and dispatches the call subject to the campaign’s daily time-window, attempt schedule, and concurrency cap.

Path Parameters

Parameter	Type	Required	Description
`campaign_id`	string (uuid)	Yes	The campaign to push the record into

Header Parameters

Parameter	Type	Required	Description
`X-API-Key`	string	Yes	Workspace-scoped API key
`Content-Type`	string	Yes	Must be `application/json`

Request Body

{
  "phone_number": "+919876543210",
  "variables": {
    "first_name": "Pankaj",
    "company": "Acme Inc."
  },
  "app_user_id": "user_12345",
  "app_session_id": "sess_abcdef"
}

Request Parameters

Parameter	Type	Required	Description
`phone_number`	string	Yes	E.164 format recommended (`+919876543210`)
`variables`	object	No	Key-value pairs matching the agent’s variable names. Sent into the agent’s prompt at call time
`app_user_id`	string	No	Your system’s user id — echoed back in webhooks and stored on the call log
`app_session_id`	string	No	Your system’s session id — echoed back in webhooks and stored on the call log

Response

Success (200 OK)

{
  "id": "00000000-0000-0000-0000-000000000001",
  "campaign_id": "11111111-1111-1111-1111-111111111111",
  "workspace_id": "22222222-2222-2222-2222-222222222222",
  "phone_number": "+919876543210",
  "status": "queued",
  "variables": {
    "first_name": "Pankaj",
    "company": "Acme Inc."
  },
  "attempt_count": 0,
  "max_attempts": 3,
  "call_history": null,
  "next_attempt_at": null,
  "dnc_at": null,
  "dnc_reason": null,
  "created_at": "2026-05-27T03:00:00.000000+00:00",
  "updated_at": "2026-05-27T03:00:00.000000+00:00"
}

Response Parameters

Parameter	Type	Description
`id`	string (uuid)	Unique id for this record / call attempt batch
`campaign_id`	string (uuid)	Campaign this record belongs to
`workspace_id`	string (uuid)	Workspace (derived from the API key)
`phone_number`	string	Echoed back from the request
`status`	string	Initial status — typically `queued`. See Record Status Values
`variables`	object \| null	Echoed back from the request
`attempt_count`	number	Number of attempts made so far — `0` on push
`max_attempts`	number	From the campaign’s execution config
`call_history`	array \| null	Per-attempt call log — `null` on push
`next_attempt_at`	string \| null	ISO-8601 timestamp of next attempt if retry/follow-up scheduled
`dnc_at`	string \| null	When the number was added to DNC, if applicable
`dnc_reason`	string \| null	Reason for DNC, if applicable
`created_at`	string	ISO-8601 timestamp
`updated_at`	string	ISO-8601 timestamp

cURL Example

curl -X POST \
  "https://staging-api.revrag.ai/v1/campaigns/{campaign_id}/records/push" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+919876543210",
    "variables": {
      "first_name": "Pankaj",
      "company": "Acme Inc."
    }
  }'

2. Push Bulk Records

POST /v1/campaigns/{campaign_id}/records/push-bulk Queue multiple records in a single call. Each record is treated independently — the runner dispatches them per the same schedule / concurrency rules as single push. The response counts how many were accepted vs rejected. Partial success is possible (some accepted, some rejected) and is returned as a single 200 OK response.

Path Parameters

Parameter	Type	Required	Description
`campaign_id`	string (uuid)	Yes	The campaign to push records into

Header Parameters

Parameter	Type	Required	Description
`X-API-Key`	string	Yes	Workspace-scoped API key
`Content-Type`	string	Yes	Must be `application/json`

Request Body

{
  "records": [
    {
      "phone_number": "+919876543210",
      "variables": { "first_name": "Pankaj" },
      "app_user_id": "user_12345"
    },
    {
      "phone_number": "+919876543211",
      "variables": { "first_name": "Riya" }
    }
  ]
}

Request Parameters

Parameter	Type	Required	Description
`records`	array	Yes	Array of records, each with the same shape as the single-push body

Each record in the array supports the same fields as the single push: phone_number (required), variables, app_user_id, app_session_id.

Response

Success (200 OK)

{
  "accepted": 2,
  "rejected": 0,
  "errors": null
}

Partial success (200 OK)

{
  "accepted": 1,
  "rejected": 1,
  "errors": [
    {
      "index": 1,
      "reason": "Invalid phone number format"
    }
  ]
}

Response Parameters

Parameter	Type	Description
`accepted`	number	How many records were inserted and queued for calling
`rejected`	number	How many were skipped (invalid phone, schema error, etc.)
`errors`	array \| null	Per-record error details when `rejected > 0`. Each entry has the `index` (zero-based position in the `records` array) and a `reason` string

cURL Example

curl -X POST \
  "https://staging-api.revrag.ai/v1/campaigns/{campaign_id}/records/push-bulk" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "phone_number": "+919876543210",
        "variables": { "first_name": "Pankaj" }
      },
      {
        "phone_number": "+919876543211",
        "variables": { "first_name": "Riya" }
      }
    ]
  }'

How Records are Called

Pushing a record does not always trigger an immediate dial. After your push is accepted, the campaign runner picks up queued records each cycle and applies the campaign’s configured gates (all set in the dashboard):

Gate	Effect on your record
Outside the campaign’s daily calling window	Stays queued until the window opens
Day not in the campaign’s active days (e.g. weekend on a Mon-Fri campaign)	Queued until the next active day’s window
First-attempt schedule is later than today	Queued until that day
Campaign’s max concurrency reached	Queued until a slot frees
Phone is in the workspace’s Do-Not-Call list	Marked `dnc`, no call placed

When all gates are open, dispatch is typically within ~1 second of the push. See Record Status Values for what each status means in flight. If you push to a campaign that has finished (past its end date) or has been cancelled/paused-and-stopped from the dashboard, the API returns 400. The campaign must be in an active state on the dashboard to accept pushes.

Get Call Status

GET /v1/campaigns/trigger/status/{call_id} Fetch the status, transcript, recording URL, summary, and extracted variables for a specific call. The call_id for a pushed record is delivered via webhook (see below) or is visible on the campaign’s Records tab in the dashboard. It is not part of the push response itself, since the call is placed asynchronously by the campaign runner.

Path Parameters

Parameter	Type	Required	Description
`call_id`	string (uuid)	Yes	The call id, obtained from the webhook payload or from the dashboard

Header Parameters

Parameter	Type	Required	Description
`X-API-Key`	string	Yes	Workspace-scoped API key

Response shape and example are identical to the legacy Get Call Status endpoint — call_status, from_number, to_number, summary, start_time, end_time, duration, disconnection_reason, recording_url, transcription, and any custom_variables extracted by the agent.

cURL Example

curl -X GET \
  "https://staging-api.revrag.ai/v1/campaigns/trigger/status/call_123e4567-e89b-12d3-a456-426614174000" \
  -H "X-API-Key: YOUR_API_KEY"

Webhook Notifications

Instead of polling for status, configure a webhook URL to receive a POST notification when each call ends. Webhooks fire for every call placed by the agent — including calls dispatched from campaigns pushed via this API.

Configuration

Contact contact@revrag.ai to configure your webhook URL and signing secret.

Payload

The webhook receives a POST request with the same JSON structure as the Get Call Status response. The variable_fields you sent in the original push (variables field) are echoed back on the payload as variable_fields, and app_user_id / app_session_id (if you sent them) are available on the call log for correlation back to your records. For payload signing and verification, see the Webhook Security reference.

Record Status Values

Status	Description
`queued`	Accepted, waiting for the runner to pick it up
`in_progress`	Call is being placed or is live
`completed`	Call finished — see `call_history` on the record for details
`failed`	Call attempt failed (e.g. telephony error). Will retry if attempts remain and retry conditions match
`retry_pending`	Waiting for the next retry attempt at `next_attempt_at`
`follow_up_pending`	Waiting for a follow-up attempt scheduled by post-call logic
`rescheduled`	Caller requested a callback — will dispatch at the requested time
`dnc`	Phone added to Do-Not-Call list, no further attempts

Common Errors

Status	When
`400 Bad Request`	Campaign is not currently accepting pushes (e.g. already finished or cancelled on the dashboard), or `phone_number` is malformed
`401 Unauthorized`	Missing or invalid `X-API-Key` header
`404 Not Found`	`campaign_id` doesn’t exist in the API key’s workspace, or `campaign_id` isn’t a valid UUID
`422 Unprocessable Entity`	Request body doesn’t match the schema (missing `phone_number`, malformed JSON, etc.)

Example error body

{
  "detail": "Cannot push records: campaign is completed."
}

Support

For API keys, campaign setup, or any technical issue, contact contact@revrag.ai.

Documentation Index

​Overview

​Base URLs

​Authentication

​Before You Push

​Endpoints

​1. Push a Single Record

​Path Parameters

​Header Parameters

​Request Body

​Request Parameters

​Response

​Response Parameters

​cURL Example

​2. Push Bulk Records

​Path Parameters

​Header Parameters

​Request Body

​Request Parameters

​Response

​Response Parameters

​cURL Example

​How Records are Called

​Get Call Status

​Path Parameters

​Header Parameters

​cURL Example

​Webhook Notifications

​Configuration

​Payload

​Record Status Values

​Common Errors

​Support

Overview

Base URLs

Authentication

Before You Push

Endpoints

1. Push a Single Record

Path Parameters

Header Parameters

Request Body

Request Parameters

Response

Response Parameters

cURL Example

2. Push Bulk Records

Path Parameters

Header Parameters

Request Body

Request Parameters

Response

Response Parameters

cURL Example

How Records are Called

Get Call Status

Path Parameters

Header Parameters

cURL Example

Webhook Notifications

Configuration

Payload

Record Status Values

Common Errors

Support