Skip to content
Norbelys
Esc
↑↓navigate↵open⌘Jpreview

Enroll people into a campaign.

Up to 100 at once (201), more through a job (202). Unknown people, suppressed addresses and people already enrolled are skipped.

POST/v1/enrollments
Authorization
AuthorizationBearer token · headerrequired

An API key (nb_live_…, nb_test_…), a workspace token (nbs_…) or a CLI token (nbc_…).

Header parameters
Idempotency-Keystringrequired

A stable key for this logical request; reuse it when retrying.

min length 1 · max length 128 · matches ^[!-~]+$
Request body
requiredapplication/json
campaign_idstringrequired

The campaign (cmp_…).

emailsstring[] | null

People by address, at most 1,000; an address that is no person of the workspace is skipped.

group_idstring | null

A group's members (grp_…).

person_idsstring[] | null

People by id (per_…), at most 1,000.

segment_idstring | null

The people a segment matches (seg_…).

Responses
201

Up to 100 people: the enrollments made and the people skipped.

dataEnrollmentObject[]required

The enrollments created.

max items 100
Show properties
Array of EnrollmentObject
campaign_idId_Campaignrequired
matches ^cmp_[0-9a-f]{32}$
created_atTimestamprequired
idId_Enrollmentrequired
matches ^enr_[0-9a-f]{32}$
message_idId_Message | null
Show properties
One of:
Id_Message
string
null
null
next_run_atTimestamp | null
Show properties
One of:
Timestamp
string<date-time>
null
null
personPersonRefrequired

The person an enrollment is for.

Show properties
emailstringrequired
idId_Personrequired
matches ^per_[0-9a-f]{32}$
namestring | null

The given and family names, when the person has either.

positioninteger<int32>required

The step it is at, 1 for the first.

sender_identity_idId_SenderIdentity | null
Show properties
One of:
Id_SenderIdentity
string
null
null
statusEnrollmentStatusrequired

An enrollment's lifecycle (enrollments.status).

Allowed:activepausedcompletedrepliedstoppedfailed
status_detailstring | null

Why it ended, when it ended early.

updated_atTimestamprequired
waiting_forId_SenderIdentity | null
Show properties
One of:
Id_SenderIdentity
string
null
null
skippedSkipped[]required

The people that were not enrolled, and why.

max items 100
Show properties
Array of Skipped
emailstring | null

The address, when the request named the person by it.

person_idId_Person | null
Show properties
One of:
Id_Person
string
null
null
reasonSkipReasonrequired

Why a person was not enrolled.

Allowed:not_foundsuppressedalready_enrolled
202

More than 100 people: the enrollment.add job; Location names it.

attemptsinteger<int32>required

Failed runs so far; a yield is not a failure.

cancel_requested_atTimestamp | null
Show properties
One of:
Timestamp
string<date-time>
null
null
created_atTimestamprequired
finished_atTimestamp | null
Show properties
One of:
Timestamp
string<date-time>
null
null
idId_Jobrequired
matches ^job_[0-9a-f]{32}$
kindstringrequired

The kind of work, such as enrollment.add. New kinds may be added.

last_errorLastError | null
Show properties
One of:
LastError
atTimestamprequired

When the job's row last changed: the moment of the error for a job that ended, and at or after it while the job is still waiting or running (the row keeps no separate time for its error).

codestringrequired

A short machine-readable code (error, lease_expired, unknown_kind, cancelled, …).

detailstringrequired

A human-readable explanation.

null
null
progressany

What the job has done so far, as its last checkpoint recorded it.

resultany

The job's bounded result, once it completed (at most 64 KiB).

stateJobStaterequired

Where a job is (jobs.state): available while it waits for its run, running, then completed, failed or cancelled; needs_review when an operator decides whether an ambiguous external effect happened.

Allowed:availablerunningcompletedfailedcancelledneeds_review
updated_atTimestamprequired
401

No valid credential.

codeProblemCoderequired

The closed registry of problem codes: programs branch on a problem's code, never on its text. A code may be added, never repurposed.

Allowed:invalid_requestunauthorizedforbiddensession_requirednot_foundarchivedmethod_not_allowedconflictinvalid_stateidempotency_in_progressprecondition_failedpayload_too_largeunsupported_media_typevalidation_failedidempotency_mismatchsuppressedcaptcha_failedinsufficient_scoperate_limitedquota_exceededinternal_errorservice_unavailabletimeout
detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties
Array of FieldError
codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0
statusinteger<int32>required

The HTTP status.

min 0
titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

403

The credential lacks campaigns:write.

codeProblemCoderequired

The closed registry of problem codes: programs branch on a problem's code, never on its text. A code may be added, never repurposed.

Allowed:invalid_requestunauthorizedforbiddensession_requirednot_foundarchivedmethod_not_allowedconflictinvalid_stateidempotency_in_progressprecondition_failedpayload_too_largeunsupported_media_typevalidation_failedidempotency_mismatchsuppressedcaptcha_failedinsufficient_scoperate_limitedquota_exceededinternal_errorservice_unavailabletimeout
detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties
Array of FieldError
codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0
statusinteger<int32>required

The HTTP status.

min 0
titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

404

No such campaign, group or segment in this workspace.

codeProblemCoderequired

The closed registry of problem codes: programs branch on a problem's code, never on its text. A code may be added, never repurposed.

Allowed:invalid_requestunauthorizedforbiddensession_requirednot_foundarchivedmethod_not_allowedconflictinvalid_stateidempotency_in_progressprecondition_failedpayload_too_largeunsupported_media_typevalidation_failedidempotency_mismatchsuppressedcaptcha_failedinsufficient_scoperate_limitedquota_exceededinternal_errorservice_unavailabletimeout
detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties
Array of FieldError
codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0
statusinteger<int32>required

The HTTP status.

min 0
titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

409

The campaign is archived (invalid_state).

codeProblemCoderequired

The closed registry of problem codes: programs branch on a problem's code, never on its text. A code may be added, never repurposed.

Allowed:invalid_requestunauthorizedforbiddensession_requirednot_foundarchivedmethod_not_allowedconflictinvalid_stateidempotency_in_progressprecondition_failedpayload_too_largeunsupported_media_typevalidation_failedidempotency_mismatchsuppressedcaptcha_failedinsufficient_scoperate_limitedquota_exceededinternal_errorservice_unavailabletimeout
detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties
Array of FieldError
codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0
statusinteger<int32>required

The HTTP status.

min 0
titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

422

The body is invalid, or names no source of people or more than one.

codeProblemCoderequired

The closed registry of problem codes: programs branch on a problem's code, never on its text. A code may be added, never repurposed.

Allowed:invalid_requestunauthorizedforbiddensession_requirednot_foundarchivedmethod_not_allowedconflictinvalid_stateidempotency_in_progressprecondition_failedpayload_too_largeunsupported_media_typevalidation_failedidempotency_mismatchsuppressedcaptcha_failedinsufficient_scoperate_limitedquota_exceededinternal_errorservice_unavailabletimeout
detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties
Array of FieldError
codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0
statusinteger<int32>required

The HTTP status.

min 0
titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

Try it
Server
Authorization
Parameters
Bodyapplication/json
Request
curl -X POST 'https://api.norbelys.com/v1/enrollments' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Idempotency-Key: string' \
  -H 'Content-Type: application/json' \
  -d '{
  "campaign_id": "cmp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4",
  "group_id": "grp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4"
}'
Response
{
  "data": [
    {
      "campaign_id": "cmp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4",
      "created_at": "2019-08-24T14:15:22Z",
      "id": "enr_0190f8a2b4c87a10b6d2e4f6a8c0e2f4",
      "message_id": "msg_0190f8a2b4c87a10b6d2e4f6a8c0e2f4",
      "next_run_at": "2019-08-24T14:15:22Z",
      "person": {
        "email": "string",
        "id": "per_0190f8a2b4c87a10b6d2e4f6a8c0e2f4",
        "name": "string"
      },
      "position": 0,
      "sender_identity_id": "sid_0190f8a2b4c87a10b6d2e4f6a8c0e2f4",
      "status": "active",
      "status_detail": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "waiting_for": "sid_0190f8a2b4c87a10b6d2e4f6a8c0e2f4"
    }
  ],
  "skipped": [
    {
      "email": "string",
      "person_id": "per_0190f8a2b4c87a10b6d2e4f6a8c0e2f4",
      "reason": "not_found"
    }
  ]
}