Skip to main content
This guide walks you through the entire lifecycle of a Leadterra campaign — from grabbing your API key to watching your first sequence step queue up — using nothing but curl. Each step maps to a single API call, so you can drop any of them straight into an agent workflow or automation script.
1

Get your API key

Log in to your workspace at app.leadterra.co and navigate to Settings → API Keys. Create a new key and copy it immediately — it won’t be shown again.Your key will look like this:
sk_live_YOUR_KEY
Pass it as a Bearer token in the Authorization header on every request:
Authorization: Bearer sk_live_YOUR_KEY
Store your key in an environment variable (for example, LEADTERRA_API_KEY) so you don’t hard-code it in scripts or source files.
2

Inspect your sender pool

Before creating a campaign, check the delivery pools available to your workspace. This tells you the sending identities you can use and how much daily capacity remains.
curl https://app.leadterra.co/v1/sender-pools \
  -H "Authorization: Bearer sk_live_YOUR_KEY"
A successful response looks like this:
{
  "senderPools": [
    {
      "id": "pool_abc123",
      "name": "Primary Outbound",
      "dailyCapacity": 500,
      "remainingToday": 412,
      "senderCount": 8
    }
  ]
}
Use the remainingToday field to make sure you have enough headroom before you enroll a large lead list.
3

Create a campaign

Create a draft campaign with a name and at least one sequence step. The campaign stays in draft state until you explicitly start it.
curl -X POST https://app.leadterra.co/v1/campaigns \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VP Sales - AI workflow",
    "sequenceSteps": [{
      "subject": "Quick question, {{firstName}}",
      "bodyHtml": "<p>Saw your team is scaling outbound...</p>"
    }]
  }'
Leadterra returns the new campaign object, including the id you’ll need in the next step:
{
  "campaign": {
    "id": "camp_123",
    "name": "VP Sales - AI workflow",
    "status": "draft",
    "sequenceStepCount": 1,
    "createdAt": "2025-01-15T10:00:00Z"
  }
}
Copy the id value — you’ll use it in every subsequent call for this campaign.
4

Add leads and start the campaign

Enroll your leads by posting an array to the bulk endpoint. Leadterra upserts each record and links it to the campaign.
curl -X POST https://app.leadterra.co/v1/campaigns/camp_123/leads/bulk \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leads": [{
      "email": "ava@example.com",
      "firstName": "Ava",
      "company": "ExampleCo",
      "jobTitle": "VP Sales"
    }]
  }'
Once your leads are enrolled, start the campaign. Leadterra immediately begins queueing the first sequence step across your sender pool.
curl -X POST https://app.leadterra.co/v1/campaigns/camp_123/start \
  -H "Authorization: Bearer sk_live_YOUR_KEY"
That’s it. You can monitor progress at any time with GET /v1/campaigns/camp_123/stats, or receive live events by registering a webhook with POST /v1/webhooks.
These four calls cover the core happy path. The full API Reference documents every endpoint, request parameter, and response field — including campaign stats, reply retrieval, suppression lists, and webhook registration.