> ## Documentation Index
> Fetch the complete documentation index at: https://docs.juicyway.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Customer

> Create and manage customers within your integration.

## Overview

The Customers API enables you to create and manage customer profiles for your integration. Each customer object includes personal information, contact details, and billing information that can be referenced in future transactions.

## Create a Customer

```json theme={null}
POST /customers
```

Create a new customer profile with the specified information. Each customer must have a unique email address within your integration.

<Note>
  Ensure phone numbers match the billing address country format. For example, Nigerian phone numbers (+234) should have a Nigerian billing address.
</Note>

### Request Parameters

<ParamField body="first_name" type="string" required>
  Customer's first name.

  * Maximum length: 100 characters
  * Must contain only letters, spaces, hyphens, and apostrophes
</ParamField>

<ParamField body="last_name" type="string" required>
  Customer's last name.

  * Maximum length: 100 characters
  * Must contain only letters, spaces, hyphens, and apostrophes
</ParamField>

<ParamField body="email" type="string" required>
  Customer's email address.

  * Must be a valid email format
  * Must be unique within your integration
</ParamField>

<ParamField body="phone_number" type="string" required>
  Customer's phone number in E.164 format.

  * Must include country code
  * Must be a valid number for the billing address country
  * Example: +2348012345678
</ParamField>

<ParamField body="billing_address" type="object" required>
  Customer's billing address information.

  <Expandable title="Address Fields">
    <ResponseField name="line1" type="string" required>
      Street address (first line)

      * Maximum length: 100 characters
    </ResponseField>

    <ResponseField name="line2" type="string">
      Street address (second line)

      * Maximum length: 100 characters
    </ResponseField>

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

      * Maximum length: 50 characters
    </ResponseField>

    <ResponseField name="state" type="string" required>
      State or province

      * Maximum length: 50 characters
    </ResponseField>

    <ResponseField name="zip_code" type="string" required>
      Postal or ZIP code

      * Format varies by country
    </ResponseField>

    <ResponseField name="country" type="string" required>
      Two-letter country code (ISO 3166-1 alpha-2)

      * Example: "US", "NG", "GB"
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField body="type" type="string" required>
  Must be of `business` or `individual`
</ParamField>

### Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.spendjuice.com/customers" \
  -H "Authorization:  YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone_number": "+2348012345678",
    "type": "business|individual",
    "billing_address": {
      "line1": "123 Test Lane",
      "line2": "Suite 456",
      "city": "Lagos",
      "state": "Lagos",
      "zip_code": "100001",
      "country": "NG"
    }
  }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.spendjuice.com/customers', {
    method: 'POST',
    headers: {
      'Authorization': ' YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      first_name: 'John',
      last_name: 'Doe',
      email: 'john.doe@example.com',
      phone_number: '+2348012345678',
      type: "business|individual",
      billing_address: {
        line1: '123 Test Lane',
        line2: 'Suite 456',
        city: 'Lagos',
        state: 'Lagos',
        zip_code: '100001',
        country: 'NG'
      }
    })
  });

  const customer = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.spendjuice.com/customers',
      headers={
          'Authorization': ' YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'first_name': 'John',
          'last_name': 'Doe',
          'email': 'john.doe@example.com',
          'phone_number': '+2348012345678',
          'type': 'business|individual',
          'billing_address': {
              'line1': '123 Test Lane',
              'line2': 'Suite 456',
              'city': 'Lagos',
              'state': 'Lagos',
              'zip_code': '100001',
              'country': 'NG'
          }
      }
  )

  customer = response.json()
  ```
</CodeGroup>

### Response

<CodeGroup>
  ```json 201 Success theme={null}
  {
    "data": {
      "id": "6f7e1e7f-93d1-4fcc-b7a4-738f869615c8",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone_number": "+2348012345678",
      "type": "business|individual",
      "billing_address": {
        "line1": "123 Test Lane",
        "line2": "Suite 456",
        "city": "Lagos",
        "state": "Lagos",
        "zip_code": "100001",
        "country": "NG"
      }
    }
  }
  ```

  ```json 400 Validation Error theme={null}
  {
    "error": {
      "code": "validation_error",
      "message": "Invalid input parameters",
      "details": {
        "email": ["Invalid email format"],
        "phone_number": ["Phone number does not match country format"]
      }
    }
  }
  ```

  ```json 409 Duplicate Customer theme={null}
  {
    "error": {
      "code": "duplicate_customer",
      "message": "A customer with this email already exists",
      "details": {
        "email": ["must be unique"]
      }
    }
  }
  ```
</CodeGroup>

## Rate Limits

| Environment | Requests per minute |
| ----------- | ------------------- |
| Test        | 100                 |
| Production  | 1000                |

Exceeding these limits will return a `429 Too Many Requests` response.

## Idempotency

All POST requests support idempotency to prevent duplicate customer creation. Include an `Idempotency-Key` header with a unique value for each request:

```bash theme={null}
Idempotency-Key: a123b456-c789-d012-e345-f67890123456
```

The same key will return the original response for duplicate requests within 24 hours.

## Best Practices

1. **Validation**
   * Validate email formats before sending
   * Ensure phone numbers match country codes
   * Use proper character encoding for names
2. **Error Handling**
   * Implement retry logic with exponential backoff
   * Handle validation errors gracefully
   * Check for duplicate customers before creation
3. **Security**
   * Use HTTPS for all API calls
   * Keep API keys secure
   * Implement proper access controls

<Card title="Need help?" icon="question-circle">
  For support with customer creation:

  * Check our [Error Handling Guide](/errors)
  * Contact [support@juicyway.com](mailto:support@juicyway.com)
</Card>