--- updatedAt: 2026-06-05T14:02:48.000Z agentTools: siteIndex: https://developers.pismo.io/llms.txt projectIndex: https://developers.pismo.io/pismo-docs/llms.txt --- # List beneficiaries List registered beneficiaries with query filtering options. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Banking - Bank accounts", "version": "1.0.0", "description": "API for managing bank accounts in global formats", "contact": { "name": "API Support", "url": "https://developers.pismo.io/support/" }, "license": { "name": "Copyright Pismo" } }, "servers": [ { "url": "https://sandbox.pismolabs.io/intl-bankaccounts", "description": "Sandbox API server for testing" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Beneficiaries", "description": "Beneficiaries management endpoints" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Account token - token encoded with Pismo account ID. Tokens can expire quickly, which can result in an **401 Unauthorized** error.", "bearerFormat": "JWT" } }, "parameters": { "authHeader": { "name": "Authorization", "in": "header", "description": "Account token - Token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a **401 Unauthorized** error. \n", "required": true, "schema": { "type": "string" }, "example": 1234 } }, "schemas": { "accountID": { "type": "integer", "description": "Account ID", "example": 78123456 }, "brazilAccountType": { "type": "string", "enum": [ "CACC", "SLRY", "SVGS", "TRAN" ], "maxLength": 4, "description": "Account type: \n `CACC` - Checking/current account. Known as \"conta corrente\" in Portuguese, this is a bank account type designed for everyday financial transactions and is the most common type individuals and businesses use for day-to-day banking.\n `SVGS` - Savings account\n `TRAN` - Payment account. Payment institutions offer payment accounts to move funds and make payments, while banks offer checking accounts that include full financial services such as credit and investments.\n `SLRY` - Salary account. Employer deposits a fixed amount every month.\n", "example": "TRAN" }, "beneBankCode": { "type": "string", "description": "Beneficiary bank code.", "maxLength": 20, "example": "1086" }, "beneBranch": { "maxLength": 50, "description": "Beneficiary branch.", "type": "string", "example": "5555555" }, "beneAccountCode": { "type": "string", "maxLength": 50, "description": "Beneficiary account code.", "example": "7654321" }, "beneAlias": { "type": "string", "maxLength": 20, "description": "Beneficiary alias.", "example": "Curveball" }, "beneName": { "type": "string", "description": "Beneficiary's first and last name.", "maxLength": 50, "example": "Al Freydough" }, "beneDocNumber": { "type": "string", "description": "A government document number, such as a Social Security number (US) or Cadastro de Pessoas Físicas number (Brazil). \n", "maxLength": 20, "example": "123412341234" }, "beneID": { "type": "string", "maxLength": 32, "description": "UUID identifying beneficiary.", "example": "123e4567-e89b-12d3-a456-42661417" }, "beneEnabled": { "type": "boolean", "description": "Is beneficiary active flag.", "example": true }, "beneficiaries.Beneficiary": { "type": "object", "properties": { "account_code": { "$ref": "#/components/schemas/beneAccountCode" }, "account_id": { "$ref": "#/components/schemas/accountID" }, "account_type": { "$ref": "#/components/schemas/brazilAccountType" }, "alias": { "$ref": "#/components/schemas/beneAlias" }, "bank_code": { "$ref": "#/components/schemas/beneBankCode" }, "beneficiary_id": { "$ref": "#/components/schemas/beneID" }, "branch": { "$ref": "#/components/schemas/beneBranch" }, "creation_datetime": { "$ref": "#/components/schemas/creationDatetime" }, "document_number": { "$ref": "#/components/schemas/beneDocNumber" }, "enabled": { "$ref": "#/components/schemas/beneEnabled" }, "name": { "$ref": "#/components/schemas/beneName" }, "region": { "$ref": "#/components/schemas/regionCode" }, "schema": { "$ref": "#/components/schemas/beneSchema" }, "updated_datetime": { "$ref": "#/components/schemas/updatedDatetime" } } }, "beneficiaries.SearchBeneficiaryResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/beneficiaries.Beneficiary" } }, "last_evaluated_creation_datetime": { "type": "string", "description": "Use this field to get next results" }, "per_page": { "type": "integer", "description": "Items per page.", "example": 10 }, "total_items": { "type": "integer", "description": "Total items", "example": 100 } } }, "beneSchema": { "type": "string", "description": "Beneficiary schema validation: \n\n `BANKACCOUNT` - `account_code` contains a Brazilian account number (used in junction with the `bank_code` and `branch` fields)\n\n `PIX` - `account_code` contains a valid Pix key. For more information, see Pix instant payments\n\n `DOCUMENTNUMBER` - `account_code` contains a valid Brazilian document number. This is government document number, such as Cadastro de Pessoas Físicas number - a Brazilian tax registry number, similar to a Social Security number in the US. \n", "enum": [ "BANKACCOUNT", "PIX", "DOCUMENTNUMBER" ], "example": "PIX" }, "creationDatetime": { "type": "string", "format": "date-time", "description": "Account creation date time displayed in ISO 8601 format `2023-04-12T23:20:50.52Z`.", "example": "2023-04-12T23:20:50.52Z" }, "domain.Error": { "type": "object", "properties": { "code": { "type": "string", "description": "Error type code", "example": "EIBA0001" }, "details": { "type": "string", "description": "Error details", "example": "Key not found" }, "message": { "type": "string", "description": "Error message", "example": "Key not found" } } }, "regionCode": { "type": "string", "description": "ISO-3166 two letter country code. For example, BR=Brazil.", "example": "BR" }, "updatedDatetime": { "type": "string", "format": "date-time", "description": "Updated date time. A RFC 3339 value, i.e., \"2023-04-12T23:20:50.52Z\".", "example": "2023-04-12T23:20:50.52Z" } } }, "paths": { "/v1/beneficiaries": { "get": { "tags": [ "Beneficiaries" ], "summary": "List beneficiaries", "description": "List registered beneficiaries with query filtering options.\n", "operationId": "get-intl-bank-accounts-v1-bank-accounts-beneficiaries", "parameters": [ { "$ref": "#/components/parameters/authHeader" }, { "name": "lastEvaluatedCreationDatetime", "in": "query", "description": "This is the `last_evaluated_creation_datetime` field from the response. You can use it to get the next page of results on a subsequent call.\n", "schema": { "type": "string" } }, { "name": "perPage", "in": "query", "description": "Number of items per page, min=1, max=100, default=20.", "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Sort order. Results are ordered on the `created_datetime` field. Default=`DESC`.", "schema": { "type": "string", "enum": [ "DESC", "ASC" ] } }, { "name": "name", "in": "query", "description": "Beneficiary name", "schema": { "type": "string", "maxLength": 50 } }, { "name": "alias", "in": "query", "description": "Beneficiary alias", "schema": { "type": "string", "maxLength": 20 } }, { "name": "enabled", "in": "query", "description": "Return only active or non-active beneficiaries flag. If not passed, all beneficiares are returned.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Response Body", "headers": { "x-cid": { "description": "Request tracking identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/beneficiaries.SearchBeneficiaryResponse" } } } }, "400": { "description": "Bad Request", "headers": { "x-cid": { "description": "Request tracking identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/domain.Error" }, "examples": { "EIBA0012": { "summary": "Accounts API invalid request", "value": { "code": "EIBA0012", "message": "Accounts - API returned 4xx error" } }, "EIBA0018": { "summary": "Invalid perPage Query Parameter", "value": { "code": "EIBA0018", "message": "Invalid value for query param 'perPage'" } }, "EIBA0019": { "summary": "Invalid Datetime Query Parameter", "value": { "code": "EIBA0019", "message": "Invalid value for datetime query parameter. RFC3339 format must be used" } }, "EIBA0020": { "summary": "Invalid Boolean Query Parameter", "value": { "code": "EIBA0020", "message": "Invalid value for boolean query parameter" } } } } } }, "403": { "description": "Forbidden", "headers": { "x-cid": { "description": "Request tracking identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/domain.Error" }, "examples": { "EIBA0006": { "summary": "Missing tenant header", "value": { "code": "EIBA0006", "message": "Missing required header: 'x-tenant'" } }, "EIBA0007": { "summary": "Invalid account ID header", "value": { "code": "EIBA0007", "message": "Invalid account ID header: 'x-account-id'" } }, "EIBA0023": { "summary": "Account status not NORMAL", "value": { "code": "EIBA0023", "message": "Account status not NORMAL" } } } } } }, "404": { "description": "Not Found", "headers": { "x-cid": { "description": "Request tracking identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/domain.Error" }, "examples": { "EIBA0010": { "summary": "Account not found", "value": { "code": "EIBA0010", "message": "Account not found" } } } } } }, "500": { "description": "Internal Server Error", "headers": { "x-cid": { "description": "Request tracking identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/domain.Error" }, "examples": { "EIBA0005": { "summary": "HTTP error", "value": { "code": "EIBA0005", "message": "HTTP error" } }, "EIBA0011": { "summary": "Accounts API server error", "value": { "code": "EIBA0011", "message": "Accounts - API returned 5xx error" } }, "EIBA0013": { "summary": "Accounts API timeout", "value": { "code": "EIBA0013", "message": "Accounts - API timeout" } }, "EIBA0015": { "summary": "Database error", "value": { "code": "EIBA0015", "message": "Database internal error" } } } } } } }, "x-codegen-request-body-name": "RequestBody" } } } } ```