Skip to main content
Use this endpoint to add or update a batch of leads and immediately enroll them in a specific campaign. Leadterra performs an upsert on each entry: if a lead with a matching email address already exists in your workspace, their record is updated with any new field values you provide and they are re-enrolled in the campaign. New leads are created and enrolled in a single operation, keeping your contact data clean without requiring a separate sync step.

​
Endpoint

POST /v1/campaigns/:id/leads/bulk

​
Authorization

All requests must include a valid API key in the Authorization header as a Bearer token. 
Authorization: Bearer sk_live_YOUR_KEY

​
Path Parameters

​
id
string
required
The unique identifier of the campaign you want to enroll leads into.

​
Request Body

​
leads
array
required
An array of lead objects to upsert and enroll. Each object must contain at least an email address. You may include any additional custom fields beyond the ones listed below — Leadterra will store them on the lead record and make them available as personalization variables in your campaign sequences.

​
Example Request

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"
      },
      {
        "email": "ben@example.com",
        "firstName": "Ben",
        "company": "AcmeCorp",
        "jobTitle": "Head of Growth"
      },
      {
        "email": "cara@example.com",
        "firstName": "Cara",
        "company": "StartupHQ",
        "jobTitle": "Founder"
      },
      {
        "email": "dan@example.com",
        "firstName": "Dan",
        "company": "ScaleUp Inc",
        "jobTitle": "Director of Sales"
      }
    ]
  }'

​
Response Fields

​
enrolled
integer
The number of net-new leads that were created and enrolled in this request.
​
updated
integer
The number of existing leads whose records were updated and re-enrolled in this request.
​
total
integer
The total number of leads processed in this request. Always equal to enrolled + updated.

​
Example Response

{
  "enrolled": 3,
  "updated": 1,
  "total": 4
}
Upsert semantics: Leadterra matches leads by email address. If a lead with that email already exists in your workspace, their record is updated with the fields you provide in this request and they are added to the campaign — they will not appear as a duplicate entry. Only fields explicitly included in the request body are overwritten; omitted fields retain their existing values.

​
Error Codes

CodeMeaning
400Bad Request — the request body is malformed or missing required fields.
401Unauthorized — your API key is missing, invalid, or revoked.
404Not Found — no campaign exists for the provided :id in your workspace.
422Unprocessable Entity — one or more lead objects failed validation (e.g. invalid email format). The response body will include a errors array describing each failure.