---
title: "Create an account application"
---
An account application opens a bank-backed account for a customer. You submit the customer's KYC or KYB details, Gravv runs them through onboarding, and on approval issues an internal account with a wallet and virtual account.

Use this flow when the account needs bank onboarding. For a simple wallet-backed account, use [Create an account](/platform/accounts/create-an-account) instead.

> 📘 Before you start
>
> The customer must already exist and have completed [KYC](/getting-started/know-your-customer).

## Application lifecycle

An account application progresses through the following statuses:

```mermaid title="Account application status flow"
flowchart LR
    draft --> submitted --> processing --> approved

    processing --> manual_review
    manual_review --> approved
    manual_review --> rejected
    processing --> rejected
    processing --> expired
```

## Create and process the application

Each of the following subsections describes a step in the application process. Each step calls a single endpoint and moves the application toward `approved`.

### Create the application

To create an account application, call the [Create account application](/api-reference/accounts/post-v1-accounts-applications) endpoint. You do not need to select a bank. Gravv chooses one based on the application type, account type, and the data you provide.

Include these fields in the request body:

* `application_type`: `individual` or `business`

* In the `data` object:

  * `account_type`: `regular` or `savings`

  * `currency`

  * `blockchain_network`

  * A KYC object that matches the application type:
    * `individual` for an individual application

    * `business` for a business application

  > 📘 **Application type vs account type**
  >
  > `application_type` identifies the customer as `individual` or `business`.
  > `account_type` identifies the account as `regular` or `savings`.
  >
  > Choose an `application_type` and an `account_type` independently.

The following is a sample request:

```bash title="create a business account application"
curl --request POST \
     --url https://api.gravv.xyz/v1/accounts/applications \
     --header 'Api-Key: <API_KEY>' \
     --header 'Idempotency-Key: account-application-<UUID>' \
     --header 'content-type: application/json' \
     --data '
{
  "customer_id": "<customer id>",
  "application_type": "business",
  "data": {
    "account_type": "regular",
    "currency": "USD",
    "blockchain_network": "polygon",
    "business": {
      "legal_name": "Acme Corp",
      "type": "corporation",
      "tax_id_number": "12-3456789",
      "date_of_incorporation": "2020-01-15",
      "country_of_incorporation": "US",
      "associated_persons": [
        {
          "first_name": "John",
          "last_name": "Doe",
          "email": "john@example.com",
          "date_of_birth": "1980-01-01",
          "has_ownership": true,
          "has_control": true
        }
      ],
      "formation_document": "data:application/pdf;base64,...",
      "proof_of_address_document": "data:application/pdf;base64,..."
    }
  }
}
'
```

The response returns the application with its `id` and `status: draft`.

### Accept the terms of service

Call [Complete TOS acceptance](/api-reference/accounts/post-v1-accounts-applications-tos) with the `application_id` and the `agreement_id`. The application must be in `draft`. You must accept the terms before you can submit.

### Validate the application data

Optionally, call [Validate application data](/api-reference/accounts/post-v1-accounts-applications-validate) to check the payload against the onboarding rules without saving the application. The endpoint returns `valid` and any `validation_errors`, so you can catch problems before submitting.

### Submit the application

Call [Submit account application](/api-reference/accounts/post-v1-accounts-applications-id-submit). This moves the application from `draft` to `submitted` and runs validation. If `validation_errors` come back, then fix the data with [Update account application](/api-reference/accounts/put-v1-accounts-applications-id), then submit again.

### Process the application

Call [Process account application](/api-reference/accounts/post-v1-accounts-applications-id-process). This runs onboarding and account creation. Processing can complete immediately or move to manual review:

```text
submitted → processing → approved
                       ↘ manual_review → approved or rejected
```

On approval, Gravv creates the internal account and its virtual account.

To submit and process in a single call, use the [Submit and process application](/api-reference/accounts/post-v1-accounts-applications-id-submit-and-process) endpoint.

### Track the application status

Call [Get account application](/api-reference/accounts/get-v1-accounts-applications-id) until the status is `approved`, `rejected`, or `expired`. A `manual_review` status means the application needs a human decision; display the safe `reason` when it is returned. Calling the [Get application history](/api-reference/accounts/get-v1-accounts-applications-id-history) endpoint returns the audit trail of status changes.

## Required data

The required KYC data depends on the application type:

* For an `individual` application, include an `individual` object in `data`.
* For a `business` application, include a `business` object in `data`.

### Individual applications

The `individual` object must include:

* `first_name`
* `last_name`
* `email`
* `date_of_birth`

Depending on your account configuration, additional identity, address, and source-of-funds information may also be required.

### Business applications

The `business` object must include:

* `legal_name`
* `type` (`corporation`, `llc`, `partnership`, or `sole_proprietorship`)
* `tax_id_number`
* `date_of_incorporation`
* `country_of_incorporation`
* At least one entry in `associated_persons`

Each `associated_persons` entry must include:

* `first_name`
* `last_name`
* `email`
* `date_of_birth`
* `has_ownership`
* `has_control`

The `business` object must also include:

* `formation_document`
* `proof_of_address_document`

You must also accept the terms and conditions before submitting the application.