# Create transaction banking account
Creates a transaction banking account. For more details, refer to [Transaction banking accounts](doc:corporate-accounts).
This endpoint generates the following events:
- [Corporate account created](https://developers.pismo.io/events/docs/corporate-corporate-account-creation-1).
- [Account application created](https://developers.pismo.io/events/docs/onboarding-succeeded-1)
For more information on events and setting up event notifications, refer to the [Data and reporting](doc:data-reporting-overview) guide.
# OpenAPI definition
```json
{
"openapi": "3.0.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": {
"schemas": {
"AccountCreateDatetime": {
"type": "string",
"format": "date-time",
"description": "The datetime the account was created (in UTC). The datetime format follows the ISO 8601 standard: `yyyy-mm-ddThh:mm:ss.sssZ`.
\n`minLength: 24`\n`maxLength: 24`\n",
"minLength": 24,
"maxLength": 24,
"example": "2025-02-01T22:07:58.000Z"
},
"AccountID": {
"type": "integer",
"format": "int64",
"description": "Account ID",
"example": 1234
},
"ApplicantName": {
"type": "string",
"description": "Applicant name",
"maxLength": 60,
"example": "Chester Fields"
},
"CreateAccountRequest": {
"type": "object",
"description": "Create corporate account request object",
"properties": {
"division_code": {
"$ref": "#/components/schemas/DivisionCode"
},
"program_id": {
"$ref": "#/components/schemas/ProgramID"
},
"applicant": {
"type": "object",
"required": [
"document_number",
"name"
],
"properties": {
"document_number": {
"$ref": "#/components/schemas/DocumentNumber"
},
"name": {
"$ref": "#/components/schemas/ApplicantName"
},
"external_id": {
"$ref": "#/components/schemas/ExternalID"
},
"custom_fields": {
"$ref": "#/components/schemas/CustomFields"
}
}
},
"external_account_id": {
"$ref": "#/components/schemas/ExternalAccountID"
},
"parent_account_id": {
"$ref": "#/components/schemas/ParentAccountID"
},
"account_creation_datetime": {
"$ref": "#/components/schemas/AccountCreateDatetime"
},
"overdraft": {
"$ref": "#/components/schemas/Overdraft"
},
"currency_code": {
"$ref": "#/components/schemas/CurrencyCode"
}
},
"required": [
"division_code",
"program_id",
"applicant",
"external_account_id"
]
},
"CreateAccountResponse": {
"type": "object",
"description": "Create account response body",
"properties": {
"account_id": {
"$ref": "#/components/schemas/AccountID"
},
"external_account_id": {
"$ref": "#/components/schemas/ExternalAccountID"
},
"program_id": {
"$ref": "#/components/schemas/ProgramID3"
},
"division_code": {
"$ref": "#/components/schemas/DivisionCode"
}
},
"required": [
"account_id",
"program_id"
]
},
"CurrencyCode": {
"type": "string",
"maxLength": 3,
"description": "Alphabetic or numeric code (ISO 4217) for the currency used by the program. (Use the same currency as the program, but this is only a temporary situation).",
"example": "986"
},
"CustomFields": {
"type": "object",
"description": "Name-value fields for any account-related data your organization needs to store at Pismo. This field can have its values validated against the JSON schema stored at the division (referenced by the `division_code`) field `schema`."
},
"DivisionCode": {
"type": "string",
"maxLength": 36,
"description": "Code used to identify your division within the organization. Division code should only contain letters, numbers, and hyphens.",
"example": "US"
},
"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"
},
"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"
}
}
},
"ExternalAccountID": {
"maxLength": 60,
"type": "string",
"pattern": "^[a-zA-Z0-9-]+$",
"description": "Custom account ID. Used as the key for all operations (manage accounts, transactions, etc.) on the corporate layer.\n\nThis field is:\n- Unique within the Organization\n- Immutable: The field cannot be updated.\n- Not recyclable: You can't reuse an external account ID, even if the account that was using it has been canceled.\n",
"example": "b993ba96-b3e8-4ef7-9cf7-7eee5ddafdab"
},
"ExternalID": {
"type": "string",
"maxLength": 60,
"description": "Custom entity ID that uniquely identifies the entity within your organization. By default, `document_number` is used as the primary identifier. To set `external_id` as the primary identifier, contact a Pismo representative to enable the parameter `EXTERNAL ID AS MAIN KEY`.",
"example": "83bcde27-e049-4244-9dab-cfb4c88d70f8"
},
"Overdraft": {
"type": "object",
"required": [
"limit"
],
"properties": {
"limit": {
"$ref": "#/components/schemas/OverdraftLimit2"
}
}
},
"OverdraftLimit2": {
"type": "number",
"format": "float",
"description": "Account overdraft limit",
"minimum": 0,
"maximum": 100000000000000000,
"example": 15680.45
},
"ParentAccountID": {
"maximum": 200000000,
"description": "Parent account ID. If provided, the account is the child of the account referenced by `parent_account_id`. The account referenced by `parent_account_id` can be in another program or division.",
"type": "integer",
"format": "int64",
"example": 232
},
"ProgramID": {
"type": "integer",
"format": "int64",
"maximum": 99999999999,
"description": "Program ID. The program must belong to the organization. Use [List programs](https://developers.pismo.io/pismo-docs/reference/programs-1) to view a list of the program IDs for the organization.\n\nThis program must be bound to the division. You can attach the program with either of the following endpoints:\n[Create division](https://developers.pismo.io/pismo-docs/reference/post-division-v2)\n[Patch division](https://developers.pismo.io/pismo-docs/reference/patch-division-v2)\n",
"example": 8674
},
"ProgramID3": {
"type": "integer",
"format": "int64",
"description": "Program ID. This is a client-provided ID.",
"example": 2222
}
},
"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": {
"post": {
"summary": "Create transaction banking account",
"description": "Creates a transaction banking account. For more details, refer to [Transaction banking accounts](https://developers.pismo.io/pismo-docs/docs/corporate-accounts).\n\nThis endpoint generates the following events:\n - [Corporate account created](https://developers.pismo.io/events/docs/corporate-corporate-account-creation-1).\n - [Account application created](https://developers.pismo.io/events/docs/onboarding-succeeded-1)\n\n For more information on events and setting up event notifications, refer to the [Data and reporting](https://developers.pismo.io/pismo-docs/docs/data-reporting-overview) guide.\n",
"operationId": "post-account",
"tags": [
"Accounts"
],
"requestBody": {
"description": "Create account request body",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateAccountRequest"
}
}
}
},
"responses": {
"200": {
"description": "Create account response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateAccountResponse"
},
"examples": {
"Account created": {
"value": {
"account_id": 178800,
"external_account_id": "b993ba96-b3e8-4ef7-9cf7-7eee5ddafdab",
"program_id": 8086,
"division_code": "my-division"
}
}
}
}
}
},
"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": {
"Invalid JSON payload": {
"value": {
"code": "WCAC0013",
"message": "Invalid JSON payload received: Error unmarshalling request"
}
},
"division_code required": {
"value": {
"code": "WCAC0005",
"message": "division_code is a required field"
}
},
"division_code max length": {
"value": {
"code": "WCAC0005",
"message": "division_code must be a maximum of 36 characters in length"
}
},
"program_id required": {
"value": {
"code": "WCAC0005",
"message": "program_id is a required field"
}
},
"program_id max size": {
"value": {
"code": "WCAC0005",
"message": "program_id must be 99,999,999,999 or less"
}
},
"Program Id not bound to Division": {
"value": {
"code": "WCAC0006",
"message": "Program not bound to Division"
}
},
"applicant.document_number required": {
"value": {
"code": "WCAC0005",
"message": "document_number is a required field"
}
},
"applicant.document_number max length": {
"value": {
"code": "WCAC0005",
"message": "document_number must be a maximum of 15 characters in length"
}
},
"applicant.document_number alphanumeric only": {
"value": {
"code": "WCAC0005",
"message": "document_number can only contain alphanumeric characters"
}
},
"applicant.name required": {
"value": {
"code": "WCAC0005",
"message": "name is a required field"
}
},
"applicant.name max length": {
"value": {
"code": "WCAC0005",
"message": "name must be a maximum of 60 characters in length"
}
},
"applicant.external_id max length": {
"value": {
"code": "WCAC0005",
"message": "external_id must be a maximum of 60 characters in length"
}
},
"parent_account_id max value": {
"value": {
"code": "WCAC0005",
"message": "parent_account_id must be 200,000,000 or less"
}
},
"external_account_id required": {
"value": {
"code": "WCAC0005",
"message": "external_account_id is a required field"
}
},
"external_account_id max length": {
"value": {
"code": "WCAC0005",
"message": "external_account_id must be a maximum of 60 characters in length"
}
},
"overdraft.limit max value": {
"value": {
"code": "WCAC0005",
"message": "limit must be 100,000,000,000,000,000.00 or less"
}
},
"external_account_id contains character not permitted": {
"value": {
"code": "WCAC0005",
"message": "external_account_id contains character not permitted: [characters]"
}
},
"custom_fields don't match with the Division JSON schema": {
"value": {
"code": "WCAC0004",
"message": "schema validation error: [validation description]"
}
},
"parent_account_id invalid": {
"value": {
"code": "WCAC0016",
"message": "parent_account_id informed as Parent Account not exists"
}
},
"currency_numeric_code invalid": {
"value": {
"code": "WCAC0016",
"message": "currency_numeric_code: Invalid Currency Numeric Code"
}
},
"currency_code invalid": {
"value": {
"code": "WCAC0005",
"message": "currency_code: invalid currency code"
}
},
"Not mapped 400 error": {
"value": {
"code": "WCAC0009",
"message": "generic message"
}
},
"Invalid account creation date time format": {
"value": {
"code": "WCAC0005",
"message": "account_creation_datetime should be formatted as yyyy-mm-ddThh:mm:ss.sssZ and be a valid datetime"
}
},
"account creation datetime in the future": {
"value": {
"code": "WCAC0005",
"message": "account_creation_datetime cannot be a future date"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Division not found": {
"value": {
"code": "WDIV0002",
"message": "Division not found"
}
}
}
}
}
},
"409": {
"description": "Conflict.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"external_account_id duplicated": {
"value": {
"code": "WCAC0011",
"message": "Duplicated external_account_id"
}
},
"Account duplicated": {
"value": {
"code": "WCAC0014",
"message": "Duplicate corporate account"
}
}
}
}
}
},
"500": {
"$ref": "#/components/responses/500InternalServer"
}
}
},
"parameters": []
}
}
}
```