POST /v1/campaigns — Create an Outbound Campaign

Use this endpoint to create a new outbound campaign in Leadterra. Campaigns are created in draft status, giving you time to enroll leads and review sequence steps before sending. You can optionally supply one or more sequence steps at creation time, or add them later through the dashboard. Each step supports personalization tokens such as {{firstName}} and {{company}} to tailor copy to each recipient.

POST /v1/campaigns

Authorization

All requests must include a Bearer token in the Authorization header. You can find your API key in the Leadterra dashboard under Settings → API Keys.

Request Body

string

required

Display name for the campaign. Shown in the dashboard and included in API responses. For example, "VP Sales - AI workflow".

array

An ordered list of email steps that make up the campaign sequence. Each step is sent to enrolled leads in sequence. If omitted, the campaign is created with no steps and you can add them later.

Show sequenceSteps item properties

string

required

Subject line for this step’s email. Supports personalization tokens: {{firstName}}, {{company}}, {{jobTitle}}, and {{email}}.

string

required

Full HTML body of the email. Supports the same personalization tokens as subject. Ensure your HTML is valid and includes a plain-text fallback where possible.

Personalization Tokens

You can embed the following tokens anywhere in subject or bodyHtml. Leadterra replaces them with each lead’s data at send time.

Token	Replaced with
`{{firstName}}`	Lead’s first name
`{{company}}`	Lead’s company name
`{{jobTitle}}`	Lead’s job title
`{{email}}`	Lead’s email address

Example Request

curl --request POST \
  --url https://app.leadterra.co/v1/campaigns \
  --header "Authorization: Bearer sk_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "VP Sales - AI workflow",
    "sequenceSteps": [
      {
        "subject": "Quick question, {{firstName}}",
        "bodyHtml": "<p>Hi {{firstName}},</p><p>Saw your team is scaling outbound at {{company}}. I had a quick question about how you are handling workflow automation right now.</p><p>Worth a 15-minute call this week?</p>"
      }
    ]
  }'

Response Fields

string

Unique identifier for the newly created campaign (e.g., camp_123). Use this ID with the start, pause, and stats endpoints.

string

The display name you supplied at creation.

string

Initial state of the campaign. Always draft on creation.

array

The sequence steps saved to the campaign.

Show sequenceSteps item properties

integer

Zero-based position of this step in the sequence.

string

Subject line for this step as provided.

string

HTML body for this step as provided.

string

ISO 8601 timestamp of when the campaign was created.

Example Response

{
  "id": "camp_123",
  "name": "VP Sales - AI workflow",
  "status": "draft",
  "sequenceSteps": [
    {
      "stepIndex": 0,
      "subject": "Quick question, {{firstName}}",
      "bodyHtml": "<p>Hi {{firstName}},</p><p>Saw your team is scaling outbound at {{company}}. I had a quick question about how you are handling workflow automation right now.</p><p>Worth a 15-minute call this week?</p>"
    }
  ],
  "createdAt": "2025-01-15T10:32:00Z"
}

Error Codes

HTTP Status	Code	Meaning
`400 Bad Request`	`invalid_request`	A required field is missing, a field value is the wrong type, or the request body is malformed JSON.
`401 Unauthorized`	`authentication_failed`	The `Authorization` header is missing, malformed, or the key is invalid.
`404 Not Found`	`workspace_not_found`	No workspace is associated with the provided API key.

Sender Infrastructure

Campaigns

Leads & Replies

SDR Workspace

Webhooks

POST /v1/campaigns — Create an Outbound Campaign

Authorization

Request Body

Personalization Tokens

Example Request

Response Fields

Example Response

Error Codes

​Authorization

​Request Body

​Personalization Tokens

​Example Request

​Response Fields

​Example Response

​Error Codes

Authorization

Request Body

Personalization Tokens

Example Request

Response Fields

Example Response

Error Codes