Skip to main content
POST
/
api
/
campaigns
Error
A valid request URL is required to generate request examples
{
  "_id": "<string>",
  "accountId": "<string>",
  "name": "<string>",
  "agentConfigId": "<string>",
  "channel": "whatsapp",
  "status": "draft",
  "schedule": {
    "startAt": "2023-11-07T05:31:56Z",
    "rateLimit": 5,
    "activeHours": {
      "start": "09:00",
      "end": "17:00",
      "timezone": "America/New_York"
    },
    "activeDays": [
      1,
      2,
      3,
      4,
      5
    ]
  },
  "leads": [
    {
      "leadId": "<string>",
      "status": "pending",
      "conversationId": "<string>",
      "sentAt": "2023-11-07T05:31:56Z",
      "error": "<string>"
    }
  ],
  "stats": {
    "totalLeads": 0,
    "sent": 0,
    "delivered": 0,
    "replied": 0,
    "qualified": 0,
    "disqualified": 0,
    "failed": 0
  },
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "leadFilter": {
    "statuses": [
      "<string>"
    ],
    "tags": [
      "<string>"
    ],
    "importedAfter": "2023-11-07T05:31:56Z"
  },
  "advancedFilter": {
    "conditions": [
      {
        "field": "<string>",
        "operator": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "manualLeadIds": [
    "<string>"
  ]
}

Authorizations

X-API-Key
string
header
required

API key for programmatic access. Keys use the format nl_live_<64 hex> or nl_test_<64 hex> and are scoped to an account's RBAC permissions.

Body

application/json

Request body for creating a new campaign.

name
string
required

Campaign display name

agentConfigId
string
required

ID of the agent configuration to use for conversations

channel
enum<string>
default:whatsapp

Messaging channel for outreach

Available options:
whatsapp,
telegram,
email
leadFilter
object

Basic lead filter criteria.

advancedFilter
object

Advanced filter with multiple conditions.

manualLeadIds
string[]

Explicitly selected lead IDs to include

schedule
object

Campaign scheduling and rate limit configuration.

Response

Campaign created successfully

A campaign orchestrates batch AI-driven outreach to leads.

_id
string
required

Unique campaign identifier

accountId
string
required

Account that owns this campaign

name
string
required

Campaign display name

agentConfigId
string
required

Reference to the AI agent configuration used for conversations

channel
enum<string>
default:whatsapp
required

Messaging channel for outreach

Available options:
whatsapp,
telegram,
email
status
enum<string>
default:draft
required

Current campaign lifecycle status

Available options:
draft,
scheduled,
running,
paused,
completed
schedule
object
required

Campaign scheduling and rate limit configuration.

leads
object[]
required

Per-lead tracking for the campaign

stats
object
required

Aggregate statistics for the campaign.

createdAt
string<date-time>
required
updatedAt
string<date-time>
required
leadFilter
object

Basic lead filter criteria.

advancedFilter
object

Advanced filter with multiple conditions.

manualLeadIds
string[]

Explicitly selected lead IDs to include in the campaign