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

📘 Before you start

The customer must already exist and have completed KYC.

Application lifecycle

An account application progresses through the following statuses:

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 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:

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 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 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. This moves the application from draft to submitted and runs validation. If validation_errors come back, then fix the data with Update account application, then submit again.

Process the application

Call Process account application. This runs onboarding and account creation. Processing can complete immediately or move to manual review:

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

Track the application status

Call Get account application 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 endpoint returns the audit trail of status changes.