> ## Documentation Index > Fetch the complete documentation index at: https://tracefinance.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # List beneficiaries > Lists all beneficiaries for the authenticated customer. ## OpenAPI ````yaml apis/fx-payment/openapi.yml GET /api/beneficiaries openapi: 3.1.1 info: title: Trace Finance Payments API version: 1.0.0 description: > API for deposits, withdrawals, swaps, and beneficiary management on the Trace Finance platform. servers: - url: https://api.sandbox.tracefinance.com description: Sandbox security: - bearerAuth: [] tags: - name: Operations description: >- Create deposits, withdrawals, and swaps. Query operation status and history. - name: Reports description: Generate aggregated views of operations across a time window. - name: Beneficiaries description: >- Manage external beneficiaries and their payment instructions for withdrawals. - name: Payment instructions description: Add or remove payment instructions on an existing beneficiary. paths: /api/beneficiaries: get: tags: - Beneficiaries summary: List beneficiaries description: >- Lists all beneficiaries for the authenticated customer. Returns lightweight summaries — call `GET /api/beneficiaries/{beneficiaryId}` to retrieve the full beneficiary including its payment instructions. Results are paginated. operationId: listBeneficiaries parameters: - $ref: '#/components/parameters/TraceVersion' - $ref: '#/components/parameters/PaginationLimit' - $ref: '#/components/parameters/PaginationCursor' - $ref: '#/components/parameters/PaginationDirection' - $ref: '#/components/parameters/PaginationSortOrder' - $ref: '#/components/parameters/Filters' responses: '200': description: Paginated list of beneficiary summaries. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/BeneficiaryList' '401': $ref: '#/components/responses/UnauthorizedError' components: parameters: TraceVersion: name: X-Trace-Version in: header required: false description: API version. Omit to use the default version. schema: type: string example: '1' PaginationLimit: name: limit in: query required: false description: Maximum number of items to return. Defaults to 10. schema: type: integer default: 10 minimum: 1 maximum: 100 PaginationCursor: name: cursor in: query required: false description: Opaque cursor for fetching the next or previous page. schema: type: string PaginationDirection: name: direction in: query required: false description: Direction of pagination relative to the cursor. schema: type: string enum: - NEXT - PREVIOUS PaginationSortOrder: name: sortOrder in: query required: false description: Sort order for results. Defaults to DESCENDING. schema: type: string enum: - ASCENDING - DESCENDING default: DESCENDING Filters: name: filters in: query required: false description: > Filter expression using LHS Brackets syntax (`field[operator]=value`). Combine multiple conditions with `and(...)`, `or(...)`, or `;` (implicit AND). See the [Filtering](/guides/principles/filtering) guide for the full operator catalog. schema: type: string example: intent.type[eq]=WITHDRAWAL;currentState.status[eq]=COMPLETED headers: RequestId: description: >- Unique request identifier emitted on every response. Reference it when contacting Trace Finance support so we can trace the request end-to-end. See [Errors](/guides/principles/errors). schema: type: string format: uuid schemas: BeneficiaryList: type: object properties: data: type: array items: $ref: '#/components/schemas/BeneficiarySummaryResponse' meta: $ref: '#/components/schemas/PageMetadata' required: - data - meta BeneficiarySummaryResponse: type: object description: >- Lightweight beneficiary projection used by the list endpoint. Same as `BeneficiaryResponse` but with a count instead of the full payment instructions array. properties: id: type: string format: uuid example: ben-a1b2c3d4-5e6f-7890-abcd-ef1234567890 readOnly: true customerId: type: string format: uuid description: Customer that owns this beneficiary. entity: $ref: '#/components/schemas/EntityResponse' relationshipType: type: string enum: - SELF_OWNED - THIRD_PARTY description: >- Whether the beneficiary is the customer themselves (`SELF_OWNED`) or a separate party (`THIRD_PARTY`). instructionCount: type: integer description: Number of payment instructions on this beneficiary. example: 2 createdAt: type: string format: date-time example: '2026-04-14T10:30:00Z' readOnly: true updatedAt: type: string format: date-time example: '2026-04-14T10:30:00Z' readOnly: true required: - id - customerId - entity - relationshipType - instructionCount - createdAt - updatedAt PageMetadata: type: object description: Cursor-based pagination metadata. properties: previousCursor: type: string nullable: true description: Cursor for the previous page. `null` on the first page. nextCursor: type: string nullable: true description: Cursor for the next page. `null` on the last page. total: type: integer description: Number of items in the current page. required: - previousCursor - nextCursor - total ErrorResponse: type: object properties: code: type: string description: Machine-readable error code. message: type: string description: Human-readable description. details: type: object additionalProperties: true required: - code - message EntityResponse: description: The person or company that receives funds. Discriminated by `type`. oneOf: - $ref: '#/components/schemas/IndividualEntityResponse' - $ref: '#/components/schemas/CompanyEntityResponse' discriminator: propertyName: type mapping: INDIVIDUAL: $ref: '#/components/schemas/IndividualEntityResponse' COMPANY: $ref: '#/components/schemas/CompanyEntityResponse' IndividualEntityResponse: title: Individual type: object properties: type: type: string enum: - INDIVIDUAL firstName: type: string example: João lastName: type: string example: Silva taxId: $ref: '#/components/schemas/TaxIdResponse' dateOfBirth: type: string format: date description: Date of birth in ISO 8601 (`yyyy-MM-dd`). example: '1985-03-15' address: $ref: '#/components/schemas/Address' required: - type - firstName - lastName - taxId - dateOfBirth - address CompanyEntityResponse: title: Company type: object properties: type: type: string enum: - COMPANY legalName: type: string example: Acme Importação Ltda tradeName: type: string nullable: true example: Acme taxId: $ref: '#/components/schemas/TaxIdResponse' address: $ref: '#/components/schemas/Address' required: - type - legalName - taxId - address TaxIdResponse: type: object description: Tax identifier returned for a beneficiary entity. properties: value: type: string example: '52998224725' type: $ref: '#/components/schemas/TaxIdType' required: - value - type Address: type: object description: Postal address of an entity or beneficiary. properties: addressLine1: type: string description: Primary street line (number + street). addressLine2: oneOf: - type: string - type: 'null' description: >- Secondary line (apartment, suite, building). `null` if not applicable. city: type: string state: oneOf: - type: string - type: 'null' description: >- State, province, or region. `null` for countries without subdivisions in the address. country: $ref: '#/components/schemas/Country' postalCode: type: string description: Postal or ZIP code, formatted per the country's convention. required: - addressLine1 - addressLine2 - city - state - country - postalCode TaxIdType: type: string description: > Country-specific tax identifier type. The type itself implies the country (`CPF`/`CNPJ` are Brazilian, `CUIT`/`CUIL` are Argentine, `RUT_CL` is Chilean, etc.). enum: - CPF - CNPJ - CUIT - CUIL - RUT_CL - RUT_UY - CI_UY - RUC - DNI_PE - NIT - CC - RFC - RUC_PY - CI_PY - NIPC - NIF_PT - CIF - NIF_ES - NIE - SIREN - SIRET - NIF_FR - PARTITA_IVA - CODICE_FISCALE - UST_IDNR - STEUER_ID - KVK - BSN - BCE - NN_BE - ORGANISATIONSNUMMER - PERSONNUMMER - ORGANISASJONSNUMMER - FODSELSNUMMER - UID_CH - AHV - VAT_GB - NIN - EIN - SSN - ITIN - BN_CA - SIN - ABN - TFN - USCC - CORPORATE_NUMBER_JP - MY_NUMBER - BRN_KR - RRN - GSTIN - PAN - INN_RU - COMPANY_NUMBER_IL - TEUDAT_ZEHUT - TRADE_LICENSE - EMIRATES_ID - CIPC - SA_ID example: CPF Country: type: string description: ISO 3166-1 alpha-2 country code. example: BR enum: - AF - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BQ - BA - BW - BV - BR - IO - BN - BG - BF - BI - CV - KH - CM - CA - KY - CF - TD - CL - CN - CX - CC - CO - KM - CD - CG - CK - CR - HR - CU - CW - CY - CZ - CI - DK - DJ - DM - DO - EC - EG - SV - GQ - ER - EE - SZ - ET - FK - FO - FJ - FI - FR - GF - PF - TF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GP - GU - GT - GG - GN - GW - GY - HT - HM - VA - HN - HK - HU - IS - IN - ID - IR - IQ - IE - IM - IL - IT - JM - JP - JE - JO - KZ - KE - KI - KP - KR - KW - KG - LA - LV - LB - LS - LR - LY - LI - LT - LU - MO - MG - MW - MY - MV - ML - MT - MH - MQ - MR - MU - YT - MX - FM - MD - MC - MN - ME - MS - MA - MZ - MM - NA - NR - NP - NL - NC - NZ - NI - NE - NG - NU - NF - MP - 'NO' - OM - PK - PW - PS - PA - PG - PY - PE - PH - PN - PL - PT - PR - QA - MK - RO - RU - RW - RE - BL - SH - KN - LC - MF - PM - VC - WS - SM - ST - SA - SN - RS - SC - SL - SG - SX - SK - SI - SB - SO - ZA - GS - SS - ES - LK - SD - SR - SJ - SE - CH - SY - TW - TJ - TZ - TH - TL - TG - TK - TO - TT - TN - TR - TM - TC - TV - UG - UA - AE - GB - UM - US - UY - UZ - VU - VE - VN - VG - VI - WF - EH - YE - ZM - ZW - AX responses: UnauthorizedError: description: Missing or invalid authentication token. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidToken: $ref: '#/components/examples/InvalidToken' expiredToken: $ref: '#/components/examples/ExpiredToken' examples: InvalidToken: summary: Bearer token is invalid or malformed value: code: INVALID_ACCESS_TOKEN message: Invalid access token details: {} ExpiredToken: summary: Bearer token has expired value: code: EXPIRED_ACCESS_TOKEN message: Expired access token details: {} securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT bearer token. Include as `Authorization: Bearer `. See the [Authentication](/guides/authentication) guide for how to obtain one. ````