List boleto beneficiaries of the tenant

GET

https://client.api.corpx.com/v1/boleto/charge/beneficiaries

GET

/v1/boleto/charge/beneficiaries

curl https://client.api.corpx.com/v1/boleto/charge/beneficiaries \
     -H "X-Content-SHA256: X-Content-SHA256" \
     -H "X-Request-Signature: X-Request-Signature" \
     -H "X-Request-Timestamp: X-Request-Timestamp" \
     -H "X-Tenant-Id: X-Tenant-Id" \
     -H "Authorization: Bearer <token>"

{
  "items": [
    {
      "beneficiaryId": "8c1f6a2e-4d3b-4b9a-9f0e-1a2b3c4d5e6f",
      "identifier": "order-12345",
      "status": "ELIGIBLE",
      "relationshipStatus": "ACTIVE",
      "relationshipActive": true,
      "personType": "person",
      "taxNumber": "12345678000190",
      "name": "MARIA DA SILVA",
      "legalName": "MARIA DA SILVA",
      "tradeName": "MARIA DA SILVA",
      "socialName": "MARIA DA SILVA",
      "relationshipStartDate": "2026-02-20",
      "relationshipClosedAt": "2026-02-20T08:33:39Z",
      "email": "maria.silva@example.com",
      "phone": "+5511999999999",
      "representativeName": "MARIA DA SILVA",
      "representativeEmail": "maria.silva@example.com",
      "representativePhone": "+5511999999999",
      "alertOriginators": [
        "string"
      ],
      "updated": "2026-02-20T08:33:39Z",
      "accountId": "2e6b725b-84a0-400d-8740-22a5ba0f23e6"
    }
  ],
  "page": 1,
  "pageSize": 50,
  "totalItems": 150,
  "hasNext": true
}

Lists beneficiaries from the settlement bank and keeps only those whose tax number matches an account of the tenant in X-Tenant-Id. Pagination follows the bank’s page; a page can come back short after that filter. hasNext means the bank has another page. Requires boleto_charge.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Headers

X-Content-SHA256stringRequired

Lowercase hex SHA-256 of the body. An empty body hashes the empty string, so the header is always present. Mismatch returns 400 body_hash_mismatch.

Query parameters

statusenumOptional

Canonical beneficiary status (ELIGIBLE, PENDING, INELIGIBLE, UNDER_REVIEW).

Allowed values:

pageintegerOptional>=1Defaults to 1

Page number, starting at 1.

pageSizeintegerOptional1-200Defaults to 50

Number of beneficiaries per page, up to 200.

Response

Tenant beneficiaries on this page.

itemslist of objectsOptional

pageintegerOptional

pageSizeintegerOptional

totalItemsintegerOptional

hasNextbooleanOptional

Errors

403

Forbidden Error