API docs

Appearance

On this page

Journeys beta ​

Journeys allow you to create automated sequences of actions for your contacts. The API allows you to programmatically enroll contacts in journeys.

Endpoints ​

POST /v1/journeys/:id/enroll

Enroll contacts in a journey ​

POST /v1/journeys/:id/enroll

Enrolls one or more contacts in a journey. You can enroll contacts by providing individual email addresses or by specifying lists to enroll all members of those lists. This endpoint enables external systems to trigger journey enrollments programmatically without needing to use the Workshop UI.

Requirements ​

  • The journey must be in the on state
  • Contacts must be active in your company
  • Contacts cannot be currently enrolled in the journey
  • Contacts cannot have completed the journey within the last 12 hours

Parameters ​

NameRequiredTypeDescription
idrequiredstringThe ID of the journey to enroll contacts in.
contact_email_addressesoptionalarray[string]An array of contact email addresses to enroll (max 1000).
list_email_addressesoptionalarray[string]An array of list email addresses to enroll all members of those lists (max 100).

At least one of contact_email_addresses or list_email_addresses must be provided.

Example payloads

Enroll individual contacts:

json
{
  "contact_email_addresses": [
    "user1@example.com",
    "user2@example.com",
    "user3@example.com"
  ]
}

Enroll all members of lists:

json
{
  "list_email_addresses": [
    "team@company.com",
    "engineering@company.com"
  ]
}

Combine both methods:

json
{
  "contact_email_addresses": ["user1@example.com"],
  "list_email_addresses": ["team@company.com"]
}

Returns ​

A response object containing a count of enrolled contacts and information about which contacts were not enrolled, along with reasons.

FieldTypeDescription
enrolled_countintegerThe number of contacts that were successfully enrolled.
not_enrolled.not_foundarray[string]Email addresses that don't match any active contact.
not_enrolled.already_enrolledarray[string]Email addresses of contacts already enrolled in this journey.
not_enrolled.recently_completedarray[string]Email addresses of contacts who completed the journey within 12 hours.
Example responses

Success response (200)

json
{
  "enrolled_count": 2,
  "not_enrolled": {
    "not_found": ["unknown@example.com"],
    "already_enrolled": ["already.in@example.com"],
    "recently_completed": ["just.finished@example.com"]
  }
}

Error response - Journey not found (404)

json
{
  "error": "Journey not found"
}

Error response - Journey not active (422)

json
{
  "error": "Journey must be in 'on' state to enroll people. Current state: draft"
}

Error response - No emails provided (422)

json
{
  "error": {
    "base": ["at least one of contact_email_addresses or list_email_addresses must be provided"]
  }
}

Error response - List not found (422)

json
{
  "error": "No list found with email address: nonexistent@company.com"
}

Error response - Multiple lists with same email (422)

json
{
  "error": "Multiple lists (2) found with email address: duplicate@company.com. Please ensure each list has a unique email address."
}

Errors ​

CodeDescription
401Unauthorized - Invalid or missing API token.
404Journey not found or does not belong to your company.
422Invalid request - journey is not in on state, list not found, or invalid parameters.

Notes ​

  • Email addresses are automatically normalized (trimmed of whitespace and lowercased)
  • Duplicate contacts (whether from contact_email_addresses or across multiple lists) are deduplicated
  • If no contacts can be enrolled, the endpoint still returns a 200 response with enrolled_count: 0
  • The not_enrolled.not_found array only includes emails from contact_email_addresses that weren't found - it does not report on individual list members