Skip to main content
Leads are the people your campaigns reach out to. Each lead is a contact record attached to a specific campaign, carrying the fields your sequence templates use for personalization. Leadterra’s bulk upsert endpoint is designed for programmatic GTM workflows — you can push hundreds of leads into a campaign in a single API call, and the platform handles both creation and deduplication automatically.

​
Lead fields

Every lead has a set of standard fields. The email field is the only required value; all other standard fields are optional but strongly recommended because they power your personalization tokens. Beyond these standard fields, you can pass any additional key-value pairs in the lead object. Leadterra stores them as custom variables and makes them available as personalization tokens using the same {{fieldName}} syntax. For example, if you include a useCase field, you can reference it in your email body as {{useCase}}.

​
Upsert semantics

POST /v1/campaigns/:id/leads/bulk uses upsert logic, meaning a single call both creates new leads and updates existing ones. Leadterra matches leads by email address within the scope of the campaign. If a lead with that email already exists in the campaign, its fields are updated with the values you provide. If no match is found, a new lead record is created.
Sample response
The response breaks down exactly how many leads were created versus updated in this call, so your automation can log the delta without re-querying the campaign.

​
Enrollment

Bulk upsert does not just load contact data — it also enrolls each lead into the campaign at the same time. The moment the call succeeds, newly created leads are queued to receive step one of your sequence. Updated leads that are already enrolled continue from wherever they are in the sequence; their position is not reset. If the campaign is in draft state when you upsert leads, the leads are added to the campaign but will not receive any messages until you call POST /v1/campaigns/:id/start. This lets you front-load your lead list before going live.
Include every field that your sequence steps reference before you enroll leads. Once a campaign is running, missing personalization fields produce empty token substitutions that are visible to your recipients. Populate firstName, company, and jobTitle at minimum, plus any custom tokens your templates use.