API reference

Workflow setup

The staff app's workflow endpoints.

The staff app's endpoints for building, testing and switching on the workflows the agent runs for signed-in patients. They need a Firebase workforce token with integrations.manage; changes need MFA. Environment API keys are not accepted. Test runs call your real connections with a sample patient but never message a patient.

Responses

Status	Meaning
`200`	Successful read or update.
`201`	Successful POST operation.
`400`	Invalid definition, or not ready to switch on.
`401`	Workforce authentication required.
`403`	Permission or MFA requirement not met, or (code BAA_REQUIRED) a test run would call a real Destination before the organization has signed its BAA.
`404`	Not found in the selected organization and environment.
`409`	Stale revision, duplicate key, a version that can no longer change, a workflow that has been live (archive it instead of deleting it), or an archived workflow (restore it before editing or switching it on).

List workflows

GET/organizations/{organizationId}/environments/{environmentId}/conversation-workflows

Every workflow and its versions, archived ones included (archivedAt). everLive says whether it has ever been switched on or run, which decides between Delete and Archive.

Staff sign-in. A Firebase ID token for a team member with integrations.manage; changes need a recent MFA sign-in. API keys aren't accepted.

Parameters

Field	Type	Description
`organizationId`Required	path · string (uuid)
`environmentId`Required	path · string (uuid)

cURL

curl "https://api.nezercare.com/organizations/ORGANIZATION_ID/environments/ENVIRONMENT_ID/conversation-workflows" \
  --request GET \
  --header "Authorization: Bearer $WORKFORCE_ID_TOKEN"

Create a workflow

POST/organizations/{organizationId}/environments/{environmentId}/conversation-workflows

Its first version is a draft.

Staff sign-in. A Firebase ID token for a team member with integrations.manage; changes need a recent MFA sign-in. API keys aren't accepted.

Parameters

Field	Type	Description
`organizationId`Required	path · string (uuid)
`environmentId`Required	path · string (uuid)

Request body

Field	Type	Description
`stableKey`Required	string	Matches `^[a-z][a-z0-9_]{1,79}$`.
`name`Required	string	1–120 characters.
`definition`Required	object	Steps run in order unless one says where to go next. Anything that changes an account (a non-GET call not marked readOnly) must come after a call that checks ownership and after a Confirm step; a call using anything the patient typed must check ownership. Both are enforced again while running.
`definition.schema`	integer	One of `2`.
`definition.category`Required	string	One of `support`, `billing`, `scheduling`, `fulfillment`.
`definition.description`Required	string	1–300 characters.Example: `Tells a patient where their order is.`.
`definition.triggerPhrases`	array of strings	Up to 20 items.
`definition.excludePhrases`	array of strings	Up to 20 items.
`definition.steps`Required	array of objects	At least 1 item.Up to 30 items.

definition.steps[] with type ask

Field	Type	Description
`id`Required	string	Matches `^[a-z][a-z0-9_]{0,39}$`.
`type`Required	string	One of `ask`.
`next`	string	Another step's id, or "end".Up to 40 characters.
`variable`Required	string	Matches `^[a-zA-Z][a-zA-Z0-9_]{0,39}$`.
`prompt`Required	string	May use {{variable}}, {{patient.email}}, {{patient.externalId}} and {{run.id}}.1–500 characters.
`format`Required	string	photos shows an upload button and saves how many files were added.One of `text`, `order_number`, `email`, `number`, `photos`.
`label`	string	Names the answer in the team's hand-off summary ("Medication: …"). Defaults to the variable name in words.1–40 characters.Example: `Medication`.

definition.steps[] with type call_api

Field	Type	Description
`id`Required	string	Matches `^[a-z][a-z0-9_]{0,39}$`.
`type`Required	string	One of `call_api`.
`next`	string	Another step's id, or "end".Up to 40 characters.
`destinationStableKey`Required	string	Matches `^[a-z][a-z0-9_]{1,79}$`.
`method`Required	string	One of `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.
`path`Required	string	Added to the connection's address; values are URL-encoded.Up to 500 characters.Example: `/orders/{{orderNumber}}`.
`body`	object	JSON for non-GET calls, up to 8,000 characters. Credentials belong on the connection.
`readOnly`	boolean	A non-GET call that only looks something up.
`select`	object
`select.listPath`Required	string	Dot path into the JSON response, like shipment.tracking.Up to 160 characters.
`select.matchPath`Required	string	Dot path into the JSON response, like shipment.tracking.Up to 160 characters.
`select.equals`Required	string	May use {{variable}}, {{patient.email}}, {{patient.externalId}} and {{run.id}}.1–200 characters.
`save`Required	array of objects	Up to 20 items.
`save[].variable`Required	string	Matches `^[a-zA-Z][a-zA-Z0-9_]{0,39}$`.
`save[].path`Required	string	Dot path into the JSON response, like shipment.tracking.Up to 160 characters.
`ownership`	object	Where the response names its patient. A record that isn't theirs reads as not found.
`ownership.emailPath`	string	Dot path into the JSON response, like shipment.tracking.Up to 160 characters.
`ownership.patientIdPath`	string	Dot path into the JSON response, like shipment.tracking.Up to 160 characters.
`contract`	string	Hold the answer to the order lookup contract (OrderLookupResponse). An answer that breaks it is treated as a failed call; no orders is treated as not found; otherwise the patient sees their latest orders as cards, and orderCount and latestOrderStatus are saved. Can't be combined with select.One of `orders_v1`.
`notFoundReply`Required	string	May use {{variable}}, {{patient.email}}, {{patient.externalId}} and {{run.id}}.1–500 characters.
`errorReply`Required	string	May use {{variable}}, {{patient.email}}, {{patient.externalId}} and {{run.id}}.1–500 characters.

definition.steps[] with type condition

Field	Type	Description
`id`Required	string	Matches `^[a-z][a-z0-9_]{0,39}$`.
`type`Required	string	One of `condition`.
`next`	string	Another step's id, or "end".Up to 40 characters.
`variable`Required	string	Matches `^[a-zA-Z][a-zA-Z0-9_]{0,39}$`.
`operator`Required	string	One of `equals`, `not_equals`, `contains`, `is_empty`, `is_not_empty`.
`value`	string	Up to 200 characters.
`then`Required	string	Another step's id, or "end".Up to 40 characters.
`else`Required	string	Another step's id, or "end".Up to 40 characters.

definition.steps[] with type confirm

Field	Type	Description
`id`Required	string	Matches `^[a-z][a-z0-9_]{0,39}$`.
`type`Required	string	One of `confirm`.
`next`	string	Another step's id, or "end".Up to 40 characters.
`prompt`Required	string	May use {{variable}}, {{patient.email}}, {{patient.externalId}} and {{run.id}}.1–500 characters.
`declineReply`Required	string	May use {{variable}}, {{patient.email}}, {{patient.externalId}} and {{run.id}}.1–500 characters.

definition.steps[] with type reply

Field	Type	Description
`id`Required	string	Matches `^[a-z][a-z0-9_]{0,39}$`.
`type`Required	string	One of `reply`.
`next`	string	Another step's id, or "end".Up to 40 characters.
`message`Required	string	May use {{variable}}, {{patient.email}}, {{patient.externalId}} and {{run.id}}.1–1000 characters.

definition.steps[] with type hand_off

Field	Type	Description
`id`Required	string	Matches `^[a-z][a-z0-9_]{0,39}$`.
`type`Required	string	One of `hand_off`.
`next`	string	Another step's id, or "end".Up to 40 characters.
`message`Required	string	May use {{variable}}, {{patient.email}}, {{patient.externalId}} and {{run.id}}.1–500 characters.
`summary`	string	May use {{variable}}, {{patient.email}}, {{patient.externalId}} and {{run.id}}.1–500 characters.
`teamAsk`	string	May use {{variable}}, {{patient.email}}, {{patient.externalId}} and {{run.id}}.1–300 characters.
`category`	string	The team that gets it; defaults to the workflow's category. clinical is the care team (a refill request, for example). The patient isn't sent a second, generic acknowledgement after this step's message; staff see an internal summary of the patient's answers at the top of the conversation.One of `support`, `billing`, `scheduling`, `fulfillment`, `clinical`.

Rename a workflow

PATCH/organizations/{organizationId}/environments/{environmentId}/conversation-workflows/{profileId}

Staff see the name; patients don't.

Staff sign-in. A Firebase ID token for a team member with integrations.manage; changes need a recent MFA sign-in. API keys aren't accepted.

Parameters

Field	Type	Description
`organizationId`Required	path · string (uuid)
`environmentId`Required	path · string (uuid)
`profileId`Required	path · string (uuid)

Request body

Field	Type	Description
`name`Required	string	1–120 characters.

Delete a workflow

DELETE/organizations/{organizationId}/environments/{environmentId}/conversation-workflows/{profileId}

Only one that has never been live, with its drafts and their test results. Audited. One that has been live is refused with 409: archive it instead.

Staff sign-in. A Firebase ID token for a team member with integrations.manage; changes need a recent MFA sign-in. API keys aren't accepted.

Parameters

Field	Type	Description
`organizationId`Required	path · string (uuid)
`environmentId`Required	path · string (uuid)
`profileId`Required	path · string (uuid)

cURL

curl "https://api.nezercare.com/organizations/ORGANIZATION_ID/environments/ENVIRONMENT_ID/conversation-workflows/PROFILE_ID" \
  --request DELETE \
  --header "Authorization: Bearer $WORKFORCE_ID_TOKEN"

Archive a workflow

POST/organizations/{organizationId}/environments/{environmentId}/conversation-workflows/{profileId}/archive

For one that has been live: it's switched off, out of the list and never matched, with its versions and runs kept. Audited.

Staff sign-in. A Firebase ID token for a team member with integrations.manage; changes need a recent MFA sign-in. API keys aren't accepted.

Parameters

Field	Type	Description
`organizationId`Required	path · string (uuid)
`environmentId`Required	path · string (uuid)
`profileId`Required	path · string (uuid)

cURL

curl "https://api.nezercare.com/organizations/ORGANIZATION_ID/environments/ENVIRONMENT_ID/conversation-workflows/PROFILE_ID/archive" \
  --request POST \
  --header "Authorization: Bearer $WORKFORCE_ID_TOKEN"

Restore a workflow

POST/organizations/{organizationId}/environments/{environmentId}/conversation-workflows/{profileId}/restore

Brings an archived workflow back, still switched off. Audited.

Staff sign-in. A Firebase ID token for a team member with integrations.manage; changes need a recent MFA sign-in. API keys aren't accepted.

Parameters

Field	Type	Description
`organizationId`Required	path · string (uuid)
`environmentId`Required	path · string (uuid)
`profileId`Required	path · string (uuid)

cURL

curl "https://api.nezercare.com/organizations/ORGANIZATION_ID/environments/ENVIRONMENT_ID/conversation-workflows/PROFILE_ID/restore" \
  --request POST \
  --header "Authorization: Bearer $WORKFORCE_ID_TOKEN"

Create or reuse a draft

POST/organizations/{organizationId}/environments/{environmentId}/conversation-workflows/{profileId}/draft

Without interrupting the live version.

Staff sign-in. A Firebase ID token for a team member with integrations.manage; changes need a recent MFA sign-in. API keys aren't accepted.

Parameters

Field	Type	Description
`organizationId`Required	path · string (uuid)
`environmentId`Required	path · string (uuid)
`profileId`Required	path · string (uuid)

cURL

curl "https://api.nezercare.com/organizations/ORGANIZATION_ID/environments/ENVIRONMENT_ID/conversation-workflows/PROFILE_ID/draft" \
  --request POST \
  --header "Authorization: Bearer $WORKFORCE_ID_TOKEN"

Switch a workflow off

POST/organizations/{organizationId}/environments/{environmentId}/conversation-workflows/{profileId}/deactivate

Staff sign-in. A Firebase ID token for a team member with integrations.manage; changes need a recent MFA sign-in. API keys aren't accepted.

Parameters

Field	Type	Description
`organizationId`Required	path · string (uuid)
`environmentId`Required	path · string (uuid)
`profileId`Required	path · string (uuid)

cURL

curl "https://api.nezercare.com/organizations/ORGANIZATION_ID/environments/ENVIRONMENT_ID/conversation-workflows/PROFILE_ID/deactivate" \
  --request POST \
  --header "Authorization: Bearer $WORKFORCE_ID_TOKEN"

List recent runs

GET/organizations/{organizationId}/environments/{environmentId}/conversation-workflows/{profileId}/runs

Step by step: outcomes only, never values.

Staff sign-in. A Firebase ID token for a team member with integrations.manage; changes need a recent MFA sign-in. API keys aren't accepted.

Parameters

Field	Type	Description
`organizationId`Required	path · string (uuid)
`environmentId`Required	path · string (uuid)
`profileId`Required	path · string (uuid)

cURL

curl "https://api.nezercare.com/organizations/ORGANIZATION_ID/environments/ENVIRONMENT_ID/conversation-workflows/PROFILE_ID/runs" \
  --request GET \
  --header "Authorization: Bearer $WORKFORCE_ID_TOKEN"

Save a draft

PUT/organizations/{organizationId}/environments/{environmentId}/conversation-workflows/versions/{versionId}

Saves the current draft revision.

Staff sign-in. A Firebase ID token for a team member with integrations.manage; changes need a recent MFA sign-in. API keys aren't accepted.

Parameters

Field	Type	Description
`organizationId`Required	path · string (uuid)
`environmentId`Required	path · string (uuid)
`versionId`Required	path · string (uuid)

Request body

Field	Type	Description
`expectedRevision`Required	integer	At least 1.
`definition`Required	object	Steps run in order unless one says where to go next. Anything that changes an account (a non-GET call not marked readOnly) must come after a call that checks ownership and after a Confirm step; a call using anything the patient typed must check ownership. Both are enforced again while running.
`definition.schema`	integer	One of `2`.
`definition.category`Required	string	One of `support`, `billing`, `scheduling`, `fulfillment`.
`definition.description`Required	string	1–300 characters.Example: `Tells a patient where their order is.`.
`definition.triggerPhrases`	array of strings	Up to 20 items.
`definition.excludePhrases`	array of strings	Up to 20 items.
`definition.steps`Required	array of objects	At least 1 item.Up to 30 items.

definition.steps[] with type ask

As in Create a workflow.

definition.steps[] with type call_api

As in Create a workflow.

definition.steps[] with type condition

As in Create a workflow.

definition.steps[] with type confirm

As in Create a workflow.

definition.steps[] with type reply

As in Create a workflow.

definition.steps[] with type hand_off

As in Create a workflow.

Discard a draft

DELETE/organizations/{organizationId}/environments/{environmentId}/conversation-workflows/versions/{versionId}

Discards the draft on top of a live (or last live) version; that version is untouched. Audited. A workflow's only draft is deleted with the workflow instead.

Staff sign-in. A Firebase ID token for a team member with integrations.manage; changes need a recent MFA sign-in. API keys aren't accepted.

Parameters

Field	Type	Description
`organizationId`Required	path · string (uuid)
`environmentId`Required	path · string (uuid)
`versionId`Required	path · string (uuid)

cURL

curl "https://api.nezercare.com/organizations/ORGANIZATION_ID/environments/ENVIRONMENT_ID/conversation-workflows/versions/VERSION_ID" \
  --request DELETE \
  --header "Authorization: Bearer $WORKFORCE_ID_TOKEN"

Check readiness

GET/organizations/{organizationId}/environments/{environmentId}/conversation-workflows/versions/{versionId}/readiness

What still blocks switching this version on.

Staff sign-in. A Firebase ID token for a team member with integrations.manage; changes need a recent MFA sign-in. API keys aren't accepted.

Parameters

Field	Type	Description
`organizationId`Required	path · string (uuid)
`environmentId`Required	path · string (uuid)
`versionId`Required	path · string (uuid)

cURL

curl "https://api.nezercare.com/organizations/ORGANIZATION_ID/environments/ENVIRONMENT_ID/conversation-workflows/versions/VERSION_ID/readiness" \
  --request GET \
  --header "Authorization: Bearer $WORKFORCE_ID_TOKEN"

Test a version

POST/organizations/{organizationId}/environments/{environmentId}/conversation-workflows/versions/{versionId}/test

Runs a saved version with a sample patient; returns the transcript and each step's request and response.

Staff sign-in. A Firebase ID token for a team member with integrations.manage; changes need a recent MFA sign-in. API keys aren't accepted.

Parameters

Field	Type	Description
`organizationId`Required	path · string (uuid)
`environmentId`Required	path · string (uuid)
`versionId`Required	path · string (uuid)

Request body

Field	Type	Description
`expectedRevision`Required	integer	At least 1.
`opening`Required	string	1–2000 characters.Example: `Where is my order?`.
`replies`Required	array of strings	Up to 20 items.
`patientEmail`	string	The sample patient's email, for ownership checks and {{patient.email}}.Up to 200 characters.
`patientId`	string	Or the sample patient's ID in your system; also sent as {{patient.externalId}} (order lookups use it).Up to 200 characters.

Switch a version on

POST/organizations/{organizationId}/environments/{environmentId}/conversation-workflows/versions/{versionId}/activate

Only a draft that passed a test within 24 hours.

Staff sign-in. A Firebase ID token for a team member with integrations.manage; changes need a recent MFA sign-in. API keys aren't accepted.

Parameters

Field	Type	Description
`organizationId`Required	path · string (uuid)
`environmentId`Required	path · string (uuid)
`versionId`Required	path · string (uuid)

Request body

Field	Type	Description
`expectedRevision`Required	integer	At least 1.