> ## 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.

# Submit Application

> Validates that the application is complete and submits it for review. Returns the outstanding items if anything is missing. For business accounts, every related person must have completed KYC before submission.

Validates that the account's application is complete and submits it for compliance review. If anything is missing, the response lists exactly what's outstanding.

## Example Request

```bash theme={null}
curl -X POST "https://api.rolla.xyz/api/v1/external/accounts/b6075be0-f1d0-451f-a468-3e94563101d2/submit" \
  -H "X-API-Key: your_api_key_here"
```

## Example Response

```json theme={null}
{
  "success": true,
  "message": "Application submitted successfully",
  "data": {
    "application": {
      "id": "f436daf8-146b-4949-bf28-9b36440085a4",
      "status": "submitted",
      "is_complete": true,
      "entity_type": "individual"
    },
    "documents": [
      {
        "document_type": "proof_of_address",
        "file_name": "bank_statement.pdf"
      }
    ]
  }
}
```

## Error Responses

<Info>
  When more than one thing is outstanding you get the most actionable one first: missing fields or documents are reported as `400 APPLICATION_INCOMPLETE` and always list what is missing; `409 KYC_INCOMPLETE` is returned only once the application data is complete and identity verification is the sole remaining hold.
</Info>

### Application incomplete (`400`)

```json theme={null}
{
  "status": 400,
  "message": "Application is incomplete",
  "code": "APPLICATION_INCOMPLETE",
  "missingFields": [
    "related_persons.a3d4f21e-f499-488f-8508-43228dfea485.taxId"
  ],
  "missingDocuments": ["proof_of_address"]
}
```

Per-person entries are prefixed `related_persons.<personId>.`, so you can tell which
representative each one belongs to. [Get Requirements](/api-reference/endpoint/accounts/requirements)
reports the same list without attempting a submit.

To find out what a submit would return without calling it, read `submitBlocker` on
[Get Requirements](/api-reference/endpoint/accounts/requirements) — it carries the same
`code` and details as the errors below.

### No beneficial owners declared (`400`)

```json theme={null}
{
  "status": 400,
  "message": "A business must declare at least one beneficial owner or director before submission",
  "code": "BENEFICIAL_OWNERS_REQUIRED"
}
```

### Identity not verified — individual (`409`)

```json theme={null}
{
  "status": 409,
  "message": "Identity verification must be completed before the application can be submitted",
  "code": "KYC_INCOMPLETE",
  "identityVerification": "pending"
}
```

### Related persons not verified — business (`409`)

```json theme={null}
{
  "status": 409,
  "message": "All beneficial owners must complete KYC before submission",
  "code": "KYC_INCOMPLETE",
  "unverified": [
    {
      "personId": "a3d4f21e-f499-488f-8508-43228dfea485",
      "name": "Jane Doe"
    }
  ]
}
```

## Key Behaviours

<Info>
  **Individual accounts:** the applicant must complete their [KYC link](/api-reference/endpoint/accounts/individual-kyc-link) before submission. Until they do, `readyToSubmit` is `false` and this endpoint returns `409 KYC_INCOMPLETE`.
</Info>

<Info>
  **Business accounts:** at least one beneficial owner or director must be declared, and every one of them must have completed identity verification. Generate [KYC links](/api-reference/endpoint/accounts/kyc-link) for any `unverified` person — or, if you verify identity yourself, [submit reliance](/api-reference/endpoint/accounts/related-person-kyc-reliance) for them — and retry once they finish.
</Info>

<Info>
  **Every related person needs a government identifier** — `taxId`, or `nin` for Nigerian residents. It is *not* required when you add the person, only here at submission, where a missing one appears as `related_persons.<personId>.taxId` in `missingFields`. It can be patched onto an existing person with [Update Related Person](/api-reference/endpoint/accounts/update-related-person), so representatives added without one do not need re-creating. See [the per-country formats](/api-reference/endpoint/accounts/add-related-person#government-identifier).
</Info>

<Warning>
  Submitted applications are locked for editing. If the review team requests changes, the application reopens with a `changes_requested` status and a note explaining what to fix.
</Warning>


## OpenAPI

````yaml POST /accounts/{accountId}/submit
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}/submit:
    post:
      summary: Submit Application
      description: >-
        Validates that the application is complete and submits it for review.
        Returns the outstanding items if anything is missing. For business
        accounts, every related person must have completed KYC before
        submission.
      operationId: submitAccount
      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: Application submitted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Application submitted successfully
                  data:
                    type: object
                    properties:
                      application:
                        $ref: '#/components/schemas/KybApplication'
                      documents:
                        type: array
                        items:
                          $ref: '#/components/schemas/KybDocument'
        '400':
          description: Application incomplete
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 400
                  message:
                    type: string
                    example: Application is incomplete
                  code:
                    type: string
                    example: APPLICATION_INCOMPLETE
                  missingFields:
                    type: array
                    items:
                      type: string
                  missingDocuments:
                    type: array
                    items:
                      type: string
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Already submitted, or related persons have not completed KYC
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 409
                  message:
                    type: string
                    example: All beneficial owners must complete KYC before submission
                  code:
                    type: string
                    example: KYC_INCOMPLETE
                  unverified:
                    type: array
                    items:
                      type: object
                      properties:
                        personId:
                          type: string
                        name:
                          type: string
components:
  schemas:
    KybApplication:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - draft
            - submitted
            - approved
            - rejected
            - changes_requested
        current_step:
          type: integer
        is_complete:
          type: boolean
        business_info:
          $ref: '#/components/schemas/BusinessInfo'
        business_address:
          $ref: '#/components/schemas/BusinessAddress'
        contact_info:
          $ref: '#/components/schemas/ContactInfo'
        related_persons:
          type: array
          items:
            $ref: '#/components/schemas/RelatedPerson'
        banking_info:
          $ref: '#/components/schemas/BankingInfo'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    KybDocument:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Document identifier
        applicationId:
          type: string
          description: Associated KYB application ID
        documentType:
          type: string
          description: Type of document
          enum:
            - certificate_of_incorporation
            - articles_of_association
            - proof_of_address
            - director_register
            - shareholder_register
        fileName:
          type: string
          description: Uploaded file name
        fileUrl:
          type: string
          format: uri
          description: Document download URL
        relatedPersonKey:
          type: string
          description: Associated related person
        created_at:
          type: string
          format: date-time
          description: Upload timestamp
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
    BusinessInfo:
      type: object
      properties:
        legalName:
          type: string
          example: Acme Corp Ltd
        tradingName:
          type: string
        businessType:
          type: string
          example: Limited Company
        incorporationDate:
          type: string
          example: '2020-01-15'
        incorporationCountry:
          type: string
          example: NG
        registrationNumber:
          type: string
          example: RC-1234567
        taxId:
          type: string
          example: 12345678-0001
        website:
          type: string
          format: uri
        description:
          type: string
        monthlyVolume:
          type: string
        annualRevenue:
          type: string
        primaryFundingSource:
          type: string
    BusinessAddress:
      type: object
      properties:
        street:
          type: string
          example: 123 Main Street
        city:
          type: string
          example: Lagos
        state:
          type: string
          example: Lagos
        postalCode:
          type: string
          example: '100001'
        country:
          type: string
          example: NG
    ContactInfo:
      type: object
      properties:
        email:
          type: string
          format: email
          example: contact@acmecorp.com
        phone:
          type: string
          example: '+2341234567890'
    RelatedPerson:
      type: object
      properties:
        id:
          type: string
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: Doe
        roles:
          type: array
          items:
            type: string
            enum:
              - Beneficial Owner
              - Director
        email:
          type: string
          format: email
        phone:
          type: string
        dateOfBirth:
          type: string
          example: '1990-01-15'
        ownershipPercentage:
          type: number
          minimum: 0
          maximum: 100
        currentAddress:
          $ref: '#/components/schemas/BusinessAddress'
        sourceOfWealthExplanation:
          type: string
        taxId:
          type: string
          description: >-
            The person's government identifier, in the format their country of
            residence issues — Mainland China: 18-character resident ID; Hong
            Kong: HKID; United States: SSN or ITIN; elsewhere: national ID or
            tax number as issued. Nigerian residents send `nin` instead.
            Required before the application can be submitted, and can be patched
            onto an existing person. The format is validated by the USD provider
            when the account is issued.
          example: '440301199209153216'
        bvn:
          type: string
          description: Bank Verification Number (11 digits). Nigerian residents only.
        nin:
          type: string
          description: >-
            National Identification Number (11 digits). Nigerian residents only;
            accepted in place of `taxId`.
    BankingInfo:
      type: object
      properties:
        bankName:
          type: string
        accountNumber:
          type: string
        routingNumber:
          type: string
        accountType:
          type: string
          enum:
            - checking
            - savings
        currency:
          type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your Rolla API key

````