> ## Documentation Index
> Fetch the complete documentation index at: https://docs.custral.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer journeys

> The workspace's customer journey, and where each customer is in it.

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"`.

```bash theme={null}
curl https://api.custral.com/v1/journey \
  -H "Authorization: Bearer $CUSTRAL_API_KEY"
```

<ResponseExample>
  ```json The journey theme={null}
  {
    "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}
            ]
          }
        ]
      }
    ]
  }
  ```
</ResponseExample>

<ResponseField name="source" type="string">
  Where a phase's stages come from: `own_object`, `shared_property` or `journey_tracked`.
</ResponseField>

<ResponseField name="linkPropertyId" type="string | null">
  The relation joining the phase's object to the anchor. `null` when the phase reads the anchor itself.
</ResponseField>

<ResponseField name="isExit" type="boolean">
  Won, Lost, Churned: a record leaves the phase at this stage rather than sitting in it.
</ResponseField>

## 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.

```bash theme={null}
curl https://api.custral.com/v1/records/rec_3Ab9xK2mQ7/journey \
  -H "Authorization: Bearer $CUSTRAL_API_KEY"
```

<ResponseExample>
  ```json A customer's journey theme={null}
  {
    "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}
            ]
          }
        ]
      }
    ]
  }
  ```
</ResponseExample>

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

```ts theme={null}
const journey = await custral.journeys.retrieve();
const atlas = await custral.journeys.forRecord("rec_3Ab9xK2mQ7");
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.