Gravv docs
Docs Agent Sign in Get API keys
API Reference

Create an account

Opens a bank account, with a token wallet where the bank offers one, for a customer whose KYC is completed. First call GET /v1/accounts/capabilities to choose bank_code, currency and account_type, then GET /v2/accounts/requirements to build data.

The response has only account_id and status: pending. Get the account for application_id and status_reason, and poll until it is active, or wait for the applications.accounts.completed webhook. Gravv does not send account.activated for v2 accounts. The API rejects unknown fields. When you retry, reuse the same Idempotency-Key.

POSThttps://api.gravv.xyz/v2/accounts

Headers

Required for POST requests. The key is 1 to 255 printable ASCII characters. A retry with the same key within 24 hours returns the first response, so reuse the key when you retry the same request.

Request Body

Request Examples

{
"customer_id": "0b6f3c1e-2a4d-4c8e-9f10-7d2a6b5e4c33",
"customer_type": "individual",
"currency": "USD",
"account_type": "operating",
"bank_code": "cross_river_bank",
"network": "polygon",
"label": "Jane USD",
"data": {
"root": {
  "first_name": "Jane",
  "last_name": "Doe",
  "date_of_birth": "1990-04-02",
  "email": "jane@example.com",
  "phone_daytime": "+447700900123",
  "gender": "female",
  "citizenship_country": "GB",
  "tax_residence_country": "GB",
  "permanent_address": {
    "address_line": "1 High St",
    "city": "London",
    "state": "GB-LND",
    "postal_code": "EC1A 1BB",
    "country": "GB"
  }
},
"documents": [
  {
    "document_type": "passport",
    "issuing_country": "GB",
    "number": "123456789",
    "issued_date": "2020-01-15",
    "expiration_date": "2030-01-14",
    "filename": "passport.jpg",
    "content": "<base64>"
  },
  {
    "document_type": "proof_of_address",
    "issuing_country": "GB",
    "filename": "bill.pdf",
    "content": "<base64>"
  }
]
}
}

{
"customer_id": "9a1e4c77-2f3b-4d8e-b6a0-5c3e8f9d1b22",
"customer_type": "business",
"currency": "USD",
"account_type": "operating",
"category": "sub_account",
"bank_code": "cross_river_bank",
"wallet_id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
"label": "Acme USD",
"data": {
"root": {
  "legal_name": "Acme Exports Ltd",
  "business_type": "private limited company",
  "industry": "wholesale_trade",
  "registration_number": "12345678",
  "incorporation_country": "GB",
  "incorporation_date": "2015-03-01",
  "tax_id_type": "ein",
  "tax_id_number": "981234567",
  "business_description": "Exports industrial pumps to buyers in North America",
  "business_address": {
    "address_line": "1 Finsbury Avenue",
    "city": "London",
    "state": "GB-LND",
    "postal_code": "EC2M 2PF",
    "country": "GB"
  }
},
"parties": [
  {
    "id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",
    "has_ownership": true,
    "ownership_percentage": 60,
    "has_control": true,
    "is_signer": true,
    "documents": [
      {
        "document_type": "passport",
        "issuing_country": "GB",
        "number": "123456789",
        "issued_date": "2020-01-15",
        "expiration_date": "2030-01-14",
        "filename": "owner-passport.jpg",
        "content": "<base64>"
      },
      {
        "document_type": "proof_of_address",
        "issuing_country": "GB",
        "filename": "owner-bill.pdf",
        "content": "<base64>"
      }
    ]
  }
],
"documents": [
  {
    "document_type": "articles_of_incorporation",
    "issuing_country": "GB",
    "filename": "articles.pdf",
    "content": "<base64>"
  },
  {
    "document_type": "ownership_document",
    "issuing_country": "GB",
    "filename": "shareholders.pdf",
    "content": "<base64>"
  },
  {
    "document_type": "proof_of_address",
    "issuing_country": "GB",
    "filename": "company-bill.pdf",
    "content": "<base64>"
  },
  {
    "document_type": "control_structure",
    "issuing_country": "GB",
    "filename": "org-chart.pdf",
    "content": "<base64>"
  }
]
}
}

{
"customer_id": "7c8d9e0f-1a2b-4c3d-9e4f-5a6b7c8d9e0f",
"customer_type": "individual",
"currency": "EUR",
"account_type": "operating",
"category": "sub_account",
"bank_code": "lead_bank",
"network": "polygon",
"label": "Lucas EUR",
"data": {
"root": {
  "first_name": "Lucas",
  "last_name": "Ferreira",
  "date_of_birth": "1993-08-21",
  "email": "lucas.ferreira@example.com",
  "citizenship_country": "PT",
  "tax_residence_country": "PT",
  "immigration_status": "non_resident",
  "permanent_address": {
    "address_line": "Rua Augusta 100",
    "city": "Lisboa",
    "state": "PT-11",
    "postal_code": "1100-053",
    "country": "PT"
  },
  "international_supplement": {
    "has_us_bank_account": false,
    "has_denied_bank_account": false,
    "has_regulatory_action": false,
    "is_politically_exposed": false
  },
  "expected_activity": {
    "expected_avg_daily_balance": 3000,
    "ach_in": {
      "monthly_count": 0,
      "monthly_amount": 0
    }
  }
},
"documents": [
  {
    "document_type": "national_id",
    "document_type_side": "front",
    "issuing_country": "PT",
    "number": "123456789ZZ1",
    "issued_date": "2021-02-01",
    "expiration_date": "2031-02-01",
    "filename": "id-front.jpg",
    "content": "<base64>"
  },
  {
    "document_type": "proof_of_address",
    "issuing_country": "PT",
    "filename": "bill.pdf",
    "content": "<base64>"
  }
]
}
}

{
"customer_id": "4b7d1e2a-9c3f-4a5b-8d6e-0f1a2b3c4d5e",
"customer_type": "business",
"currency": "USD",
"account_type": "operating",
"category": "sub_account",
"bank_code": "<bank_code>",
"label": "Rocky Mountain Bakery USD",
"data": {
"root": {
  "legal_name": "Rocky Mountain Bakery LLC",
  "email": "accounts@rockymountainbakery.example",
  "registration_number": "20151234567",
  "incorporation_country": "US",
  "incorporation_date": "2015-06-01",
  "tax_id_type": "ein",
  "tax_id_number": "841234567",
  "industry": "manufacturing",
  "business_status": "operating",
  "business_entity_type": "llc",
  "llc_taxed_as": "partnership",
  "business_address": {
    "address_line": "1600 Pearl Street",
    "city": "Denver",
    "state": "US-CO",
    "postal_code": "80202",
    "country": "US"
  },
  "expected_activity": {
    "expected_avg_daily_balance": 25000,
    "ach_in": {
      "monthly_count": 40,
      "monthly_amount": 60000
    }
  }
},
"parties": [
  {
    "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
    "party_role": "primary",
    "date_of_birth": "1984-11-02",
    "citizenship_country": "US",
    "has_ownership": true,
    "ownership_percentage": 100,
    "tax_id_type": "ssn",
    "tax_id_number": "123456780",
    "permanent_address": {
      "address_line": "88 Elm Avenue",
      "city": "Denver",
      "state": "US-CO",
      "postal_code": "80203",
      "country": "US"
    },
    "mailing_address": {
      "address_line": "88 Elm Avenue",
      "city": "Denver",
      "state": "US-CO",
      "postal_code": "80203",
      "country": "US"
    },
    "documents": [
      {
        "document_type": "drivers_license",
        "document_type_side": "front",
        "issuing_country": "US",
        "number": "D1234567",
        "issued_date": "2022-04-10",
        "expiration_date": "2030-04-10",
        "filename": "dl-front.jpg",
        "content": "<base64>"
      }
    ]
  }
],
"documents": [
  {
    "document_type": "articles_of_incorporation",
    "issuing_country": "US",
    "filename": "articles.pdf",
    "content": "<base64>"
  },
  {
    "document_type": "ownership_document",
    "issuing_country": "US",
    "filename": "operating-agreement.pdf",
    "content": "<base64>"
  },
  {
    "document_type": "proof_of_address",
    "issuing_country": "US",
    "filename": "lease.pdf",
    "content": "<base64>"
  },
  {
    "document_type": "control_structure",
    "issuing_country": "US",
    "filename": "control.pdf",
    "content": "<base64>"
  }
]
}
}

{
"customer_id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
"customer_type": "individual",
"currency": "GBP",
"account_type": "operating",
"category": "sub_account",
"bank_code": "<bank_code>",
"label": "Jane GBP",
"data": {
"root": {
  "first_name": "Jane",
  "last_name": "Doe",
  "date_of_birth": "1990-04-02",
  "birth_place": "Leeds",
  "email": "jane@example.com",
  "phone_daytime": "+447700900123",
  "citizenship_country": "GB",
  "permanent_address": {
    "address_line": "1 High St",
    "city": "London",
    "postal_code": "EC1A 1BB",
    "country": "GB"
  }
},
"documents": [
  {
    "document_type": "passport",
    "issuing_country": "GB",
    "number": "123456789",
    "issued_date": "2020-01-15",
    "expiration_date": "2030-01-14",
    "filename": "passport.jpg",
    "content": "<base64>"
  },
  {
    "document_type": "proof_of_address",
    "issuing_country": "GB",
    "filename": "bill.pdf",
    "content": "<base64>"
  }
]
}
}

{
"customer_id": "5b0f6c1e-2a8f-4c39-9d0e-0c7e3b9a1f42",
"customer_type": "individual",
"currency": "NGN",
"account_type": "operating",
"category": "sub_account",
"label": "Chidi NGN",
"data": {
"root": {
  "first_name": "Chidi",
  "middle_name": "Emeka",
  "last_name": "Okafor",
  "phone": "+2348031234567",
  "bank_verification_number": "22123456789"
}
}
}

{
"customer_id": "8e9f0a1b-2c3d-4e5f-8a6b-7c8d9e0f1a2b",
"customer_type": "business",
"currency": "KES",
"account_type": "operating",
"category": "sub_account",
"label": "Savanna KES",
"data": {
"root": {
  "legal_name": "Savanna Traders Ltd",
  "incorporation_country": "KE"
}
}
}

Responses

Status Description
200 Account opening started
400 Invalid request, a customer that does not exist or has not completed KYC, or no bank fits the request
409 The customer is at the account limit, the bank is disabled for this account, an application is already in progress at this bank, or a request with the same Idempotency-Key is still running
422 You used the Idempotency-Key before with a different body.
503 Gravv could not read the customer record. Retry with the same key.

200 response

Possible values: pending

 
{
"data": {
"account_id": "6f1c2a9e-3b1d-4f7a-9c62-0d8e4b7a5c11",
"status": "pending"
},
"error": null
}

400 response

Error message. When several fields fail, it names the first and says how many others are in details. Branch on the HTTP status and the details codes, not on this text.

Field problems, keyed by field path. Each value is CODE: message, such as REQUIRED: Customer ID is required. The API joins several problems on one field with ; .

 
{
"data": null,
"error": "the customer for the customer_id supplied has not completed KYC; complete the customer's KYC before opening an account for them",
"details": {
"customer_id": "CUSTOMER_KYC_INCOMPLETE: the customer for the customer_id supplied has not completed KYC; complete the customer's KYC before opening an account for them"
}
}

{
"data": null,
"error": "Date of Birth is required (and 1 other field; see details)",
"details": {
"date_of_birth": "required: is required",
"permanent_address.city": "required: is required"
}
}

{
"data": null,
"error": "network is required for account options that support wallet integration"
}

409 response

One of the following variants:

Error message. When several fields fail, it names the first and says how many others are in details. Branch on the HTTP status and the details codes, not on this text.

Field problems, keyed by field path. Each value is CODE: message, such as REQUIRED: Customer ID is required. The API joins several problems on one field with ; .

Possible values: idempotency_in_flight, idempotency_key_reused

 
{
"data": null,
"error": "this customer already holds the maximum number of USD accounts permitted for this account type (5)"
}

422 response

Possible values: idempotency_in_flight, idempotency_key_reused

503 response

Error message. When several fields fail, it names the first and says how many others are in details. Branch on the HTTP status and the details codes, not on this text.

Field problems, keyed by field path. Each value is CODE: message, such as REQUIRED: Customer ID is required. The API joins several problems on one field with ; .

Authorization

  • ApiKeyAuth
Was this page helpful?
ESC