Customer journeys

{
  "id": "jrny_3Ab9xK2mQ7",
  "name": "Customer journey",
  "status": "active",
  "anchorObjectId": "obj_3Ab9xK2mQ7",
  "templateKey": "b2b_saas",
  "phases": [
    {
      "id": "jph_5Bc0xJ1kP4",
      "name": "Sales",
      "color": "#DC323D",
      "kind": "object",
      "source": "own_object",
      "objectId": "obj_5Bc0xJ1kP4",
      "stagePropertyId": "prop_7Dd2xL3nR6",
      "linkPropertyId": "prop_9Ee4xM5oS8",
      "stages": [
        {
          "id": "jstg_2Ff6xN7pT0",
          "optionId": "opt_4Gg8xO9qU2",
          "name": "Proposal",
          "targetDays": 10,
          "isExit": false,
          "meetings": [
            {"eventTypeId": null, "playbookId": "pb_6Hh0xP1rV4", "label": "Pricing review", "expected": 1, "required": false}
          ],
          "tasks": [
            {"title": "Meet the economic buyer", "dueDays": 7, "autoComplete": "meeting_held", "autoCompleteConfig": null, "customerVisible": false, "requiredToExit": false}
          ]
        }
      ]
    }
  ]
}

{
  "id": "jrny_3Ab9xK2mQ7",
  "name": "Customer journey",
  "status": "active",
  "anchorObjectId": "obj_3Ab9xK2mQ7",
  "templateKey": "b2b_saas",
  "phases": [
    {
      "id": "jph_5Bc0xJ1kP4",
      "name": "Sales",
      "color": "#DC323D",
      "kind": "object",
      "source": "own_object",
      "objectId": "obj_5Bc0xJ1kP4",
      "stagePropertyId": "prop_7Dd2xL3nR6",
      "linkPropertyId": "prop_9Ee4xM5oS8",
      "stages": [
        {
          "id": "jstg_2Ff6xN7pT0",
          "optionId": "opt_4Gg8xO9qU2",
          "name": "Proposal",
          "targetDays": 10,
          "isExit": false,
          "meetings": [
            {"eventTypeId": null, "playbookId": "pb_6Hh0xP1rV4", "label": "Pricing review", "expected": 1, "required": false}
          ],
          "tasks": [
            {"title": "Meet the economic buyer", "dueDays": 7, "autoComplete": "meeting_held", "autoCompleteConfig": null, "customerVisible": false, "requiredToExit": false}
          ]
        }
      ]
    }
  ]
}

A journey is the row of phases a customer moves through: Marketing, Sales, Implementation, Success and Product, or whatever your workspace uses. Each phase reads the stage property of one object (Deals · Deal stage), or a range of options on a property the phases share (Companies · Lifecycle stage), or a Journey stage property Custral adds when there is neither. Both endpoints are read-only. The journey is set up in the app under Journeys → Setup.

Retrieve the journey

GET /v1/journey returns the phases, their stages, the meetings expected in each stage with their playbooks, and the focus tasks created when a record enters a stage. Requires the objects:read scope. A workspace that has never saved a journey gets a draft built from its objects, with id: null and status: "draft".

curl https://api.custral.com/v1/journey \
  -H "Authorization: Bearer $CUSTRAL_API_KEY"

{
  "id": "jrny_3Ab9xK2mQ7",
  "name": "Customer journey",
  "status": "active",
  "anchorObjectId": "obj_3Ab9xK2mQ7",
  "templateKey": "b2b_saas",
  "phases": [
    {
      "id": "jph_5Bc0xJ1kP4",
      "name": "Sales",
      "color": "#DC323D",
      "kind": "object",
      "source": "own_object",
      "objectId": "obj_5Bc0xJ1kP4",
      "stagePropertyId": "prop_7Dd2xL3nR6",
      "linkPropertyId": "prop_9Ee4xM5oS8",
      "stages": [
        {
          "id": "jstg_2Ff6xN7pT0",
          "optionId": "opt_4Gg8xO9qU2",
          "name": "Proposal",
          "targetDays": 10,
          "isExit": false,
          "meetings": [
            {"eventTypeId": null, "playbookId": "pb_6Hh0xP1rV4", "label": "Pricing review", "expected": 1, "required": false}
          ],
          "tasks": [
            {"title": "Meet the economic buyer", "dueDays": 7, "autoComplete": "meeting_held", "autoCompleteConfig": null, "customerVisible": false, "requiredToExit": false}
          ]
        }
      ]
    }
  ]
}

string

Where a phase’s stages come from: own_object, shared_property or journey_tracked.

string | null

The relation joining the phase’s object to the anchor. null when the phase reads the anchor itself.

boolean

Won, Lost, Churned: a record leaves the phase at this stage rather than sitting in it.

Retrieve a customer’s journey

GET /v1/records/{id}/journey returns one customer’s path: every stage they passed through across their deals, onboarding and the company record itself, with dates, and where they are now. {id} is a record on the journey’s anchor object, usually a company. Requires the records:read scope.

curl https://api.custral.com/v1/records/rec_3Ab9xK2mQ7/journey \
  -H "Authorization: Bearer $CUSTRAL_API_KEY"

{
  "journeyId": "jrny_3Ab9xK2mQ7",
  "anchorRecordId": "rec_3Ab9xK2mQ7",
  "anchorName": "Atlas Manufacturing",
  "current": {
    "phaseId": "jph_8Ii2xQ3sW6",
    "phaseName": "Success",
    "stageId": "jstg_0Jj4xR5tX8",
    "stageName": "Adopting",
    "enteredAt": "2026-09-11T00:00:00.000Z",
    "days": 34,
    "targetDays": 45
  },
  "phases": [
    {
      "phaseId": "jph_5Bc0xJ1kP4",
      "name": "Sales",
      "kind": "object",
      "enteredAt": "2026-04-10T00:00:00.000Z",
      "exitedAt": "2026-06-28T00:00:00.000Z",
      "days": 79,
      "lanes": [
        {
          "recordId": "rec_2Kk6xS7uY0",
          "label": "Atlas rollout",
          "hidden": false,
          "segments": [
            {"stageId": "jstg_2Ff6xN7pT0", "stageName": "Proposal", "enteredAt": "2026-05-13T00:00:00.000Z", "exitedAt": "2026-06-12T00:00:00.000Z", "days": 30, "targetDays": 10, "isCurrent": false}
          ]
        }
      ]
    }
  ]
}

A customer with two deals has two Sales lanes. A linked record your key’s creator cannot read comes back with hidden: true, recordId: null and the label "Hidden": its dates are kept so time in stage stays right, and its name is not. A stage property hidden from the key’s creator returns no history for that phase. A record that doesn’t exist, or that the key can’t read, is insufficient_permissions. A record that isn’t on the journey’s anchor object is journey_record_not_anchor.

SDK

const journey = await custral.journeys.retrieve();
const atlas = await custral.journeys.forRecord("rec_3Ab9xK2mQ7");

Introduction

Endpoints

Embeds & real-time

Retrieve the journey

Retrieve a customer’s journey

SDK

​Retrieve the journey

​Retrieve a customer’s journey

​SDK

Retrieve the journey

Retrieve a customer’s journey

SDK