Onboard your first customer

In this guide, you will learn how to onboard your first customer with our API. A customer can be either a business or an individual.

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

Create an account on Gravv

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

Visit the registration page.
Enter your First name, Last name, Email address, and Business name in the appropriate fields.

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

Check the box to agree to the Terms of use and Privacy policy.
Click Sign up.

Check your email for a verification message and visit the link to complete your registration.

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:

Sign in to your Gravv Dashboard with your registered business email address.
Click Manage in the side navigation.

Click Configure under the Manage section.

Now click API keys, then click the copy button under Secret Key to copy your Secret Key.

Make your first request

Now that you have obtained your Secret key, you can make your first request. In the following example, you will learn how to call the Gravv API to Add a customer and confirm a successful response.

Before you begin

To complete this tutorial, you will need the following:

Your Secret Key before making requests. If you haven't obtained it yet, follow the steps in the Obtain your API key section.
Basic understanding of REST APIs and cURL

Create an individual customer

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

Create and send a request

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>"
    }
  }'

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.

Confirm response

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": "[email protected]",
    "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
}

Create 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).

Create and send a request

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>"
        }
      }
    ]
  }'

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

Confirm response

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

{
  "data": {
    "id": "d7052709-dc3f-4fa4-9173-164a4879b71f",
    "type": "business",
    "email": "[email protected]",
    "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": "[email protected]",
        "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?

Now that you’ve onboarded your first customer, you’re ready to build a full integration. Continue with Your first Gravv integration to learn how to:

Onboard multiple customers
Verify customers with KYC
Fund accounts
Transfer funds between accounts