Enroll contacts
https://api.norreach.app/v1/campaigns/{id}/enrollmentsPuts contacts into a campaign: contact_ids (up to 10,000) or every contact on a list_id (a list of at most as many). Only this workspace's contacts are enrolled (others come back in not_found_ids); contacts already in the campaign are skipped and reported, never enrolled twice; the campaign's own enrollment rules may exclude some (excluded). A live campaign starts them now — or holds each first send in Approvals when it asks before sending; a draft or paused one holds them until it runs. At most 50 000 new enrollments a day per workspace (429 send_cap_reached). The suppression list, consent and quiet hours are checked again at every send. Also needs campaigns:write (it changes the campaign's audience).
curl -X POST "https://api.norreach.app/v1/campaigns/{id}/enrollments" \
-H "Authorization: Bearer $NORREACH_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"contact_ids": [
"7d1c3b2a-5e4f-4a1b-9c8d-0e1f2a3b4c5d",
"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
]
}'{
"object": "enrollment_result",
"campaign_id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
"dry_run": false,
"requested": 2,
"enrolled": 1,
"already_enrolled": 1,
"already_enrolled_ids": [
"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
],
"not_found": 0,
"not_found_ids": [],
"excluded": 0,
"held_for_approval": false,
"remaining_contact_ids": []
}Authorizations
Bearer authentication: send Authorization: Bearer <key>, with an API key or an OAuth access token. The key needs the scope campaigns:launch. API keys and scopes
Path parameters
An id (UUID).
Query parameters
Run every check and return what would happen, changing nothing.
Headers
Any unique string (≤ 255). The same key with the same request returns the first answer for 24 hours.
Body
application/json
An id (UUID).
Response
200application/json— Enroll contacts
An id (UUID).
Distinct contacts asked for.
New enrollments made (or, in a dry run, at most this many).
Ids that aren't contacts of this workspace — never enrolled.
Skipped by the campaign's own enrollment rules (recently messaged, per-company cap).
The campaign asks before it sends: each first send waits in Approvals.
Not processed this time (the request ran out of time) — send them again; already enrolled contacts are skipped.
Errors
Errors are application/problem+json with a stable code.
| Status | Code | Meaning |
|---|---|---|
| 400 | bad_request | The request couldn't be read. |
| 400 | unknown_field | The request has a field this operation doesn't know. |
| 400 | idempotency_key_required | This operation needs an Idempotency-Key header. |
| 401 | unauthorized | A valid API key is required. |
| 403 | insufficient_scope | This API key doesn't have the scope this operation needs. |
| 403 | feature_not_enabled | The API isn't switched on for this workspace. |
| 403 | role_forbidden | The key's creator's role can't do this. |
| 404 | not_found | That doesn't exist. |
| 409 | idempotency_in_progress | A request with this Idempotency-Key is still running. |
| 409 | conflict | That conflicts with the current state. |
| 409 | outreach_paused | Outreach is paused for this workspace. |
| 413 | too_large | The request body is too large. |
| 422 | validation_failed | The request has invalid fields. |
| 422 | idempotency_mismatch | This Idempotency-Key was used with a different request. |
| 429 | rate_limited | Too many requests. Slow down and try again. |
| 429 | send_cap_reached | The workspace's sending limit for now is reached. |
| 500 | server_error | Something went wrong on our side. |
| 503 | unavailable | The API isn't available right now. Try again shortly. |