Guides

Navigate a member to care

Run a pathway from location to a chosen provider
View as MarkdownOpen in Claude

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.

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.

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

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.

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

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

$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