Skip to main content

Journeys API

Marketing automation journeys, step management, and enrollments.

List Journeys​

GET /journeys

Query Parameters

ParameterTypeDescription
tenantIdstringRequired
statusstringDRAFT, ACTIVE, PAUSED, ARCHIVED
triggerTypestringFilter by trigger event type

Response: 200 OK

{
  "data": [{
    "id": "journey_123",
    "name": "New Member Onboarding",
    "status": "ACTIVE",
    "triggerType": "scl.member.created",
    "totalEnrolled": 150,
    "totalCompleted": 120,
    "totalExited": 10,
    "stepsCount": 5,
    "activatedAt": "2025-11-01T00:00:00Z"
  }]
}

Get Journey​

GET /journeys/:id

Query Parameters

ParameterTypeDescription
includestringComma-separated: steps, enrollments

Response: 200 OK

{
  "id": "journey_123",
  "tenantId": "tenant_123",
  "name": "New Member Onboarding",
  "description": "Welcome sequence for new members",
  "status": "ACTIVE",
  "triggerType": "scl.member.created",
  "triggerConfig": {
    "conditions": [
      { "field": "membershipTier", "operator": "in", "value": ["Gold", "Platinum"] }
    ]
  },
  "allowReentry": false,
  "timezone": "Africa/Johannesburg",
  "totalEnrolled": 150,
  "totalCompleted": 120,
  "totalExited": 10,
  "activeEnrollments": 20,
  "activatedAt": "2025-11-01T00:00:00Z",
  "createdBy": "user_123",
  "createdAt": "2025-10-15T00:00:00Z",
  "updatedAt": "2025-12-14T10:00:00Z"
}

Create Journey​

POST /journeys

Request Body

{
  "tenantId": "tenant_123",
  "name": "New Member Onboarding",
  "description": "Welcome sequence for new members",
  "triggerType": "scl.member.created",
  "triggerConfig": {
    "conditions": [
      { "field": "membershipTier", "operator": "in", "value": ["Gold", "Platinum"] }
    ]
  },
  "allowReentry": false,
  "timezone": "Africa/Johannesburg"
}

Response: 201 Created

Update Journey​

PATCH /journeys/:id

Request Body

{
  "name": "Updated Journey Name",
  "description": "Updated description"
}

Response: 200 OK

Note: ACTIVE journeys have limited editable fields.

Delete Journey​

DELETE /journeys/:id

Response: 204 No Content

Note: Only DRAFT journeys can be deleted. Active journeys must be archived.

Journey Lifecycle​

Activate Journey​

POST /journeys/:id/activate

Response: 200 OK

{
  "id": "journey_123",
  "status": "ACTIVE",
  "activatedAt": "2025-12-14T10:00:00Z"
}

Requirements: Journey must have at least one step.

Pause Journey​

POST /journeys/:id/pause

Response: 200 OK

{
  "id": "journey_123",
  "status": "PAUSED",
  "pausedAt": "2025-12-14T10:00:00Z",
  "activeEnrollments": 20
}

Note: Pausing stops new enrollments and pauses step execution.

Resume Journey​

POST /journeys/:id/resume

Response: 200 OK

{
  "id": "journey_123",
  "status": "ACTIVE",
  "resumedAt": "2025-12-14T10:00:00Z"
}

Archive Journey​

POST /journeys/:id/archive

Response: 200 OK

{
  "id": "journey_123",
  "status": "ARCHIVED",
  "archivedAt": "2025-12-14T10:00:00Z",
  "exitedEnrollments": 20
}

Note: Archiving exits all active enrollments.

Journey Steps​

Get Journey Steps​

GET /journeys/:id/steps

Response: 200 OK

{
  "data": [
    {
      "id": "step_1",
      "stepNumber": 1,
      "type": "SEND",
      "name": "Welcome Email",
      "config": { "channel": "EMAIL", "templateId": "welcome_email" },
      "nextStepId": "step_2"
    },
    {
      "id": "step_2",
      "stepNumber": 2,
      "type": "WAIT",
      "name": "Wait 3 days",
      "config": { "duration": "3 days" },
      "nextStepId": "step_3"
    },
    {
      "id": "step_3",
      "stepNumber": 3,
      "type": "CONDITION",
      "name": "Check if opened",
      "config": {
        "rules": [{ "field": "lastEmailOpenAt", "operator": "isNotNull" }]
      },
      "nextStepYesId": "step_4",
      "nextStepNoId": "step_5"
    }
  ]
}

Add Journey Step​

POST /journeys/:id/steps

Request Body

{
  "type": "SEND",
  "name": "Follow-up Email",
  "config": {
    "channel": "EMAIL",
    "templateId": "followup_email"
  },
  "afterStepId": "step_2"
}

Response: 201 Created

Update Journey Step​

PATCH /journeys/:journeyId/steps/:stepId

Request Body

{
  "name": "Updated Step Name",
  "config": {
    "channel": "EMAIL",
    "templateId": "new_template"
  }
}

Response: 200 OK

Delete Journey Step​

DELETE /journeys/:journeyId/steps/:stepId

Response: 204 No Content

Reorder Steps​

POST /journeys/:id/steps/reorder

Request Body

{
  "stepIds": ["step_1", "step_3", "step_2", "step_4"]
}

Response: 200 OK

Step Types​

TRIGGER​

Entry point for the journey.

{
  "type": "TRIGGER",
  "name": "Member Created",
  "config": {
    "eventType": "scl.member.created",
    "conditions": [
      { "field": "membershipTier", "operator": "in", "value": ["Gold", "Platinum"] }
    ]
  }
}

SEND​

Sends a message via a channel.

{
  "type": "SEND",
  "name": "Welcome Email",
  "config": {
    "channel": "EMAIL",
    "templateId": "welcome_email"
  }
}

WAIT​

Delays progression for a duration.

{
  "type": "WAIT",
  "name": "Wait 3 days",
  "config": {
    "duration": "3 days"
  }
}

Supported formats: 30 minutes, 2 hours, 3 days, 1 week.

CONDITION​

Branches based on customer data.

{
  "type": "CONDITION",
  "name": "Check Engagement",
  "config": {
    "combinator": "AND",
    "rules": [
      { "field": "engagementScore", "operator": "gte", "value": 70 },
      { "field": "emailOptIn", "operator": "eq", "value": true }
    ]
  },
  "nextStepYesId": "step_engaged",
  "nextStepNoId": "step_not_engaged"
}

SPLIT​

A/B testing split.

{
  "type": "SPLIT",
  "name": "A/B Test",
  "config": {
    "splits": [
      { "percentage": 50, "nextStepId": "step_variant_a" },
      { "percentage": 50, "nextStepId": "step_variant_b" }
    ]
  }
}

UPDATE​

Updates customer profile.

{
  "type": "UPDATE",
  "name": "Tag as Onboarded",
  "config": {
    "updates": [
      { "field": "tags", "action": "add", "value": "onboarded" }
    ]
  }
}

END​

Marks journey completion.

{
  "type": "END",
  "name": "Journey Complete"
}

Enrollments​

Get Journey Enrollments​

GET /journeys/:id/enrollments

Query Parameters

ParameterTypeDescription
statusstringACTIVE, COMPLETED, EXITED, FAILED
skipnumberOffset
takenumberLimit

Response: 200 OK

{
  "data": [{
    "id": "enrollment_123",
    "customerId": "customer_456",
    "customerName": "John Smith",
    "customerEmail": "john@example.com",
    "status": "ACTIVE",
    "currentStepNumber": 3,
    "currentStepName": "Wait 3 days",
    "waitingUntil": "2025-12-17T09:00:00Z",
    "enrolledAt": "2025-12-14T09:00:00Z"
  }],
  "meta": { "total": 150, "skip": 0, "take": 25 }
}

Manually Enroll Customer​

POST /journeys/:id/enrollments

Request Body

{
  "customerId": "customer_123"
}

Response: 201 Created

{
  "id": "enrollment_456",
  "journeyId": "journey_123",
  "customerId": "customer_123",
  "status": "ACTIVE",
  "currentStepNumber": 1,
  "enrolledAt": "2025-12-14T10:00:00Z"
}

Exit Customer from Journey​

DELETE /journeys/:journeyId/enrollments/:customerId

Response: 204 No Content

Get Enrollment Details​

GET /journeys/:journeyId/enrollments/:enrollmentId

Response: 200 OK

{
  "id": "enrollment_123",
  "journeyId": "journey_456",
  "customerId": "customer_789",
  "status": "ACTIVE",
  "currentStepNumber": 3,
  "enrolledAt": "2025-12-14T09:00:00Z",
  "steps": [
    {
      "stepId": "step_1",
      "stepName": "Welcome Email",
      "status": "COMPLETED",
      "startedAt": "2025-12-14T09:00:00Z",
      "completedAt": "2025-12-14T09:00:05Z"
    },
    {
      "stepId": "step_2",
      "stepName": "Wait 3 days",
      "status": "COMPLETED",
      "startedAt": "2025-12-14T09:00:05Z",
      "completedAt": "2025-12-17T09:00:00Z"
    },
    {
      "stepId": "step_3",
      "stepName": "Check if opened",
      "status": "ACTIVE",
      "startedAt": "2025-12-17T09:00:00Z"
    }
  ]
}