Tickets

Base URL: $BUSINESS_API

The object

idstring · optional
tenant_idstring · optional
customer_idstring · optional
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

account_idstring · optional
account_numberstring · optional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · optional

Display name of the customer who holds the referenced account. Omitted when unknown.

categorystring · optional
subjectstring · optional
statusstring · optional
The object
{
  "id": "sup_2AubVo0zrAeLjY6td0mzN2sbbOI",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "category": "category",
  "subject": "Fuga na Rua 3",
  "status": "active"
}

List support tickets and service requests

Logs

GET /tickets

Returns the tenant's support tickets in cursor pages (limit up to 100, 20 by default, after for the next page). Query parameters customer_id, account_id, category, status and assigned_to filter exactly, and q searches ticket text and matching account holders. Requires support:read.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Support tickets

Show attributes
dataarray of SupportTicket · required
Show child attributes
idstring · optional
tenant_idstring · optional
customer_idstring · optional
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

account_idstring · optional
account_numberstring · optional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · optional

Display name of the customer who holds the referenced account. Omitted when unknown.

categorystring · optional
subjectstring · optional
statusstring · optional
has_moreboolean · required
next_cursorstring · optional

Errors 403

Permissions support:read · Roles: admin, analyst, customer_service, owner, viewer

curl -X GET "$BUSINESS_API/tickets" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "sup_2AubVo0zrAeLjY6td0mzN2sbbOI",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
      "customer_name": "Ana Matsinhe",
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "account_number": "ACC-2026-000142",
      "account_holder_name": "Ana Matsinhe",
      "category": "category",
      "subject": "Fuga na Rua 3",
      "status": "active"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Open a support ticket, optionally on behalf of a customer

Logs

POST /tickets

Requires support:write. customer_id and account_id must be records of this utility; a ticket naming an account is visible to consumers linked to that account.

Body application/json

customer_idstring · optional
account_idstring · optional
categorystring · optional
subjectstring · required
descriptionstring · required
prioritystring · optional

Returns

201 Support ticket created

Errors 400 · 403

Permissions support:write · Roles: admin, customer_service, owner

curl -X POST "$BUSINESS_API/tickets" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "category": "category",
  "subject": "Fuga na Rua 3",
  "description": "Leitura confirmada no local.",
  "priority": "priority"
}'
Response 201

Support ticket created

Get support ticket details

Logs

GET /tickets/{id}

Returns one ticket with its subject, description, category, priority, status, assignee and resolution. Returns 404 when the ticket is not in the caller's tenant; requires support:read.

Parameters

idstring · path · required

ID of the support ticket in the caller's tenant.

Returns

200 Support ticket details

Errors 403 · 404

Permissions support:read · Roles: admin, analyst, customer_service, owner, viewer

curl -X GET "$BUSINESS_API/tickets/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Support ticket details

Assign support ticket to agent

Logs

POST /tickets/{id}/assign

Sets assigned_to on the ticket to the given staff user ID and, if the ticket was open, moves it to in_progress. The assignee is not validated, and an empty value clears the assignment. Returns 404 for an unknown ticket; requires support:write.

Parameters

idstring · path · required

ID of the support ticket in the caller's tenant.

Returns

200 Support ticket assigned

Errors 403 · 404

Permissions support:write · Roles: admin, customer_service, owner

curl -X POST "$BUSINESS_API/tickets/{id}/assign" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Support ticket assigned

Resolve support ticket

Logs

POST /tickets/{id}/resolve

Sets the ticket to resolved, stores the resolution text from the body and records the resolution time. The current status is not checked, so a closed ticket can be resolved again and the resolution overwritten. Returns 404 for an unknown ticket; requires support:write.

Parameters

idstring · path · required

ID of the support ticket in the caller's tenant.

Returns

200 Support ticket resolved

Errors 403 · 404

Permissions support:write · Roles: admin, customer_service, owner

curl -X POST "$BUSINESS_API/tickets/{id}/resolve" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Support ticket resolved

Close support ticket

Logs

POST /tickets/{id}/close

Sets the ticket status to closed and returns it. The current status is not checked, so any ticket, resolved or not, can be closed and the call can be repeated. Returns 404 for an unknown ticket; requires support:write.

Parameters

idstring · path · required

ID of the support ticket in the caller's tenant.

Returns

200 Support ticket closed

Errors 403 · 404

Permissions support:write · Roles: admin, customer_service, owner

curl -X POST "$BUSINESS_API/tickets/{id}/close" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Support ticket closed

List comments on support ticket

Logs

GET /tickets/{id}/comments

Returns the comments on the ticket, from staff and from the customer, each marked with its author type, in cursor pages using limit (up to 100, 20 by default) and after. Returns 404 when the ticket is not in the caller's tenant; requires support:read.

Parameters

idstring · path · required

ID of the support ticket whose comments are listed.

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Comments

Errors 403 · 404

Permissions support:read · Roles: admin, analyst, customer_service, owner, viewer

curl -X GET "$BUSINESS_API/tickets/{id}/comments" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Comments

Add comment to support ticket

Logs

POST /tickets/{id}/comments

Adds a staff comment with the given content to the ticket and updates the ticket's last-changed time; the ticket status is not changed. content is required (400 when empty) and the ticket must be in the caller's tenant (404 otherwise). Requires support:read and support:write.

Parameters

idstring · path · required

ID of the support ticket being commented on.

Returns

201 Comment added

Errors 403 · 404

Permissions support:write · Roles: admin, customer_service, owner

curl -X POST "$BUSINESS_API/tickets/{id}/comments" \
  -H "Authorization: Bearer sk_test_..."
Response 201

Comment added

Get the metadata of a ticket

Logs

GET /tickets/{id}/metadata

Returns the free-form key-value metadata the tenant has stored on the ticket, as an entry with resource_type, resource_id and a metadata map. The ticket must exist in the caller's tenant (404 otherwise); requires business:metadata:read.

Parameters

idstring · path · required

ID of the support ticket in the caller's tenant, at most 120 characters.

Returns

200 Metadata

Show attributes
resource_typestring · optional
resource_idstring · optional
metadataobject · optional

Errors 404

Permissions business:metadata:read · Roles: admin, customer_service, owner

curl -X GET "$BUSINESS_API/tickets/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

Merge metadata

Logs

PUT /tickets/{id}/metadata

Merge metadata; an empty value deletes the key

Merges the keys in the metadata object into what the ticket already has; keys not sent are kept, and a key sent with an empty string is removed. Keys must be non-blank, at most 40 characters, without square brackets or control characters, values at most 500 characters, and a resource holds at most 50 keys; violations return 400 with one entry per invalid key. Returns the full metadata after the merge; requires business:metadata:write.

Parameters

idstring · path · required

ID of the support ticket in the caller's tenant, at most 120 characters.

Body application/json

metadataobject · required

Returns

200 Resulting metadata

Show attributes
resource_typestring · optional
resource_idstring · optional
metadataobject · optional

Errors 400 · 404

Permissions business:metadata:write · Roles: admin, owner

curl -X PUT "$BUSINESS_API/tickets/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": {
    "key": "value"
  }
}'
Response 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}