Get Started with Leadterra: Launch a Campaign in Minutes

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.

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.

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.

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.

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.

Get Started

Core Concepts

Guides

Get Started with Leadterra: Launch a Campaign in Minutes