---
updatedAt: 2026-04-20T19:56:08.000Z
agentTools:
siteIndex: https://developers.pismo.io/llms.txt
projectIndex: https://developers.pismo.io/pismo-docs/llms.txt
---
# Transfer transaction banking account ownership
Assign a new owner to a transaction banking account. If the new owner already exists within the organization, it's linked to the account. If not, a new entity is created and linked to the account. The previous account owner and all other customers linked to the account are deactivated.
This endpoint generates an [Account owner changed](https://developers.pismo.io/events/docs/account-account-owner-change-1) event.
**NOTE**: This endpoint requires an account token - an access token encoded with an external account ID. Tokens can expire quickly, which can result in a `401 Unauthorized` message.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "Banking - Transaction banking",
"version": "0.9.0",
"description": "Transaction banking API",
"contact": {
"name": "API Support",
"url": "https://developers.pismo.io/support/"
},
"license": {
"name": "Copyright Pismo"
}
},
"servers": [
{
"url": "https://sandbox.pismolabs.io",
"description": "Sandbox API server for testing"
}
],
"security": [
{
"BearerAuth": []
}
],
"tags": [
{
"name": "Accounts",
"description": "Accounts endpoints"
}
],
"components": {
"parameters": {
"ExternalAccountIdPath": {
"name": "externalAccountId",
"in": "path",
"description": "External account ID",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"example": "12345678901",
"required": true
}
},
"schemas": {
"DocumentNumber": {
"type": "string",
"description": "Applicant's government document number. Once set, this value is immutable, which means that `document_number` can't be updated. This field only accepts alphanumeric characters.
\nNote: `document_number` does not allow special characters.\n",
"maxLength": 15,
"example": "812045147"
},
"EntityName": {
"type": "string",
"description": "Entity name",
"maxLength": 60,
"example": "Chester Fields"
},
"ErrorCode": {
"description": "Error code\n`minLength: 1`\n`maxLength: 12`\n",
"type": "string",
"minLength": 1,
"maxLength": 12,
"example": "WPMT0017"
},
"ErrorMessage": {
"description": "Error message\n`minLength: 1`\n`maxLength: 1000`\n",
"type": "string",
"minLength": 1,
"maxLength": 1000,
"example": "Invalid JSON payload received: Error unmarshalling request"
},
"ErrorResponse": {
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/ErrorCode"
},
"message": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
},
"PatchAccountEntity": {
"type": "object",
"properties": {
"document_number": {
"$ref": "#/components/schemas/DocumentNumber"
},
"name": {
"$ref": "#/components/schemas/EntityName"
}
},
"required": [
"document_number",
"name"
]
}
},
"responses": {
"401Unauthorized": {
"description": "Access token is missing or invalid"
},
"403Forbidden": {
"description": "The request has been lost"
},
"500InternalServer": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Generic internal error": {
"value": {
"code": "ECMN9999",
"message": "Internal error"
}
}
}
}
}
}
},
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
}
},
"paths": {
"/corporate/v1/corporate-accounts/{externalAccountId}/entity": {
"patch": {
"summary": "Transfer transaction banking account ownership",
"operationId": "patch-accounts-accountId-entity",
"description": "Assign a new owner to a transaction banking account. If the new owner already exists within the organization, it's linked to the account. If not, a new entity is created and linked to the account. The previous account owner and all other customers linked to the account are deactivated.\n\nThis endpoint generates an [Account owner changed](https://developers.pismo.io/events/docs/account-account-owner-change-1) event.\n\n**NOTE**: This endpoint requires an account token - an access token encoded with an external account ID. Tokens can expire quickly, which can result in a `401 Unauthorized` message.\n",
"tags": [
"Accounts"
],
"parameters": [
{
"$ref": "#/components/parameters/ExternalAccountIdPath"
}
],
"requestBody": {
"description": "The entity name and document number",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PatchAccountEntity"
},
"examples": {
"Update Account Entity": {
"value": {
"name": "Chester Fields",
"document_number": "812045147"
}
}
}
}
}
},
"responses": {
"204": {
"description": "OK"
},
"400": {
"description": "A Bad Request validation error.\n\nStatic Validations (mandatory field, max value, max length, etc) have the code `WCAC0005`.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Account not found": {
"value": {
"code": "WCAC0012",
"message": "Corporate account not found"
}
},
"Invalid JSON payload": {
"value": {
"code": "WCAC0013",
"message": "Invalid JSON payload received: Error unmarshalling request."
}
},
"document_number required": {
"value": {
"code": "WCAC0005",
"message": "document_number is a required field"
}
},
"document_number max length": {
"value": {
"code": "WCAC0005",
"message": "document_number must be a maximum of 15 characters in length"
}
},
"document_number contains characters not permitted": {
"value": {
"code": "WCAC0005",
"message": "document_number contains character not permitted: {characters}"
}
},
"name required": {
"value": {
"code": "WCAC0005",
"message": "name is a required field"
}
},
"name max length": {
"value": {
"code": "WCAC0005",
"message": "name must be a maximum of 60 characters in length"
}
},
"name contains characters not permitted": {
"value": {
"code": "WCAC0005",
"message": "name contains character not permitted: {characters}"
}
},
"Account closed error": {
"value": {
"code": "WCAC0029",
"message": "Action not permitted on a closed account"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
},
"409": {
"description": "Entity conflict.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Customer already owns account": {
"value": {
"code": "WCAC0026",
"message": "This document number is already associated with the owner of this account"
}
},
"Inactive customer": {
"value": {
"code": "WCAC0027",
"message": "This document number is associated with an inactive customer"
}
}
}
}
}
},
"500": {
"$ref": "#/components/responses/500InternalServer"
}
}
}
}
}
}
```