PT EN

Relações

URL base: $CONSUMER_API

O objecto

idstring · obrigatório

Membership ID for an account-bound entry, or utility relationship ID (prefix ulr) for a utility-only entry. Pass it to the end call.

tenant_idstring · obrigatório

Utility the relationship is with.

tenant_namestring · opcional

Display name of the utility; falls back to the tenant ID when the utility has no name.

kindstring · obrigatório

Relationship kind.

um de holder, delegate, payer, tenant, landlord, requester, follower

account_idstring · opcional

Account of an account-bound entry.

account_numberstring · opcional

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

account_holder_namestring · opcional

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

subject_labelstring · opcional

Label to show for an account-bound entry; the account number, or the account ID when it has no number.

subject_typestring · opcional

Type of the subject of a utility-only entry, as given when it was created.

subject_idstring · opcional

Identifier of the subject of a utility-only entry.

permissionsarray of string · opcional

Account permissions the membership grants. Omitted for utility-only entries.

statusstring · obrigatório

Current status; a membership past its expiry that was never ended reports expired.

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

started_atstring (date-time) · obrigatório
created_atstring (date-time) · obrigatório
expires_atstring (date-time) · opcional
ended_atstring (date-time) · opcional
O objecto
{
  "id": "con_2FxsaDbgur7MKnHo6RdmsNhQOT1",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "tenant_name": "Ana Matsinhe",
  "kind": "holder",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "subject_label": "subject label",
  "subject_type": "subject type",
  "subject_id": "sub_2Cg5f6gZ7W8jvEm53ICdbaeNrWe",
  "permissions": [
    "account.read"
  ],
  "status": "invited",
  "started_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "expires_at": "2026-11-19T09:30:00Z",
  "ended_at": "2026-11-19T09:30:00Z"
}

Listar relações com empresas de água

Registos

GET /relationships

Returns one list, newest first, of everything that links the signed-in person to a utility: account memberships (as holder, delegate, payer, tenant or landlord, with the permissions each grants) and utility-only relationships the person started (requester or follower). Ended and expired entries are included unless filtered out. The caller must be a consumer identity that is not bound to a tenant; otherwise the response is 403.

Parâmetros

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

kindstring · consulta · opcional

Return only entries of this kind: holder, delegate, payer, tenant, landlord, requester or follower.

statusstring · consulta · opcional

Return only entries in this status, for example active, pending_review, ended or expired.

Devolve

200 The caller's relationships

Mostrar atributos
dataarray of ConsumerRelationship · obrigatório

Relationships, newest first.

Mostrar atributos filhos
idstring · obrigatório

Membership ID for an account-bound entry, or utility relationship ID (prefix ulr) for a utility-only entry. Pass it to the end call.

tenant_idstring · obrigatório

Utility the relationship is with.

tenant_namestring · opcional

Display name of the utility; falls back to the tenant ID when the utility has no name.

kindstring · obrigatório

Relationship kind.

um de holder, delegate, payer, tenant, landlord, requester, follower

account_idstring · opcional

Account of an account-bound entry.

account_numberstring · opcional

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

account_holder_namestring · opcional

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

subject_labelstring · opcional

Label to show for an account-bound entry; the account number, or the account ID when it has no number.

subject_typestring · opcional

Type of the subject of a utility-only entry, as given when it was created.

subject_idstring · opcional

Identifier of the subject of a utility-only entry.

permissionsarray of string · opcional

Account permissions the membership grants. Omitted for utility-only entries.

statusstring · obrigatório

Current status; a membership past its expiry that was never ended reports expired.

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

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

True when another page follows.

next_cursorstring · opcional

Opaque cursor for the next page; present only when has_more is true.

Erros 400 · 401 · 403

curl -X GET "$CONSUMER_API/relationships" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "con_2FxsaDbgur7MKnHo6RdmsNhQOT1",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "tenant_name": "Ana Matsinhe",
      "kind": "holder",
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "account_number": "ACC-2026-000142",
      "account_holder_name": "Ana Matsinhe",
      "subject_label": "subject label",
      "subject_type": "subject type",
      "subject_id": "sub_2Cg5f6gZ7W8jvEm53ICdbaeNrWe",
      "permissions": [
        "account.read"
      ],
      "status": "invited",
      "started_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z",
      "expires_at": "2026-11-19T09:30:00Z",
      "ended_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Iniciar uma relação com uma empresa de água

Registos

POST /relationships

Lets a person follow a utility, or ask it about something, before or without holding an account there. A follower relationship is active at once; a requester relationship starts in pending_review and needs subject_id naming what the request is about. The caller must be a consumer identity that is not bound to a tenant (403 otherwise). A missing tenant_id, a kind other than requester or follower, a requester without subject_id, or an unknown body field returns 400.

Corpo application/json

tenant_idstring · obrigatório

Utility to start the relationship with.

kindstring · obrigatório

follower starts an active relationship at once; requester starts one in pending_review for the utility to act on and needs subject_id.

um de requester, follower

subject_typestring · opcional

Optional type of the subject the relationship is about, for example a property or service request.

subject_idstring · opcional

Identifier of the subject; required when kind is requester.

Devolve

201 Relationship created

Mostrar atributos
idstring · obrigatório

Relationship ID (prefix ulr).

tenant_idstring · obrigatório

Utility the relationship is with.

identity_idstring · opcional

The caller's identity ID.

kindstring · obrigatório

um de requester, follower

subject_typestring · opcional
subject_idstring · opcional
statusstring · obrigatório

active for a follower, pending_review for a requester.

um de active, pending_review

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

Erros 400 · 401 · 403

curl -X POST "$CONSUMER_API/relationships" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "kind": "requester",
  "subject_type": "subject type",
  "subject_id": "sub_2Cg5f6gZ7W8jvEm53ICdbaeNrWe"
}'
Resposta 201
{
  "id": "ulr_01J9Z5V7Q3",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "identity_id": "ide_2W4tFuAzbOoV5aORlgwJHqwRdkg",
  "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"
}

Terminar uma relação com uma empresa de água

Registos

POST /relationships/{id}/end

Ends an entry from the caller's relationship list. For an account membership the caller leaves the account (recorded as left by the person) and loses the permissions it granted; for a utility-only relationship its status becomes ended. Ending an entry that has already ended succeeds. An ID that is not one of the caller's entries returns 404. The caller must be a consumer identity that is not bound to a tenant.

Parâmetros

idstring · caminho · obrigatório

ID of the entry to end, as returned by the list call: a membership ID or a utility relationship ID (prefix ulr).

Devolve

204 Relationship ended

Erros 401 · 403 · 404

curl -X POST "$CONSUMER_API/relationships/{id}/end" \
  -H "Authorization: Bearer sk_test_..."
Resposta 204

Relationship ended