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

# Create a customer

> Create a new customer within Layer.

This endpoint is idempotent using the `external_id` field.
If a customer with the same `external_id` already exists, the existing customer will be updated and returned.

### Path Parameters

<ParamField path="business_id" required="true" type="string">
  ID of the [Business](/api-reference/business/business) the customer is associated with.
</ParamField>

### Body

<ParamField body="external_id" type="string">
  External ID for the customer within your platform. **Idempotency key.**
</ParamField>

<ParamField body="individual_name" type="string">
  Name of the individual customer.
</ParamField>

<ParamField body="company_name" type="string">
  Name of the company customer.
</ParamField>

<ParamField body="email" type="string">
  Email address of the customer.
</ParamField>

<ParamField body="mobile_phone" type="string">
  Mobile phone number of the customer.
</ParamField>

<ParamField body="office_phone" type="string">
  Office phone number of the customer.
</ParamField>

<ParamField body="address_string" type="string">
  Full address of the customer.
</ParamField>

<ParamField body="notes" type="string">
  Notes about the customer.
</ParamField>

<ResponseField name="tags" type="Array of Tags">
  <Expandable title="New tag properties">
    <ResponseField name="key" required="true" type="string">
      The new tag's key
    </ResponseField>

    <ResponseField name="value" required="true" type="string">
      The new tag's value
    </ResponseField>
  </Expandable>
</ResponseField>

### Response

Returns the created [Customer object](/api-reference/invoice/customer)

<RequestExample>
  ```bash Request theme={null}
  curl -X POST https://sandbox.layerfi.com/v1/businesses/${business_id}/customers \
    -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
      -d '{
            "external_id": "customer-1",
            "individual_name": "John Doe",
            "company_name": "Acme, Inc.",
            "email": "john@hotmail.com",
            "mobile_phone": "555-555-5555",
            "office_phone": "555-555-5555",
            "address_string": "123 Main St, Phoenix, AZ 85001",
            "notes": "This is a note"
          }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 (Updated) theme={null}
  {
   "data": {
     "type": "CustomerData",
     "id": "4f7c1b16-e057-4ec0-8b20-50308ba5b9ea",
     "external_id": "customer-1",
     "individual_name": "John Doe",
     "company_name": "Acme, Inc.",
     "email": "john@hotmail.com",
     "mobile_phone": "555-555-5555",
     "office_phone": "555-555-5555",
     "address_string": "123 Main St, Phoenix, AZ 85001",
     "notes": "This is a note",
     "status": "ACTIVE",
     "transaction_tags": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "key": "department",
        "value": "sales",
        "dimension_display_name": "Department",
        "value_display_name": "Sales Team",
        "dimension_id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
        "definition_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
        "created_at": "2024-02-27T02:16:40.389772Z",
        "updated_at": "2024-02-27T02:16:40.389772Z",
        "deleted_at": null,
        "archived_at": null
      }
    ]
   }
  }
  ```

  ```json 201 (Created) theme={null}
  {
   "data": {
     "type": "CustomerData",
     "id": "4f7c1b16-e057-4ec0-8b20-50308ba5b9ea",
     "external_id": "customer-1",
     "individual_name": "John Doe",
     "company_name": "Acme, Inc.",
     "email": "john@hotmail.com",
     "mobile_phone": "555-555-5555",
     "office_phone": "555-555-5555",
     "address_string": "123 Main St, Phoenix, AZ 85001",
     "notes": "This is a note",
     "status": "ACTIVE",
     "transaction_tags": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "key": "department",
        "value": "sales",
        "dimension_display_name": "Department",
        "value_display_name": "Sales Team",
        "dimension_id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
        "definition_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
        "created_at": "2024-02-27T02:16:40.389772Z",
        "updated_at": "2024-02-27T02:16:40.389772Z",
        "deleted_at": null,
        "archived_at": null
      }
    ]
   }
  }
  ```
</ResponseExample>