> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cail.health/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cail.health/_mcp/server.

# Navigate a member to care

This guide walks a member from their location, through a jurisdiction-aware pathway, to a chosen provider. Every call here is a member-path call; authenticate as a member client first. See [Authentication](/api-reference/authentication).

The flow has five stages: resolve the active pathway, start a navigation session, run a pathway execution, complete the execution against a provider, then close the session.

## Step 1: Resolve the active pathway

A pathway is the routing logic that applies at a location. Resolve the one in force for the member with `GET /v1/plan-definitions/active`. Supply either coordinates or a postcode.

```bash
curl --get "$CAIL_API_BASE_URL/v1/plan-definitions/active" \
  --data-urlencode "latitude=51.5074" \
  --data-urlencode "longitude=-0.1278" \
  --header "Authorization: Bearer $CAIL_TOKEN"
```

The response carries the `planDefinitionId` and `versionId` you use in the next steps. A location outside any served jurisdiction returns `404`. For background, see [Jurisdictions](/concepts/jurisdictions).

## Step 2: Start a navigation session

A navigation session is the anonymous container for one member's journey. Start it with `POST /v1/navigation-sessions`, pinned to the pathway from Step 1.

```bash
curl --request POST "$CAIL_API_BASE_URL/v1/navigation-sessions" \
  --header "Authorization: Bearer $CAIL_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "planDefinitionId": "a1b2c3d4-e5f6-4789-9abc-def012345678",
    "devicePlatform": "ios",
    "appVersion": "4.12.0",
    "locale": "en-GB",
    "latitude": 51.5074,
    "longitude": -0.1278
  }'
```

Sessions are anonymous by design. Never send a name, contact detail, or other identifying field. Coordinates are truncated before storage.

## Step 3: Run the pathway execution

Start the execution with `POST /v1/pathway-executions`, then advance it one node at a time.

```bash
curl --request POST "$CAIL_API_BASE_URL/v1/pathway-executions" \
  --header "Authorization: Bearer $CAIL_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "planDefinitionId": "a1b2c3d4-e5f6-4789-9abc-def012345678",
    "channel": "mobile",
    "locale": "en-GB",
    "latitude": 51.5074,
    "longitude": -0.1278
  }'
```

The response includes the first node to render. Loop until you reach a terminal node:

1. Render the current node. Fetch it again at any time with `GET /v1/pathway-executions/{id}/current`.
2. Submit the member's choice with `POST /v1/pathway-executions/{id}/answers`, passing the `nodeId` and the chosen `branchCode`.
3. The response returns the next node. When it is terminal, stop.

```bash
curl --request POST "$CAIL_API_BASE_URL/v1/pathway-executions/{id}/answers" \
  --header "Authorization: Bearer $CAIL_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "nodeId": "q.acute_chest_pain", "branchCode": "yes" }'
```

## Step 4: Complete the execution

When the member selects a provider, acknowledge the completed execution with `POST /v1/pathway-executions/{id}/complete`.

```bash
curl --request POST "$CAIL_API_BASE_URL/v1/pathway-executions/{id}/complete" \
  --header "Authorization: Bearer $CAIL_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "selectedProviderId": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }'
```

## Step 5: Close the session

Finally, close the navigation session. Call `POST /v1/navigation-sessions/{id}/complete` when the member reached care, or `POST /v1/navigation-sessions/{id}/abandon` if they left the flow.

## Next steps

* To list provider options for Step 4, see [Find providers near a member](/guides/find-providers-near-a-member).
* To author the pathways this flow runs, see [Author and publish a care pathway](/guides/author-and-publish-a-care-pathway).