---
updatedAt: 2026-06-05T14:02:48.000Z
---
Fetch the complete documentation index at: https://developers.pismo.io/pismo-docs/llms.txt. Use this file to discover all available pages before exploring further.
# Register beneficiary
Register a new beneficiary with Pismo.
A newly-registerd beneficiary is not initially enabled and must be activated before use in transactions.
# OpenAPI definition
```json
{
"openapi": "3.0.3",
"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.RegisterBeneficiaryRequest": {
"type": "object",
"required": [
"account_code",
"account_id",
"name",
"region",
"schema"
],
"properties": {
"account_code": {
"$ref": "#/components/schemas/beneAccountCode"
},
"account_id": {
"$ref": "#/components/schemas/accountID"
},
"name": {
"$ref": "#/components/schemas/beneName"
},
"region": {
"$ref": "#/components/schemas/regionCode"
},
"schema": {
"$ref": "#/components/schemas/beneSchema"
},
"account_type": {
"$ref": "#/components/schemas/brazilAccountType"
},
"alias": {
"$ref": "#/components/schemas/beneAlias"
},
"bank_code": {
"$ref": "#/components/schemas/beneBankCode"
},
"branch": {
"$ref": "#/components/schemas/beneBranch"
},
"document_number": {
"$ref": "#/components/schemas/beneDocNumber"
}
}
},
"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": {
"post": {
"tags": [
"Beneficiaries"
],
"summary": "Register beneficiary",
"description": "Register a new beneficiary with Pismo.\n\nA newly-registerd beneficiary is not initially enabled and must be activated before use in transactions.\n",
"operationId": "post-intl-bank-accounts-v1-bank-accounts-beneficiaries",
"parameters": [
{
"$ref": "#/components/parameters/authHeader"
}
],
"requestBody": {
"description": "Register beneficiary request body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/beneficiaries.RegisterBeneficiaryRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Register beneficiary response body",
"headers": {
"x-cid": {
"description": "Request tracking identifier.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/beneficiaries.Beneficiary"
}
}
}
},
"400": {
"description": "Bad Request",
"headers": {
"x-cid": {
"description": "Request tracking identifier.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/domain.Error"
},
"examples": {
"EIBA0009": {
"summary": "Validation Error",
"value": {
"code": "EIBA0009",
"message": "Validation error"
}
},
"EIBA0012": {
"summary": "Accounts API invalid request",
"value": {
"code": "EIBA0012",
"message": "Accounts - API returned 4xx error"
}
},
"EIBA0016": {
"summary": "Account ID mismatch",
"value": {
"code": "EIBA0016",
"message": "Account ID in header does not match account ID in request body"
}
}
}
}
}
},
"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"
}
}
}
}
}
},
"409": {
"description": "Conflict",
"headers": {
"x-cid": {
"description": "Request tracking identifier.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/domain.Error"
},
"examples": {
"EIBA0017": {
"summary": "Beneficiary Already Exists",
"value": {
"code": "EIBA0017",
"message": "Beneficiary - Already Exists"
}
}
}
}
}
},
"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"
}
}
}
}
}
}
}
}
}
}
}
```