> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leadterra.co/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/campaigns — Create an Outbound Campaign

> POST /v1/campaigns — Creates a new draft campaign with an optional array of sequence steps. Returns the campaign ID and initial status.

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.

```bash theme={null}
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

<ParamField body="name" type="string" required>
  Display name for the campaign. Shown in the dashboard and included in API responses. For example, `"VP Sales - AI workflow"`.
</ParamField>

<ParamField body="sequenceSteps" type="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.

  <Expandable title="sequenceSteps item properties">
    <ParamField body="subject" type="string" required>
      Subject line for this step's email. Supports personalization tokens: `{{firstName}}`, `{{company}}`, `{{jobTitle}}`, and `{{email}}`.
    </ParamField>

    <ParamField body="bodyHtml" type="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.
    </ParamField>
  </Expandable>
</ParamField>

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

```bash theme={null}
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

<ResponseField name="id" type="string">
  Unique identifier for the newly created campaign (e.g., `camp_123`). Use this ID with the start, pause, and stats endpoints.
</ResponseField>

<ResponseField name="name" type="string">
  The display name you supplied at creation.
</ResponseField>

<ResponseField name="status" type="string">
  Initial state of the campaign. Always `draft` on creation.
</ResponseField>

<ResponseField name="sequenceSteps" type="array">
  The sequence steps saved to the campaign.

  <Expandable title="sequenceSteps item properties">
    <ResponseField name="stepIndex" type="integer">
      Zero-based position of this step in the sequence.
    </ResponseField>

    <ResponseField name="subject" type="string">
      Subject line for this step as provided.
    </ResponseField>

    <ResponseField name="bodyHtml" type="string">
      HTML body for this step as provided.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of when the campaign was created.
</ResponseField>

## Example Response

```json theme={null}
{
  "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.                                                |