> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rolla.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Account
> Creates an additional business or individual account under the same owner as your API key's business. The new account starts as a draft KYB/KYC application that you complete via the other account onboarding endpoints.
Creates an additional business or individual account under the same owner as your API key's business. The new account starts as a draft application that you complete with the other account onboarding endpoints.
**White-label partners only.** The entire account onboarding API (this endpoint and everything under `/accounts`) is available only to businesses activated as white-label tenants. A non-tenant API key receives `403 Forbidden`.
## Example Request
### Business account
```bash theme={null}
curl -X POST "https://api.rolla.xyz/api/v1/external/accounts" \
-H "X-API-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"type": "business",
"name": "Beta Logistics LLC",
"email": "ops@betalogistics.com"
}'
```
### Individual account
```bash theme={null}
curl -X POST "https://api.rolla.xyz/api/v1/external/accounts" \
-H "X-API-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"type": "individual",
"firstName": "Jane",
"lastName": "Doe",
"email": "jane.doe@example.com"
}'
```
## Example Response
```json theme={null}
{
"success": true,
"message": "Account created successfully",
"data": {
"account": {
"id": "eec3cbed-79d8-4370-87a0-b6be9e287337",
"name": "Beta Logistics LLC",
"email": "ops@betalogistics.com",
"status": "created",
"entityType": "business"
},
"applicationId": "fbb45236-881a-4c58-8954-22759499eab4",
"applicationStatus": "draft"
}
}
```
## Parameters
| Field | Type | Required | Description |
| ----------- | ------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | string | Yes | `business` or `individual` |
| `name` | string | For business | Legal or trading name of the business |
| `firstName` | string | No | Account holder first name (individual accounts); defaults to the owner's name |
| `lastName` | string | No | Account holder last name (individual accounts); defaults to the owner's name |
| `email` | string | **Yes** | The account's own contact email. **Required**, and must be **unique** across your accounts — every account you onboard is a distinct customer with its own email. |
`email` is **required** and must be unique. Omitting it returns `400`. Creating a
second account with the same `email` under your business returns `409 Conflict`
with `code: "ACCOUNT_EMAIL_EXISTS"`.
## OpenAPI
````yaml POST /accounts
openapi: 3.1.0
info:
title: Rolla Developer API
description: >-
API for programmatic transaction management on the Rolla platform. Monetary
`amount` fields use the smallest unit of the referenced currency unless an
endpoint says otherwise (e.g. NGN = kobo, USD = cents, where **100 cents =
USD 1.00**).
version: 1.0.0
servers:
- url: https://api.rolla.xyz/api/v1/external
description: Production server
security:
- apiKeyAuth: []
paths:
/accounts:
post:
summary: Create Account
description: >-
Creates an additional business or individual account under the same
owner as your API key's business. The new account starts as a draft
KYB/KYC application that you complete via the other account onboarding
endpoints.
operationId: createAccount
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAccountRequest'
responses:
'201':
description: Account created successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: Account created successfully
data:
type: object
properties:
account:
$ref: '#/components/schemas/Account'
applicationId:
type: string
format: uuid
applicationStatus:
type: string
example: draft
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: >-
Your business is not a white-label tenant. The entire /accounts
onboarding API (create, onboard, issue bank accounts, list, get) is
available to white-label partners only.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
status: 403
message: >-
Account onboarding is available to white-label partners only.
Contact Rolla to enable white-label for your business.
'409':
description: >-
An account with this email already exists for this owner (code:
ACCOUNT_EMAIL_EXISTS). Only returned when a distinct `email` is
supplied.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
success: false
message: An account with this email already exists for this owner.
code: ACCOUNT_EMAIL_EXISTS
components:
schemas:
CreateAccountRequest:
type: object
required:
- type
- email
properties:
type:
type: string
enum:
- business
- individual
description: Type of account to create
name:
type: string
description: Business name. Required when type is `business`.
firstName:
type: string
description: >-
Account holder first name (individual accounts). Defaults to the
owner's name.
lastName:
type: string
description: >-
Account holder last name (individual accounts). Defaults to the
owner's name.
email:
type: string
format: email
description: >-
The account's own contact email. REQUIRED, and must be unique among
your accounts — every account you onboard is a distinct customer
with its own email. A duplicate (same owner) returns 409 with code
ACCOUNT_EMAIL_EXISTS; omitting it returns 400.
Account:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
example: Beta Logistics LLC
email:
type: string
format: email
description: Owner's email (shared across all of the owner's accounts)
entityType:
type: string
enum:
- business
- individual
applicationId:
type: string
format: uuid
applicationStatus:
type: string
enum:
- draft
- submitted
- approved
- rejected
- changes_requested
currentStep:
type: integer
example: 1
isComplete:
type: boolean
createdAt:
type: string
format: date-time
Error:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: Your Rolla API key
````