Skip to main content
A campaign sends your candidates (name + mobile number) to an enrichment. Record contacts them on WhatsApp, follows up by call and SMS, and asks the enrichment’s questions.
This contacts real people and spends credits. Credits are charged per candidate added (the live wallet for a live key, the test wallet for a TEST key) and checked for the whole batch first: if your organisation cannot cover it, nothing is created and the call answers 402 INSUFFICIENT_CREDITS. There is no separate start step: contacting begins as soon as the campaign is created. The phone numbers in the samples are placeholders, so replace them with your own test numbers. If the enrichment’s questions_status is not yet ready, the campaign waits and goes out by itself.

Candidates

  • phone_number is an Indian mobile number: 10 digits (98765 43210) or with the country code (+91 98765 43210). It is returned in full as +91….
  • external_id is your id for the candidate. It comes back on every candidate and result.
  • Up to 1,000 candidates per call.
  • A row that cannot be contacted never fails the call. It is left out and listed in skipped with its position and a reason: invalid_phone, opted_out (the number replied STOP earlier) or duplicate (already earlier in the same list). If no row can be contacted, the call answers 400 and details say why for each one.
  • Daily allowance: a key may put 2,000 different people into campaigns a day (200 for a TEST key), counted together with its Blue Collar campaigns and reset at midnight IST. A call that would go past it is refused whole with 429 DAILY_CAP and creates nothing. Skipped rows do not count.
  • A TEST key holds at most 50 candidates per enrichment (403 FORBIDDEN beyond that).

Campaign status

awaiting_questions: true means the questions are still being prepared and nothing has gone out yet.

Endpoints

Create a campaign

POST /enrichments/{enrichment_id}/campaigns Returns campaign_id, the candidates and the skipped rows. Scope: enrichment:campaigns · Idempotency-Key: required
This contacts real people.
Response · 201
Errors: 400 VALIDATION_FAILED (no contactable number, or a field wrong), 402 INSUFFICIENT_CREDITS (the organisation’s credits do not cover the whole batch; nothing is created), 403 FORBIDDEN (the TEST limit), 404 NOT_FOUND (no such enrichment, or it is archived), 429 DAILY_CAP (the key’s daily allowance of different people is used up).

List campaigns

GET /enrichments/{enrichment_id}/campaigns The campaigns of an enrichment, newest first, with counts of candidates, sent and completed. Takes limit and cursor. Scope: enrichment:read

Get a campaign

GET /enrichments/{enrichment_id}/campaigns/{campaign_id} Progress of one campaign: the funnel, numbers per channel and where candidates drop off per question. Scope: enrichment:read
Response · 200

Pause a campaign

POST /enrichments/{enrichment_id}/campaigns/{campaign_id}/pause Nothing more goes out (no invite, follow-up, SMS or call) until you resume. Only a live campaign can be paused, and one whose candidates have all finished has nothing left to pause. Scope: enrichment:campaigns · Idempotency-Key: optional · Errors: 404 NOT_FOUND, 409 CONFLICT (the campaign is not live, or every candidate has already finished)

Resume a campaign

POST /enrichments/{enrichment_id}/campaigns/{campaign_id}/resume Sending carries on where it stopped. Only a paused campaign can be resumed. Scope: enrichment:campaigns · Idempotency-Key: optional · Errors: 404 NOT_FOUND, 409 CONFLICT (the campaign is not paused)