PT EN

Relações com a empresa

URL base: $BUSINESS_API

O objecto

idstring · obrigatório
tenant_idstring · obrigatório
kindstring · obrigatório

What the person is to the utility.

um de requester, follower, assisted_helper

subject_typestring · opcional

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

subject_idstring · opcional

Identifier of that record.

statusstring · obrigatório

um de active, ended, invited, pending_review, suspended, declined, expired

started_atstring (date-time) · obrigatório
expires_atstring (date-time) · opcional
ended_atstring (date-time) · opcional
end_reasonstring · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
O objecto
{
  "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"
}

Listar relações com moradores

Registos

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.

Parâmetros

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

identity_idstring · consulta · opcional

Only relationships of this identity.

kindstring · consulta · opcional

Only relationships of this kind.

um de requester, follower, assisted_helper

statusstring · consulta · opcional

Only relationships in this status.

um de active, ended, invited, pending_review, suspended, declined, expired

Devolve

200 Relationships in the authenticated utility tenant

Mostrar atributos
dataarray of BusinessUtilityRelationship · obrigatório
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · obrigatório
kindstring · obrigatório

What the person is to the utility.

um de requester, follower, assisted_helper

subject_typestring · opcional

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

subject_idstring · opcional

Identifier of that record.

statusstring · obrigatório

um de active, ended, invited, pending_review, suspended, declined, expired

started_atstring (date-time) · obrigatório
expires_atstring (date-time) · opcional
ended_atstring (date-time) · opcional
end_reasonstring · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
has_moreboolean · obrigatório
next_cursorstring · opcional

Erros 400 · 401 · 403

Permissões business:customers:read · Funções: admin, analyst, billing_clerk, customer_service, field_supervisor, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/utility-relationships" \
  -H "Authorization: Bearer sk_test_..."
Resposta 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"
}