Skip to main content
POST
Enroll contacts
Adds contacts to a campaign. Enroll leads you already have with lead_ids, raw phone numbers with phone_numbers, or both in one request. Numbers are matched to existing leads where possible and created as new leads otherwise. The response is a report, not a failure: bad rows are described rather than aborting the batch, so a list with three unparseable numbers and two people on the do-not-call list still enrolls everybody else and tells you exactly who was skipped and why. Enrollment works on a draft campaign and on a live one — adding contacts to a running campaign is supported and they join the queue at the normal pace. Required scope: campaigns:manage.

Path parameters

Body

At least one of lead_ids / phone_numbers must be present and non-empty. Their combined length may not exceed 1000 per request — send several requests for a longer list. Numbers are canonicalized before any lookup or insert, so the same person supplied as 0501234567 in one row and +972501234567 in another resolves to one lead and one enrollment rather than two. name, email and notes apply to newly created leads. When a number matches a lead you already have, the existing lead is enrolled as-is and its details are left untouched — update it through PATCH /leads/{id} if you need to change them.

What gets skipped

A verbal opt-out during a call (“stop calling me”) adds that number to the do-not-call list automatically, workspace-wide, so it will be skipped by every future enrollment as well.

Response fields

Example request

Example response

A request where nothing survived the filters still returns 200 with the report, and without total_leads:
Always inspect the report rather than assuming 200 means everything landed.

Errors

Authorizations

Authorization
string
header
required

Your Yappr API key (e.g. ypr_live_...). Generate one in the dashboard under Settings → API Keys.

Path Parameters

id
string<uuid>
required

Body

application/json

Supply lead_ids, phone_numbers, or both — at least one must be non-empty.

lead_ids
string<uuid>[]

IDs of leads that already exist in this workspace.

phone_numbers
(string | object)[]

Numbers to enroll. Each entry is either a bare phone string or an object. Any format is accepted and normalized to E.164.

Example:

"+972501234567"

Response

Enrollment report. Returned even when nothing was enrolled — read the counters and the rejection arrays to see why.

Result of POST /campaigns/{id}/leads. Enrollment is per-row and best-effort: a bad phone number or a number on the do-not-call list is reported here rather than failing the whole batch, and re-enrolling an existing contact is idempotent.

Numbers are canonicalized to E.164 before anything is written, so the same person cannot be enrolled twice under two formats.

campaign_id
string<uuid>
enrolled
integer

Contacts newly enrolled by this request.

already_enrolled
integer

Contacts that were already enrolled — no-ops, not errors.

leads_created
integer

New leads created from phone_numbers entries with no existing match.

leads_matched
integer

phone_numbers entries matched to a lead you already had.

invalid_phone
object[]

Rows rejected before enrollment because the number could not be parsed, or the lead could not be created.

on_do_not_call
string[]

Numbers excluded because they are on the workspace do-not-call list. A verbal opt-out on a call adds the number to that list automatically, workspace-wide, so previously-contacted people can appear here.

not_found
string<uuid>[]

IDs from lead_ids that are not leads in this workspace.

total_leads
integer

Total contacts enrolled in the campaign after this request. Omitted when nothing was enrolled.

company_id
string<uuid>