Utility relationships

Base URL: $BUSINESS_API

The object

idstring · required
tenant_idstring · required
kindstring · required

What the person is to the utility.

one of requester, follower, assisted_helper

subject_typestring · optional

Type of the record the relationship is about, when it is about one.

subject_idstring · optional

Identifier of that record.

statusstring · required

one of active, ended, invited, pending_review, suspended, declined, expired

started_atstring (date-time) · required
expires_atstring (date-time) · optional
ended_atstring (date-time) · optional
end_reasonstring · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required
The object
{
  "id": "bus_26IDFyAP1M8j5sultUq3VOC3R02",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "kind": "requester",
  "subject_type": "subject type",
  "subject_id": "sub_2Cg5f6gZ7W8jvEm53ICdbaeNrWe",
  "status": "active",
  "started_at": "2026-11-19T09:30:00Z",
  "expires_at": "2026-11-19T09:30:00Z",
  "ended_at": "2026-11-19T09:30:00Z",
  "end_reason": "end reason",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

List people's relationships with the utility

Logs

GET /utility-relationships

Pages the relationships people hold with the caller's utility that do not need an account, such as requester, follower or assisted helper, newest first. Each row has the kind, the subject it is about (for example a service request), the status and its start, expiry and end times. The person's global identity key is never returned to business callers, although identity_id can still be used as a filter. Requires business:customers:read. An invalid limit or cursor returns 400.

Parameters

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

identity_idstring · query · optional

Only relationships of this identity.

kindstring · query · optional

Only relationships of this kind.

one of requester, follower, assisted_helper

statusstring · query · optional

Only relationships in this status.

one of active, ended, invited, pending_review, suspended, declined, expired

Returns

200 Relationships in the authenticated utility tenant

Show attributes
dataarray of BusinessUtilityRelationship · required
Show child attributes
idstring · required
tenant_idstring · required
kindstring · required

What the person is to the utility.

one of requester, follower, assisted_helper

subject_typestring · optional

Type of the record the relationship is about, when it is about one.

subject_idstring · optional

Identifier of that record.

statusstring · required

one of active, ended, invited, pending_review, suspended, declined, expired

started_atstring (date-time) · required
expires_atstring (date-time) · optional
ended_atstring (date-time) · optional
end_reasonstring · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required
has_moreboolean · required
next_cursorstring · optional

Errors 400 · 401 · 403

Permissions business:customers:read · Roles: admin, analyst, billing_clerk, customer_service, field_supervisor, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/utility-relationships" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "bus_26IDFyAP1M8j5sultUq3VOC3R02",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "kind": "requester",
      "subject_type": "subject type",
      "subject_id": "sub_2Cg5f6gZ7W8jvEm53ICdbaeNrWe",
      "status": "active",
      "started_at": "2026-11-19T09:30:00Z",
      "expires_at": "2026-11-19T09:30:00Z",
      "ended_at": "2026-11-19T09:30:00Z",
      "end_reason": "end reason",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}