Skip to main content
POST
Enroll a Contact in a Journey
Re-sending the same idempotencyKey returns the existing enrollment with 200 instead of creating a second one. A new enrollment returns 201. A contact the journey can’t take, such as one already active in another journey or without consent, is returned with 200, status: "skipped" and the reason in skippedReason. See Enroll contacts from your systems for a walkthrough.

Authorizations

Authorization
string
header
required

Your API key, sent as Authorization: Bearer YOUR_API_KEY

Path Parameters

key
string
required

The journey's key, such as appointment-confirmations. It is shown on the journey's Enrollment tab.

Body

application/json
idempotencyKey
string
required

Your key for this enrollment, such as a lead or appointment id. Sending it again returns the same enrollment.

Maximum string length: 255
contact
Existing contact · object
required

An existing contact by id, or contact details that are created or updated by phone number.

externalId
string | null

Another id to cancel by later. Defaults to idempotencyKey. It is also used as the contact's external id when the contact is created or updated.

Maximum string length: 255
subject
object

The record this enrollment is about, such as an appointment. The journey's conditions and texts can read these fields, and calls receive them.

params
object

Extra parameters passed to every call the journey places for this enrollment. They are also merged into subject.

subjectKey
string | null

Identifies the subject. Defaults to idempotencyKey.

Maximum string length: 255
anchorAt
string<date-time> | null

The date the journey's steps are timed from, in ISO 8601 with an offset. Overrides the anchor the journey would read from subject.

notBefore
string<date-time> | null

The earliest time the first call or text may go out. Null means as soon as calling hours allow.

Response

The enrollment already existed for this idempotencyKey, or the contact was skipped.

enrollmentId
string
required

The enrollment's id. Empty when the contact was skipped.

status
enum<string>
required

active while the journey is working the contact, ended once it finished, skipped when the contact could not be enrolled.

Available options:
active,
ended,
skipped
endedReason
string | null
required

Why the enrollment ended, such as goal_met, opted_out, cancelled, total_cap or exhausted.

skippedReason
string | null
required

Why the contact was not enrolled, in words, such as Active in another journey.

created
boolean
required

True when this request created the enrollment.

nextTouchAt
string<date-time> | null
required

When a call or text is going out right away. Null when the next step is later; it is planned when it comes due.

contact
object | null
required

The contact's time zone, when known.

Last modified on October 19, 2026