Skip to main content
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

​
name
string
required
Display name for the campaign. Shown in the dashboard and included in API responses. For example, "VP Sales - AI workflow".
​
sequenceSteps
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.

​
Personalization Tokens

You can embed the following tokens anywhere in subject or bodyHtml. Leadterra replaces them with each lead’s data at send time.
TokenReplaced 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

​
id
string
Unique identifier for the newly created campaign (e.g., camp_123). Use this ID with the start, pause, and stats endpoints.
​
name
string
The display name you supplied at creation.
​
status
string
Initial state of the campaign. Always draft on creation.
​
sequenceSteps
array
The sequence steps saved to the campaign.
​
createdAt
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 StatusCodeMeaning
400 Bad Requestinvalid_requestA required field is missing, a field value is the wrong type, or the request body is malformed JSON.
401 Unauthorizedauthentication_failedThe Authorization header is missing, malformed, or the key is invalid.
404 Not Foundworkspace_not_foundNo workspace is associated with the provided API key.