Candidates
phone_numberis an Indian mobile number: 10 digits (98765 43210) or with the country code (+91 98765 43210). It is returned in full as+91….external_idis 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
skippedwith its position and a reason:invalid_phone,opted_out(the number replied STOP earlier) orduplicate(already earlier in the same list). If no row can be contacted, the call answers400anddetailssay 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_CAPand creates nothing. Skipped rows do not count. - A TEST key holds at most 50 candidates per enrichment (
403 FORBIDDENbeyond 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
Response · 201
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)
