Skip to content

Get started

This guide shows you how to get started with our API.

By the end of this guide, you will know how to:

Register on Gravv

You need to register a Gravv to use the API. If you don't have an account, follow these steps:

  1. Visit the registration page.
  2. Enter your First name, Last name, Email address, and Business name in the appropriate fields.
  3. Check the box to agree to the Terms of use and Privacy policy.
  4. Click Sign up.
  5. Check your email for a verification message and visit the link to complete your registration.

Note

You can only create an account with a business email address.

Select an environment

Once you've registered on Gravv, the next step is to select an environment. For more information, see Environments.

Obtain your Api Key

Every request to the Gravv API requires an Api-Key. After creating a Gravv account, we generate two pairs of API keys for you: a publishable Public Key and a server-side Secret Key, for both Sandbox and Live modes.

To obtain your Api-Key, follow these steps:

  1. Sign in to your Gravv Dashboard with your registered business email address.
  2. Click Manage in the side navigation.
  3. Click Configure under the Manage section.
  4. Click API keys, then click the copy button under Secret Key to copy your Secret Key.

Now that you have obtained your Secret key, you can make your first request.

For more information, see Authentication

Whitelist your IP address

Follow these steps to whitelist your IP address before sending API requests:

  1. Follow steps 1 through 3 in Obtain Your API Key.
  2. Click IP Access List.
  3. Click Add IP Address.
  4. Enter your IP address in the IP Address field.

Add a customer

Now that you have obtained your Secret key, you can add a customer and obtain a customer ID.

You can add either an individual customer or a business customer.

Add an individual customer

Individual customers are persons who will use your platform for personal transactions.

To add an individual customer, make a POST request to the Gravv API. Replace the values in angle brackets <...> with your actual details before running the request:

curl -X POST https://api.gravv.xyz/v1/customers \
  -H "Api-Key: <Api Key>" \
  -H 'Idempotency-Key: 979879887678789_attempt_1' \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "<your first name>",
    "last_name": "<your last name>",
    "middle_name": "<your middle name>",
    "email": "<your email>",
    "phone": "<your phone number>",
    "type": "individual",
    "gender": "<your gender>",
    "date_of_birth": "<your date of birth in yyyy-mm-dd format>",
    "address": {
      "address_line1": "<your address line1>",
      "city": "<your city>",
      "country": "<your country code>",
      "postal_code": "<your postal code>",
      "state": "<your state code>"
    }
  }'

Note

first_name and last_name are required fields. middle_name is optional and should only be provided if it appears on the customer's ID.

A successful response will return the details from your request body, similar to this:

{
  "data": {
    "address": {
      "address_line1": "Same Global Housing Estate",
      "city": "Lokogoma",
      "country": "NG",
      "postal_code": "900107",
      "state": "NG-FC"
    },
    "date_of_birth": "2024-04-16",
    "email": "dunibioye@gmail.com",
    "first_name": "Oladuni",
    "gender": "female",
    "id": "0d3c3c62-95ca-4ca9-a8ac-a262e597ba99",
    "last_name": "Abioye",
    "middle_name": "Abidemi",
    "phone": "+2348069867745",
    "status": "active",
    "type": "individual"
  },
  "error": null
}

Add a business customer

Business customers are companies or organizations that will use your platform for business transactions. Business customers must include at least one associated person, such as a director or beneficial owner.

Supported business industries

When creating a business customer, the business_industry field must be one of the following:

  • Retail & E-commerce
  • Information, Software & Technology
  • Corporate & Legal Services
  • Foundations & Nonprofit Organizations
  • Marketing & Advertising
  • Financial Services (Fintech and related)
  • Investment Services
  • Insurance Services
  • Entertainment & Media
  • Hiring & HR Platforms
  • Crypto & Blockchains
  • Supply Chain & Logistics
  • Health & Medical Services
  • Regulated Financial Institutions (Banks, Security Brokers)
  • Gaming & Betting Platforms (Licensed).

Add and send a request

To add a business customer, make a POST request to the Gravv API. Replace the values in angle brackets <...> with your actual details before running the request:

curl -X POST https://api.gravv.xyz/v1/customers \
  -H "Api-Key: <Api Key>" \
  -H 'Idempotency-Key: 979879887678789_attempt_1' \
  -H "Content-Type: application/json" \
  -d '{
    "type": "business",
    "email": "<business email>",
    "phone": "<business phone number>",
    "business_name": "<registered business name>",
    "business_description": "<business description>",
    "business_type": "<business type>",
    "business_industry": "<business industry>",
    "registration_number": "<business registration number>",
    "address": {
      "address_line1": "<business address line1>",
      "address_line2": "<business address line2>",
      "city": "<city>",
      "postal_code": "<postal code>",
      "state": "<state code>",
      "country": "<country code>"
    },
    "associated_persons": [
      {
        "first_name": "<person first name>",
        "last_name": "<person last name>",
        "email": "<person email>",
        "phone": "<person phone number>",
        "gender": "<person gender>",
        "date_of_birth": "<date of birth in yyyy-mm-dd format>",
        "address": {
          "address_line1": "<person address line1>",
          "city": "<city>",
          "postal_code": "<postal code>",
          "state": "<state code>",
          "country": "<country code>"
        }
      }
    ]
  }'

Note

All fields shown above are required for business customers. You must include at least one associated person with their complete details.

A successful response will return the details from your request body, similar to this:

{
  "data": {
    "id": "d7052709-dc3f-4fa4-9173-164a4879b71f",
    "type": "business",
    "email": "contact@acmecorp.com",
    "phone": "+12025550173",
    "business_name": "Acme Corporation",
    "business_description": "Technology and software development",
    "business_type": "private_limited",
    "business_industry": "Technology",
    "registration_number": "RC-987654",
    "status": "active",
    "date_added": "2025-11-10T12:34:38.007951727+01:00",
    "address": {
      "address_line1": "1800 N Pole St",
      "address_line2": "Suite 202",
      "city": "Orlando",
      "postal_code": "32801",
      "state": "US-FL",
      "country": "US"
    },
    "associated_persons": [
      {
        "id": "7635ef7a-4b79-4bc5-b120-5ba03c2314a8",
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane.doe@acmecorp.com",
        "phone": "+14123456780",
        "date_of_birth": "1990-06-15",
        "gender": "female",
        "type": "ubo",
        "status": "active",
        "date_added": "2025-11-10T12:34:38.124730478+01:00",
        "address": {
          "address_line1": "1800 N Pole St",
          "address_line2": "Suite 202",
          "city": "Orlando",
          "postal_code": "32801",
          "state": "US-FL",
          "country": "US"
        }
      }
    ]
  },
  "error": null
}

What next?