> ## 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.
# Get Requirements
> Returns a checklist of everything still required before the account's application can be submitted: missing fields, missing documents and outstanding identity verifications.
Returns a live checklist of everything still required before the account's application can be submitted: missing fields, missing documents and outstanding identity verifications. Use it to drive your own onboarding UI or to verify readiness before calling submit.
## Example Request
```bash theme={null}
curl -X GET "https://api.rolla.xyz/api/v1/external/accounts/eec3cbed-79d8-4370-87a0-b6be9e287337/requirements" \
-H "X-API-Key: your_api_key_here"
```
## Example Response
### Business account
```json theme={null}
{
"success": true,
"message": "Requirements retrieved successfully",
"data": {
"entityType": "business",
"status": "draft",
"readyToSubmit": false,
"missingFields": [
"related_persons.a3d4f21e-f499-488f-8508-43228dfea485.taxId",
"related_persons.a3d4f21e-f499-488f-8508-43228dfea485.sourceOfWealthExplanation"
],
"missingDocuments": [
"certificate_of_incorporation",
"articles_of_association",
"proof_of_address",
"director_register",
"shareholder_register",
"bank_statement"
],
"relatedPersons": [
{
"id": "a3d4f21e-f499-488f-8508-43228dfea485",
"name": "Jane Doe",
"verification": "pending",
"missingFields": [
"related_persons.a3d4f21e-f499-488f-8508-43228dfea485.taxId",
"related_persons.a3d4f21e-f499-488f-8508-43228dfea485.sourceOfWealthExplanation"
],
"missingDocuments": [
"related_persons.a3d4f21e-f499-488f-8508-43228dfea485.proof_of_address",
"related_persons.a3d4f21e-f499-488f-8508-43228dfea485.source_of_wealth_doc"
]
}
]
}
}
```
### Individual account
```json theme={null}
{
"success": true,
"message": "Requirements retrieved successfully",
"data": {
"entityType": "individual",
"status": "draft",
"readyToSubmit": true,
"missingFields": [],
"missingDocuments": [],
"identityVerification": "verified",
"submitBlocker": null
}
}
```
## Why an account is not ready
When `readyToSubmit` is `false`, `submitBlocker` names the reason — the same one [Submit](/api-reference/endpoint/accounts/submit) would return if you called it now. Check it instead of re-deriving the reason from the other fields.
```json theme={null}
{
"submitBlocker": {
"code": "APPLICATION_INCOMPLETE",
"message": "Application is incomplete",
"details": {
"missingFields": ["individualInfo.nin"],
"missingDocuments": ["proof_of_address"]
}
}
}
```
Missing data is reported first. Once the application is complete and identity verification is the only hold, the code becomes `KYC_INCOMPLETE`:
```json theme={null}
{
"submitBlocker": {
"code": "KYC_INCOMPLETE",
"message": "Identity verification is not complete",
"details": { "identityVerification": "pending" }
}
}
```
For a business, `details.unverified` lists who is outstanding:
```json theme={null}
{
"submitBlocker": {
"code": "KYC_INCOMPLETE",
"message": "Not every beneficial owner has completed KYC",
"details": {
"unverified": [
{ "personId": "a3d4f21e-f499-488f-8508-43228dfea485", "name": "Jane Doe" }
]
}
}
}
```
An account can have `identityVerification: "verified"` and still not be submittable — a passed identity check does not mean the application data is complete. `submitBlocker` is what tells the two apart.
## Response Fields
| Field | Type | Description |
| ---------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `readyToSubmit` | boolean | `true` only when **everything** is cleared: no missing fields, no missing documents, and identity verification complete — `identityVerification` for an individual, every entry in `relatedPersons` for a business |
| `missingFields` | string\[] | Required application fields not yet provided, e.g. `business_info.legalName`. Entries prefixed `related_persons..` belong to that person |
| `missingDocuments` | string\[] | Required document types not yet uploaded, including each related person's own documents |
| `relatedPersons` | object\[] | Business only: each related person with their KYC `verification` state (`verified`, `pending`, `unknown`) and their own `missingFields` / `missingDocuments` |
| `identityVerification` | string | Individual only: identity verification state (`verified`, `pending`, `unknown`) |
| `submitBlocker` | object \| null | `null` when the account is ready. Otherwise `code` (`APPLICATION_INCOMPLETE` or `KYC_INCOMPLETE`), a human-readable `message`, and `details` carrying the specifics |
A business must declare **at least one** beneficial owner or director. Until one is added, `missingFields` contains `related_persons`.
## OpenAPI
````yaml GET /accounts/{accountId}/requirements
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/{accountId}/requirements:
get:
summary: Get Requirements
description: >-
Returns a checklist of everything still required before the account's
application can be submitted: missing fields, missing documents and
outstanding identity verifications.
operationId: getAccountRequirements
parameters:
- name: accountId
in: path
required: true
description: >-
Identifier of an account owned by the same user as your API key's
business
schema:
type: string
format: uuid
responses:
'200':
description: Requirements retrieved successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: Requirements retrieved successfully
data:
$ref: '#/components/schemas/AccountRequirements'
'401':
description: Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Account not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
AccountRequirements:
type: object
properties:
entityType:
type: string
enum:
- business
- individual
status:
type: string
enum:
- draft
- submitted
- approved
- rejected
- changes_requested
readyToSubmit:
type: boolean
description: >-
True only when everything is cleared: all required fields and
documents are present AND identity verification is complete —
identityVerification for an individual, every relatedPersons entry
for a business
missingFields:
type: array
items:
type: string
example:
- business_info.legalName
missingDocuments:
type: array
items:
type: string
example:
- certificate_of_incorporation
relatedPersons:
type: array
description: >-
Business accounts only: KYC verification state of each related
person
items:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
verification:
type: string
enum:
- verified
- pending
- unknown
identityVerification:
type: string
enum:
- verified
- pending
- unknown
description: >-
Individual accounts only: identity (ID + liveness) verification
state
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
````