Skip to content
HeyX API

Set Customer Journey Status

Required scope: journey:write

Sets a customer’s status on one journey track. Get the trackId and statusId from List Journey Config. A customer holds at most one status per track, so this replaces any current status on the track.

The outcome depends on the status’s statusChangeMode:

  • manual — the status is applied immediately and applied is true.
  • approval — an approval request is opened or advanced. If your vote satisfies the required approvals the change applies and applied is true; otherwise pendingApproval is true and the returned customer’s status is unchanged until enough approvals are recorded.
  • automation_only — the status can only be set by automation. The request is rejected with failed_precondition.

A request is also rejected with failed_precondition when the track is blocked for the customer, for example by an open problem that gates progression.

The response always returns the customer as seen after the request. In the pendingApproval case that customer still shows its previous status.

Generated Reference
POST /public-api/publicapi.v1.Customer/SetCustomerJourneyStatus

Sets a customer's status on a journey track. Manual-mode statuses apply immediately; approval-mode statuses open an approval request instead of applying, so check applied and pending_approval in the response. automation_only statuses are rejected.

Request SetCustomerJourneyStatusRequest
Response SetCustomerJourneyStatusResponse

SetCustomerJourneyStatusRequest

Field Type Description
customer_id string Customer whose journey status is being set.
track_id string Journey track the status belongs to.
status_id string Status to set on the track, from ListJourneyConfig.

SetCustomerJourneyStatusResponse

Field Type Description
customer Customer The customer after the request. In approval mode the status is unchanged.
applied bool True when the status was applied immediately.
pending_approval bool True when an approval request was opened or advanced instead of applying.

Related Types

Customer

Field Type Description
id string
title string
custom_fields map<string, string> Name-keyed compatibility representation; keys are not internal UUIDs.
reference_number string
created_at int64
updated_at int64

Request

Section titled “Request”
{
  "customerId": "be85f4d1-b680-4964-bf62-9828fdf4ce04",
  "trackId": "4c3c9f2e-6d21-4a0b-9d0f-2b1e7c8a4d10",
  "statusId": "b1f0a7d4-2c88-4e13-9a5e-6d9f0c2b3a41"
}

Response

Section titled “Response”
{
  "customer": {
    "id": "be85f4d1-b680-4964-bf62-9828fdf4ce04",
    "title": "Solar installation lead",
    "referenceNumber": "P-000456"
  },
  "applied": true,
  "pendingApproval": false
}
HeyX API