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

# Create a Customer

> The API to create (or update) a customer

## Request

**Request type**: POST

**URL**: `{{baseUrl}}/api/v1/customers`

**Body**:

```json theme={null}
{
	"name": "Vaibhav Kaushal",
	"external_user_id": "vaibkaus",
	"email": "vaibhav@eazyowl.com",
	"phone": "10987654321"
}
```

### Constraints

| Parameter Name     | Required? | Constraints                                                                                                                                                      | Remarks                                                                                                  |
| ------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| name               | yes       | Minimum 2 characters. Max 120 characters.                                                                                                                        |                                                                                                          |
| external\_user\_id | yes       | It must be a string. If you use numbers in your database, convert them to a string before making the request.                                                    | This value **must uniquely identify a single user in the merchant database**.                            |
| email              | yes       | Must be a unique email address for the merchant.                                                                                                                 | The validity of the email address shall not be performed by the platform. That must be done by merchant. |
| phone              | yes       | Minimum 8 characters. Maximum 13 characters. This field can accept anything for now (including alphabets).<br /><br />*This value is not required to be unique.* | The validity of the phone number shall not be performed by the platform. That must be done by merchant.  |

<Tip>
  If you do not have a *phone* number (since the API mandates its presence), you can send a placeholder value (e.g. `custNoPhone`) and later update it.
</Tip>

## Success Response

**HTTP code**: 201 (Created) OR 200 (OK)

<Card title="Why two response codes?" type="warning">
  This API can also **Update** the customer details.

  * The **201** response code indicates that a **new customer** was created in the database.
  * The **200** response code indicates that a **customer with existing** `external_user_id`\*\* was updated\*\*. 
    * The search for the customer is performed against the `external_user_id`
    * The values for `email` and `phone` are updated if an existing user is found.
</Card>

**Body**:

```json theme={null}
{
	"name": "Vaibhav Kaushal",
	"email": "vaibhav@eazyowl.com",
	"inserted_at": "2026-08-10T13:11:34Z",
	"external_id": "vaibkaus"
}
```

**Meaning of Response field values**:

| Field        | Expected Value                                                                                   | Remarks                                                                                      |
| ------------ | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| name         | The same value that was sent in the request should come back                                     |                                                                                              |
| email        | The same value that was sent in the request should come back                                     |                                                                                              |
| inserted\_at | The timestamp of when the data was inserted in the database                                      | **This is the UTC timestamp**. Hence it might differ from local time on the calling machine. |
| external\_id | The same value that was sent in the request under the `external_user_id` field should come back. |                                                                                              |

The phone number is not returned back in the response.

## Error Responses

Error shall be returned when the data is faulty. Typical HTTP response code shall be `422 (Unprocessable Content)`. Some examples include (this is not an exhaustive list):

### Email Already exists

You cannot create a customer account with same email as that of an existing customer. A response body like below can be expected:

```text theme={null}
{
	"errors": {
		"email": [
			"Email is already taken in this organization"
		]
	}
}
```

## Phone number is not of the right length

Phone number length must be 8-13 characters long. If the input exceeds the range on either side, an error is shown, for example:

```text theme={null}
{
	"errors": {
		"phone": [
			"should be at most 13 character(s)"
		]
	}
}
```