---
title: "Add a customer"
description: "Create a new customer record."
protocol: rest
method: POST
endpoint: "/v1/customers"
baseUrl: "https://api.gravv.xyz"
group: "Customers"
auth:
  label: "Api-Key"
  name: "Api-Key"
  in: header
---

# Add a customer

<Endpoint method="POST" path="/v1/customers" />

Create a new customer record.

## Headers

<ParamField name="Idempotency-Key" header="Idempotency-Key" type="string" required>
  Required for POST requests. Reuse only for an identical retry.
</ParamField>

## Request Body

### Request Examples

<RequestExample>

```json title="IndividualCustomer"
{
  "first_name": "john",
  "middle_name": "william",
  "last_name": "doe",
  "email": "john.doe@example.com",
  "phone": "+15555550101",
  "type": "individual",
  "gender": "male",
  "date_of_birth": "1990-04-16",
  "external_id": "individual_12345",
  "address": {
    "address_line1": "1800 N Pole St",
    "address_line2": "Suite 202",
    "city": "Orlando",
    "postal_code": "32801",
    "state": "US-FL",
    "country": "US"
  }
}
```

```json title="BusinessCustomer"
{
  "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",
  "external_id": "BUS-67890",
  "address": {
    "address_line1": "1800 N Pole St",
    "address_line2": "Suite 202",
    "city": "Orlando",
    "postal_code": "32801",
    "state": "US-FL",
    "country": "US"
  },
  "associated_persons": [
    {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane.doe@acmecorp.com",
      "date_of_birth": "1990-06-15",
      "gender": "female",
      "phone": "+15555550102",
      "address": {
        "address_line1": "1800 N Pole St",
        "address_line2": "Suite 202",
        "city": "Orlando",
        "postal_code": "32801",
        "state": "US-FL",
        "country": "US"
      }
    }
  ]
}
```

</RequestExample>

## Responses

| Status | Description |
| --- | --- |
| `200` | Customer created successfully |
| `400` | Bad request — invalid or missing parameters |

### 200 response

<ResponseField name="data" type="object">
  Full customer object returned by create and get endpoints.

  <Expandable title="properties">
    <ResponseField name="id" type="string">
    </ResponseField>

    <ResponseField name="first_name" type="string">
    </ResponseField>

    <ResponseField name="last_name" type="string">
    </ResponseField>

    <ResponseField name="middle_name" type="string">
    </ResponseField>

    <ResponseField name="type" type="string">

      Possible values: `individual`, `business`
    </ResponseField>

    <ResponseField name="email" type="string">
    </ResponseField>

    <ResponseField name="phone" type="string">
    </ResponseField>

    <ResponseField name="address" type="object">

      <Expandable title="properties">
        <ResponseField name="address_line1" type="string" required>
        </ResponseField>

        <ResponseField name="address_line2" type="string">
        </ResponseField>

        <ResponseField name="city" type="string" required>
        </ResponseField>

        <ResponseField name="postal_code" type="string" required>
        </ResponseField>

        <ResponseField name="state" type="string" required>
        </ResponseField>

        <ResponseField name="country" type="string" required>
        </ResponseField>

      </Expandable>
    </ResponseField>

    <ResponseField name="status" type="string">
    </ResponseField>

    <ResponseField name="kyc" type="object[]">

      <Expandable title="properties">
        <ResponseField name="id" type="string">
        </ResponseField>

        <ResponseField name="type" type="string">
        </ResponseField>

        <ResponseField name="status" type="string">
        </ResponseField>

        <ResponseField name="kyc_url" type="string">
        </ResponseField>

        <ResponseField name="remark" type="string">
        </ResponseField>

        <ResponseField name="verified_at" type="string,null">
        </ResponseField>

      </Expandable>
    </ResponseField>

    <ResponseField name="associated_persons" type="object[]">

      <Expandable title="properties">
        <ResponseField name="id" type="string">
        </ResponseField>

        <ResponseField name="first_name" type="string">
        </ResponseField>

        <ResponseField name="middle_name" type="string">
        </ResponseField>

        <ResponseField name="last_name" type="string">
        </ResponseField>

        <ResponseField name="email" type="string">
        </ResponseField>

        <ResponseField name="date_of_birth" type="string">
        </ResponseField>

        <ResponseField name="gender" type="string">

          Possible values: `male`, `female`, `other`
        </ResponseField>

        <ResponseField name="phone" type="string">
        </ResponseField>

        <ResponseField name="status" type="string">
        </ResponseField>

        <ResponseField name="type" type="string">
        </ResponseField>

        <ResponseField name="address" type="object">

          <Expandable title="properties">
            <ResponseField name="address_line1" type="string" required>
            </ResponseField>

            <ResponseField name="address_line2" type="string">
            </ResponseField>

            <ResponseField name="city" type="string" required>
            </ResponseField>

            <ResponseField name="postal_code" type="string" required>
            </ResponseField>

            <ResponseField name="state" type="string" required>
            </ResponseField>

            <ResponseField name="country" type="string" required>
            </ResponseField>

          </Expandable>
        </ResponseField>

        <ResponseField name="date_added" type="string">
        </ResponseField>

        <ResponseField name="kyc" type="object[]">

          <Expandable title="properties">
            <ResponseField name="id" type="string">
            </ResponseField>

            <ResponseField name="type" type="string">
            </ResponseField>

            <ResponseField name="status" type="string">
            </ResponseField>

            <ResponseField name="kyc_url" type="string">
            </ResponseField>

            <ResponseField name="remark" type="string">
            </ResponseField>

            <ResponseField name="verified_at" type="string,null">
            </ResponseField>

          </Expandable>
        </ResponseField>

      </Expandable>
    </ResponseField>

    <ResponseField name="business_name" type="string">
    </ResponseField>

    <ResponseField name="business_description" type="string">
    </ResponseField>

    <ResponseField name="business_type" type="string">
    </ResponseField>

    <ResponseField name="business_industry" type="string">
    </ResponseField>

    <ResponseField name="registration_number" type="string">
    </ResponseField>

    <ResponseField name="date_added" type="string">
    </ResponseField>

    <ResponseField name="external_id" type="string">
    </ResponseField>

    <ResponseField name="industry_code" type="string">
    </ResponseField>

  </Expandable>
</ResponseField>

<ResponseField name="error" type="null">
</ResponseField>

<ResponseExample>

```json title="Response"
{
  "data": {
    "id": "e59daa17-20ed-4727-833c-e1c633782cc8",
    "first_name": "Jane",
    "last_name": "Doe",
    "middle_name": "A.",
    "type": "individual",
    "email": "jane@example.com",
    "phone": "+15555550101",
    "address": {
      "address_line1": "1800 N Pole St",
      "address_line2": "Suite 202",
      "city": "Orlando",
      "postal_code": "32801",
      "state": "US-FL",
      "country": "US"
    },
    "status": "active",
    "kyc": [],
    "associated_persons": [],
    "date_added": "2024-01-15T10:30:00Z",
    "external_id": "individual_12345",
    "industry_code": ""
  },
  "error": null
}
```

</ResponseExample>

### 400 response

<ResponseField name="data" type="null">
</ResponseField>

<ResponseField name="error" type="string">
</ResponseField>

<ResponseExample>

```json title="Response"
{
  "data": null,
  "error": "invalid request body"
}
```

</ResponseExample>

## Authorization

- **ApiKeyAuth**