For the complete documentation index, see llms.txt. This page is also available as Markdown.

Use Cases & Bindings

List channel use cases for voice, SMS, iMessage, and email, and bind each use case to the platform service that handles its conversations.

Use cases define how a workspace uses a specific communication channel, and service bindings connect each use case to the platform service that handles its conversations. Each use case ties an approved channel setup to a named purpose - for example, an outbound voice use case for appointment reminders or an email use case for transactional notifications.

Base path: /v1/{workspace_id}/use-cases

Endpoints

Method
Path
Description

GET

/use-cases

List use cases

GET

/use-cases/ownership

List the use case IDs this workspace owns

GET

/use-cases/{use_case_id}/ownership

Get the workspace's ownership record for a use case

PUT

/use-cases/{use_case_id}/ownership

Claim ownership of a use case for the workspace

DELETE

/use-cases/{use_case_id}/ownership

Release the workspace's ownership of a use case

PUT

/use-cases/{use_case_id}/service-binding

Bind a use case to a platform service

DELETE

/use-cases/{use_case_id}/service-binding

Unbind a use case from its service

GET

/use-cases/{use_case_id}/service-binding

Get the current service binding

Use case lifecycle (create, update, delete) is managed through the channel management API (POST /v1/use-case, PUT /v1/use-case/{use_case_id}, DELETE /v1/use-case/{use_case_id}), authenticated with an OAuth2 client credential carrying the use-case:write scope on the target channel setup. See Channel Manager.

Create a Use Case

Create a use case through the channel management API. The request body is a discriminated union on the channel field: inbound_voice, outbound_voice, ringless_voicemail, and sms use cases associate a telephony setup, imessage use cases associate an iMessage setup, and email use cases associate an email setup plus a sender email address and email type (transactional or marketing).

Scope required: use-case:write on the target setup

POST /v1/use-case
Authorization: Bearer <oauth2_access_token>
Content-Type: application/json

List Use Cases

List use cases with optional filters by entity name, channel, and setup ID. Filtering by setup_id requires channel to also be specified.

Permission required: Channel.view

List channel use cases

get

List use cases with optional filters by entity_name, channel, setup_id. Requires Channel.view permission.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Query parameters
entity_namestring · nullableOptional
channelstring · enum · nullableOptionalPossible values:
setup_idstring · uuid · nullableOptional
Responses
200

Successful Response

application/json
get/v1/{workspace_id}/use-cases

Delete a Use Case

Delete a use case by ID through the channel management API. Returns 409 while phone numbers or lines are still assigned to the use case - unassign them first.

Scope required: use-case:write on the target setup

Ownership

A workspace claims ownership of a channel-manager use case before binding it to a service. Claiming requires the Channel.ManageOwnership permission (admin tier), is idempotent (re-claiming an already-owned use case returns 200), and returns 409 if another workspace already owns the use case. Releasing ownership returns 409 while any service still binds the use case - unbind first.

Service Binding

A use case can be bound to a platform service. A binding is unique per workspace for a given service and channel pair: only one use case may bind a given (service, channel) at a time.

Bind a Service

Upserts a binding for the use case. If the use case already has a binding, the prior binding is replaced. A different use case cannot bind a service and channel pair that is already bound.

Permission required: Channel.create

Bind a use case to a platform service

put

Bind this use case to a platform service in the current workspace. PUT semantics — rebinding to a different service replaces the prior binding. Inbound webhook events for the use case will resolve to this workspace; outbound dispatch from the service will route through this use case for its channel. 409 if a different use case already binds the same (service, channel) pair. 404 if the service or use case is missing or belongs to another workspace. Requires Channel.create permission.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
use_case_idstring · uuidRequired
Body
service_idstring · uuidRequired
Responses
200

Successful Response

application/json
use_case_idstring · uuidRequired
service_idstring · uuidRequired
workspace_idstring · uuidRequired
channelstring · enumRequiredPossible values:
created_atstring · date-timeRequired
updated_atstring · date-timeRequired
put/v1/{workspace_id}/use-cases/{use_case_id}/service-binding

Unbind a Service

Soft-unbinds the use case from its service. Fails if no live binding exists for the use case.

Permission required: Channel.delete

Unbind a use case from its platform service

delete

Release a use case from its bound service in this workspace. Soft-delete on the binding row. 404 if the use case is not currently bound (covers both 'never bound' and 'already unbound'). Requires Channel.delete permission.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
use_case_idstring · uuidRequired
Responses
204

Successful Response

No content

delete/v1/{workspace_id}/use-cases/{use_case_id}/service-binding

No content

Get the Service Binding

Returns the current service binding for the use case. Fails if no binding exists for the use case.

Permission required: Channel.view

Get the service binding for a use case

get

Return the platform service this use case is bound to in this workspace, or 404 if unbound. Requires Channel.view permission.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
use_case_idstring · uuidRequired
Responses
200

Successful Response

application/json
use_case_idstring · uuidRequired
service_idstring · uuidRequired
workspace_idstring · uuidRequired
channelstring · enumRequiredPossible values:
created_atstring · date-timeRequired
updated_atstring · date-timeRequired
get/v1/{workspace_id}/use-cases/{use_case_id}/service-binding

Last updated

Was this helpful?