--- title: "Create account application" description: "Create a new account application for a given customer." protocol: rest method: POST endpoint: "/v1/accounts/applications" baseUrl: "https://api.gravv.xyz" group: "Accounts" auth: label: "Api-Key" name: "Api-Key" in: header --- # Create account application Create a new account application for a given customer. For sandbox and testing integrations, use `polygon` as the `blockchain_network`. ## Headers Required for POST requests. Reuse the key only when retrying the same operation with an identical payload. ## Request Body UUID of the customer submitting the application. Type of application. One of individual or business. Possible values: `individual`, `business` Application data including KYC information and account configuration. First name of the individual. Required. Last name of the individual. Required. Middle name of the individual. Email address of the individual. Required. Role of the individual in the application (for example, owner). Phone number of the individual, in E.164 format. May be required depending on your account configuration. Date of birth of the individual, in YYYY-MM-DD format. Required. Gender of the individual. Nationality of the individual, in ISO 3166-1 alpha-2 format. Social Security Number of the individual. May be required depending on your account configuration. Tax Identification Number of the individual. May be required depending on your account configuration. Primary source of income. May be required. One of employment, self_employment, investments, retirement, or other. Current employment status of the individual (for example, employed or self_employed). Country of citizenship, in ISO 3166-1 alpha-2 format. May be required depending on your account configuration. Type of government-issued ID. May be required. One of drivers_license, passport, or state_id. Document number of the government-issued ID. May be required depending on your account configuration. Country that issued the identification document, in ISO 3166-1 alpha-2 format. Expiry date of the identification document, in YYYY-MM-DD format. Street address, PO box, company name, c/o Apartment, suite, unit, building, floor, etc. City State, province, county ZIP or postal code Country (ISO 3166-1 alpha-2) Front of the government-issued ID, as a Base64 data URI. May be required depending on your account configuration. Back of the government-issued ID, as a Base64 data URI. Proof of address document, as a Base64 data URI. Sources of the individual's wealth. May be required depending on your account configuration. Free-text description of the source of wealth when not covered by the standard options. Purposes for opening the account. May be required depending on your account configuration. Free-text description of account purposes when not covered by the standard options. Sources of funds for the account. May be required depending on your account configuration. Free-text description of the source of funds when not covered by the standard options. Countries where the individual expects to transact, in ISO 3166-1 alpha-2 format. May be required depending on your account configuration. Expected monthly volume of fiat transactions. May be required depending on your account configuration. Expected monthly volume of crypto transactions. Registered legal name of the business. Required. Trading name or DBA (doing business as) name of the business. Description of the business operations. May be required (minimum 100 characters). Legal entity type of the business (for example, llc or corporation). Required. Industry category of the business. May be required depending on your account configuration. Public-facing website URL of the business. Official registration or incorporation number of the business. Tax Identification Number (TIN) of the business. May be required depending on your account configuration. Date the business was incorporated, in YYYY-MM-DD format. Country where the business is incorporated, in ISO 3166-1 alpha-2 format. Some account configurations require this to be US. US state where the business is incorporated. May be required depending on your account configuration. Current operating status of the business (for example, active or inactive). Street address, PO box, company name, c/o Apartment, suite, unit, building, floor, etc. City State, province, county ZIP or postal code Country (ISO 3166-1 alpha-2) Street address, PO box, company name, c/o Apartment, suite, unit, building, floor, etc. City State, province, county ZIP or postal code Country (ISO 3166-1 alpha-2) Street address, PO box, company name, c/o Apartment, suite, unit, building, floor, etc. City State, province, county ZIP or postal code Country (ISO 3166-1 alpha-2) First name of the individual. Required. Last name of the individual. Required. Middle name of the individual. Email address of the individual. Required. Role of the individual in the application (for example, owner). Phone number of the individual, in E.164 format. May be required depending on your account configuration. Date of birth of the individual, in YYYY-MM-DD format. Required. Gender of the individual. Nationality of the individual, in ISO 3166-1 alpha-2 format. Social Security Number of the individual. May be required depending on your account configuration. Tax Identification Number of the individual. May be required depending on your account configuration. Primary source of income. May be required. One of employment, self_employment, investments, retirement, or other. Current employment status of the individual (for example, employed or self_employed). Country of citizenship, in ISO 3166-1 alpha-2 format. May be required depending on your account configuration. Type of government-issued ID. May be required. One of drivers_license, passport, or state_id. Document number of the government-issued ID. May be required depending on your account configuration. Country that issued the identification document, in ISO 3166-1 alpha-2 format. Expiry date of the identification document, in YYYY-MM-DD format. Street address, PO box, company name, c/o Apartment, suite, unit, building, floor, etc. City State, province, county ZIP or postal code Country (ISO 3166-1 alpha-2) Front of the government-issued ID, as a Base64 data URI. May be required depending on your account configuration. Back of the government-issued ID, as a Base64 data URI. Proof of address document, as a Base64 data URI. Sources of the individual's wealth. May be required depending on your account configuration. Free-text description of the source of wealth when not covered by the standard options. Purposes for opening the account. May be required depending on your account configuration. Free-text description of account purposes when not covered by the standard options. Sources of funds for the account. May be required depending on your account configuration. Free-text description of the source of funds when not covered by the standard options. Countries where the individual expects to transact, in ISO 3166-1 alpha-2 format. May be required depending on your account configuration. Expected monthly volume of fiat transactions. May be required depending on your account configuration. Expected monthly volume of crypto transactions. Provide at least one associated person. First name of the associated person. Last name of the associated person. Middle name of the associated person. Email address of the associated person. Phone number of the associated person, in E.164 format. Date of birth of the associated person, in YYYY-MM-DD format. Country of citizenship, in ISO 3166-1 alpha-2 format. Social Security Number of the associated person. Job title of the associated person (for example, CEO or CFO). Role of the associated person in the business (for example, director or officer). Indicates whether the person holds an ownership stake in the business. Indicates whether the person has control over the business. Indicates whether the person is an authorized signer on the account. Indicates whether the person is a director of the business. Percentage of the business owned by this person. Street address, PO box, company name, c/o Apartment, suite, unit, building, floor, etc. City State, province, county ZIP or postal code Country (ISO 3166-1 alpha-2) Type of government-issued ID (for example, passport or drivers_license). Document number of the government-issued ID. Country that issued the identification document, in ISO 3166-1 alpha-2 format. Expiry date of the identification document, in YYYY-MM-DD format. Front of the government-issued ID, as a Base64 data URI. Back of the government-issued ID, as a Base64 data URI. Proof of address document, as a Base64 data URI. Indicates whether the business has ownership held through a material intermediary. Business formation document, as a Base64 data URI. Document showing the ownership structure of the business, as a Base64 data URI. Proof of business address, as a Base64 data URI. Document that verifies the nature of the business, as a Base64 data URI. Indicates whether the business is a decentralized autonomous organization (DAO). Primary purpose for opening the account (for example, operations or payroll). Primary source of business funds (for example, revenue or investment). Subtype of financial services industry, if applicable. Subtype of crypto industry, if applicable. Description of the industry when it does not fit a standard category. Countries where the business expects to transact, in ISO 3166-1 alpha-2 format. Sources of funds for the account. May be required depending on your account configuration. Free-text description of the source of funds when not covered by the standard options. Document verifying the business TIN, as a Base64 data URI. May be required depending on your account configuration. Authorization document for the account, as a Base64 data URI. May be used depending on your account configuration. Indicates whether the business is a money services business (MSB). Purposes for opening the account. May be required depending on your account configuration. Free-text description of account purposes when not covered by the standard options. Primary geographic market the business targets. Free-text description of the primary target market when not covered by the standard options. Expected monthly volume of fiat transactions. Expected monthly volume of crypto transactions. Kind of account to open (for example, regular or savings). This is the account type, not the customer type. Use the top-level application_type field for individual vs business. Possible values: `regular`, `savings` Currency for the account, in ISO 4217 format. Blockchain network to back the account (for example, polygon or stellar). Blockchain wallet address to associate with the account. UUID of an existing Gravv wallet to link to the account. Human-readable label for the account. ID of the provider agreement associated with this application. URL to the terms of service the applicant must accept. Arbitrary key-value pairs for storing additional information about the application. ### Request Examples ```json title="Individual application" { "customer_id": "123e4567-e89b-12d3-a456-426614174000", "application_type": "individual", "data": { "account_type": "regular", "currency": "USD", "blockchain_network": "polygon", "wallet_address": "0x123...", "wallet_id": "123e4567-e89b-12d3-a456-426614174000", "label": "ops", "agreement_id": "agr_123", "tos_link": "https://example.com/tos", "tier": "tier_1", "metadata": { "source": "web" }, "individual": { "first_name": "John", "last_name": "Doe", "middle_name": "Robert", "email": "john.doe@example.com", "role": "owner", "phone": "+14155552671", "date_of_birth": "1980-01-01", "gender": "male", "nationality": "US", "ssn": "000000000", "tin": "000000000", "income_source": "employment", "employment_status": "employed", "citizenship": "US", "identification_type": "passport", "identification_number": "P1234567", "identification_country": "US", "identification_expiry": "2030-01-01", "address": { "street_line_1": "123 Main St", "street_line_2": "Apt 4B", "city": "San Francisco", "state": "CA", "postal_code": "94105", "country": "US" }, "id_document_front": "data:application/pdf;base64,...", "id_document_back": "data:application/pdf;base64,...", "proof_of_address_document": "data:application/pdf;base64,...", "source_of_wealth": [ "SALARY" ], "source_of_wealth_other_description": "Salary from tech job", "account_purposes": [ "PERSONAL_BANKING" ], "account_purposes_other_description": "Personal savings", "source_of_funds_list": [ "INCOME" ], "source_of_funds_other_description": "Income", "expected_counterparty_countries": [ "US", "GB" ], "expected_fiat_monthly_volume": "10000_TO_50000", "expected_crypto_monthly_volume": "10000_TO_50000" } } } ``` ```json title="Business application" { "customer_id": "123e4567-e89b-12d3-a456-426614174000", "application_type": "business", "data": { "account_type": "regular", "currency": "USD", "blockchain_network": "polygon", "wallet_address": "0x123...", "wallet_id": "123e4567-e89b-12d3-a456-426614174000", "label": "ops", "agreement_id": "agr_123", "tos_link": "https://example.com/tos", "tier": "tier_1", "metadata": { "source": "web" }, "business": { "legal_name": "Acme Corp", "trade_name": "Acme", "description": "A very detailed description of Acme Corp here.", "type": "llc", "industry": "software", "website": "https://acme.corp", "registration_number": "12345678", "tax_id_number": "000000000", "date_of_incorporation": "2010-01-01", "country_of_incorporation": "US", "state_of_incorporation": "DE", "business_status": "active", "registered_address": { "street_line_1": "123 Business Rd", "street_line_2": "Suite 100", "city": "New York", "state": "NY", "postal_code": "10001", "country": "US" }, "physical_address": { "street_line_1": "123 Business Rd", "street_line_2": "Suite 100", "city": "New York", "state": "NY", "postal_code": "10001", "country": "US" }, "mailing_address": { "street_line_1": "123 Business Rd", "street_line_2": "Suite 100", "city": "New York", "state": "NY", "postal_code": "10001", "country": "US" }, "primary_contact": { "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+14155552671", "date_of_birth": "1980-01-01", "citizenship": "US", "identification_type": "passport", "identification_number": "P1234567", "identification_country": "US", "address": { "street_line_1": "123 Main St", "city": "San Francisco", "state": "CA", "postal_code": "94105", "country": "US" } }, "associated_persons": [ { "first_name": "Jane", "last_name": "Smith", "middle_name": "Anne", "email": "jane@acme.corp", "phone": "+14155552672", "date_of_birth": "1985-06-15", "citizenship": "US", "ssn": "000000000", "title": "CEO", "role": "director", "has_ownership": true, "has_control": true, "is_signer": true, "is_director": true, "ownership_percentage": 100, "identification_type": "passport", "identification_number": "P7654321", "identification_country": "US", "identification_expiry": "2030-01-01", "id_document_front": "data:application/pdf;base64,...", "id_document_back": "data:application/pdf;base64,...", "proof_of_address_document": "data:application/pdf;base64,...", "address": { "street_line_1": "456 Home Ave", "street_line_2": "Apt 1", "city": "Brooklyn", "state": "NY", "postal_code": "11201", "country": "US" } } ], "has_material_intermediary_ownership": false, "formation_document": "data:application/pdf;base64,...", "ownership_document": "data:application/pdf;base64,...", "proof_of_address_document": "data:application/pdf;base64,...", "proof_of_nature_of_business": "data:application/pdf;base64,...", "is_dao": false, "account_purpose": "operations", "source_of_funds": "revenue", "industry_financial_services_subtype": "none", "industry_crypto_subtype": "none", "industry_other_description": "Software dev", "expected_counterparty_countries": [ "US", "GB" ], "source_of_funds_list": [ "REVENUE" ], "source_of_funds_other_description": "Sales revenue", "tin_verification_document": "data:application/pdf;base64,...", "authorization_document": "data:application/pdf;base64,...", "is_msb": false, "account_purposes": [ "BUSINESS_OPERATIONS" ], "account_purposes_other_description": "Operations", "primary_target_market": "US", "primary_target_market_other_description": "US market", "expected_fiat_monthly_volume": "10000_TO_50000", "expected_crypto_monthly_volume": "10000_TO_50000" } } } ``` ## Responses | Status | Description | | --- | --- | | `200` | Application created | | `400` | Request failed. All gateway errors are returned as HTTP 400 with this envelope. | ### 200 response Unique identifier for the application. ID of the tenant that owns this application. UUID of the customer this application belongs to. Type of application. One of individual or business. Current status of the application. `creating_account` is a deprecated transitional value and should not be treated as a required lifecycle step. `manual_review` means a human decision is required. Possible values: `draft`, `submitted`, `processing`, `creating_account`, `manual_review`, `approved`, `rejected`, `expired` First name of the individual. Required. Last name of the individual. Required. Middle name of the individual. Email address of the individual. Required. Role of the individual in the application (for example, owner). Phone number of the individual, in E.164 format. May be required depending on your account configuration. Date of birth of the individual, in YYYY-MM-DD format. Required. Gender of the individual. Nationality of the individual, in ISO 3166-1 alpha-2 format. Social Security Number of the individual. May be required depending on your account configuration. Tax Identification Number of the individual. May be required depending on your account configuration. Primary source of income. May be required. One of employment, self_employment, investments, retirement, or other. Current employment status of the individual (for example, employed or self_employed). Country of citizenship, in ISO 3166-1 alpha-2 format. May be required depending on your account configuration. Type of government-issued ID. May be required. One of drivers_license, passport, or state_id. Document number of the government-issued ID. May be required depending on your account configuration. Country that issued the identification document, in ISO 3166-1 alpha-2 format. Expiry date of the identification document, in YYYY-MM-DD format. Street address, PO box, company name, c/o Apartment, suite, unit, building, floor, etc. City State, province, county ZIP or postal code Country (ISO 3166-1 alpha-2) Front of the government-issued ID, as a Base64 data URI. May be required depending on your account configuration. Back of the government-issued ID, as a Base64 data URI. Proof of address document, as a Base64 data URI. Sources of the individual's wealth. May be required depending on your account configuration. Free-text description of the source of wealth when not covered by the standard options. Purposes for opening the account. May be required depending on your account configuration. Free-text description of account purposes when not covered by the standard options. Sources of funds for the account. May be required depending on your account configuration. Free-text description of the source of funds when not covered by the standard options. Countries where the individual expects to transact, in ISO 3166-1 alpha-2 format. May be required depending on your account configuration. Expected monthly volume of fiat transactions. May be required depending on your account configuration. Expected monthly volume of crypto transactions. Registered legal name of the business. Required. Trading name or DBA (doing business as) name of the business. Description of the business operations. May be required (minimum 100 characters). Legal entity type of the business (for example, llc or corporation). Required. Industry category of the business. May be required depending on your account configuration. Public-facing website URL of the business. Official registration or incorporation number of the business. Tax Identification Number (TIN) of the business. May be required depending on your account configuration. Date the business was incorporated, in YYYY-MM-DD format. Country where the business is incorporated, in ISO 3166-1 alpha-2 format. Some account configurations require this to be US. US state where the business is incorporated. May be required depending on your account configuration. Current operating status of the business (for example, active or inactive). Street address, PO box, company name, c/o Apartment, suite, unit, building, floor, etc. City State, province, county ZIP or postal code Country (ISO 3166-1 alpha-2) Street address, PO box, company name, c/o Apartment, suite, unit, building, floor, etc. City State, province, county ZIP or postal code Country (ISO 3166-1 alpha-2) Street address, PO box, company name, c/o Apartment, suite, unit, building, floor, etc. City State, province, county ZIP or postal code Country (ISO 3166-1 alpha-2) First name of the individual. Required. Last name of the individual. Required. Middle name of the individual. Email address of the individual. Required. Role of the individual in the application (for example, owner). Phone number of the individual, in E.164 format. May be required depending on your account configuration. Date of birth of the individual, in YYYY-MM-DD format. Required. Gender of the individual. Nationality of the individual, in ISO 3166-1 alpha-2 format. Social Security Number of the individual. May be required depending on your account configuration. Tax Identification Number of the individual. May be required depending on your account configuration. Primary source of income. May be required. One of employment, self_employment, investments, retirement, or other. Current employment status of the individual (for example, employed or self_employed). Country of citizenship, in ISO 3166-1 alpha-2 format. May be required depending on your account configuration. Type of government-issued ID. May be required. One of drivers_license, passport, or state_id. Document number of the government-issued ID. May be required depending on your account configuration. Country that issued the identification document, in ISO 3166-1 alpha-2 format. Expiry date of the identification document, in YYYY-MM-DD format. Front of the government-issued ID, as a Base64 data URI. May be required depending on your account configuration. Back of the government-issued ID, as a Base64 data URI. Proof of address document, as a Base64 data URI. Sources of the individual's wealth. May be required depending on your account configuration. Free-text description of the source of wealth when not covered by the standard options. Purposes for opening the account. May be required depending on your account configuration. Free-text description of account purposes when not covered by the standard options. Sources of funds for the account. May be required depending on your account configuration. Free-text description of the source of funds when not covered by the standard options. Countries where the individual expects to transact, in ISO 3166-1 alpha-2 format. May be required depending on your account configuration. Expected monthly volume of fiat transactions. May be required depending on your account configuration. Expected monthly volume of crypto transactions. Provide at least one associated person. First name of the associated person. Last name of the associated person. Middle name of the associated person. Email address of the associated person. Phone number of the associated person, in E.164 format. Date of birth of the associated person, in YYYY-MM-DD format. Country of citizenship, in ISO 3166-1 alpha-2 format. Social Security Number of the associated person. Job title of the associated person (for example, CEO or CFO). Role of the associated person in the business (for example, director or officer). Indicates whether the person holds an ownership stake in the business. Indicates whether the person has control over the business. Indicates whether the person is an authorized signer on the account. Indicates whether the person is a director of the business. Percentage of the business owned by this person. Type of government-issued ID (for example, passport or drivers_license). Document number of the government-issued ID. Country that issued the identification document, in ISO 3166-1 alpha-2 format. Expiry date of the identification document, in YYYY-MM-DD format. Front of the government-issued ID, as a Base64 data URI. Back of the government-issued ID, as a Base64 data URI. Proof of address document, as a Base64 data URI. Indicates whether the business has ownership held through a material intermediary. Business formation document, as a Base64 data URI. Document showing the ownership structure of the business, as a Base64 data URI. Proof of business address, as a Base64 data URI. Document that verifies the nature of the business, as a Base64 data URI. Indicates whether the business is a decentralized autonomous organization (DAO). Primary purpose for opening the account (for example, operations or payroll). Primary source of business funds (for example, revenue or investment). Subtype of financial services industry, if applicable. Subtype of crypto industry, if applicable. Description of the industry when it does not fit a standard category. Countries where the business expects to transact, in ISO 3166-1 alpha-2 format. Sources of funds for the account. May be required depending on your account configuration. Free-text description of the source of funds when not covered by the standard options. Document verifying the business TIN, as a Base64 data URI. May be required depending on your account configuration. Authorization document for the account, as a Base64 data URI. May be used depending on your account configuration. Indicates whether the business is a money services business (MSB). Purposes for opening the account. May be required depending on your account configuration. Free-text description of account purposes when not covered by the standard options. Primary geographic market the business targets. Free-text description of the primary target market when not covered by the standard options. Expected monthly volume of fiat transactions. Expected monthly volume of crypto transactions. Kind of account to open (for example, regular or savings). This is the account type, not the customer type. Use the top-level application_type field for individual vs business. Possible values: `regular`, `savings` Currency for the account, in ISO 4217 format. Blockchain network to back the account (for example, polygon or stellar). Blockchain wallet address to associate with the account. UUID of an existing Gravv wallet to link to the account. Human-readable label for the account. ID of the provider agreement associated with this application. URL to the terms of service the applicant must accept. Arbitrary key-value pairs for storing additional information about the application. Arbitrary key-value pairs attached to the application. List of validation errors returned when the application data does not meet provider requirements. The field that failed validation. Human-readable explanation of the validation error. Machine-readable error code for the validation failure. Suggested fix for the validation error. Timestamp when the application was submitted, in ISO 8601 format. Timestamp when the application was processed by the provider, in ISO 8601 format. Timestamp when the application was created, in ISO 8601 format. Timestamp when the application was last updated, in ISO 8601 format. Timestamp when the application was soft-deleted, if applicable. ### 400 response Human-readable error message. ## Authorization - **ApiKeyAuth**