---
title: "Create a customer"
method: POST
path: "/customers"
tags: ["Customers"]
---

# Create a customer

`POST /customers`

## Request

- Base URL: `https://www.billingengine.com/api/v1`
- URL: `https://www.billingengine.com/api/v1/customers`
- Auth: HTTP bearer

A new customer needs a company or a last name and an address with line 1, postal code, city and country. The number is assigned automatically.

## Request body

- CustomerInput
  - `company` string
  - `first_name` string
  - `last_name` string
  - `email` string, email
  - `phone` string
  - `vat_number` string
  - `buyer_reference` string
  - `address_attributes` Address
    - `line_1` string
    - `line_2` string, nullable
    - `postal_code` string
    - `city` string
    - `region` string, nullable
    - `country` string: ISO country code such as DE.

## Response `201`

The created customer.

- Customer
  - `id` integer
  - `number` union
    - string
    - integer
  - `name` string: Company, or first and last name.
  - `company` string, nullable
  - `first_name` string, nullable
  - `last_name` string, nullable
  - `email` string, nullable
  - `phone` string, nullable
  - `vat_number` string, nullable
  - `buyer_reference` string, nullable: Buyer reference (BT-10), for example a Leitweg-ID.
  - `address` Address
    - `line_1` string
    - `line_2` string, nullable
    - `postal_code` string
    - `city` string
    - `region` string, nullable
    - `country` string: ISO country code such as DE.

## Other responses

- `400`: Malformed request: missing parameter, invalid JSON, invalid date or invalid filter.
- `401`: Missing or invalid API key.
- `403`: The API is not available in the Free plan, or the monthly invoice maximum of the plan has been reached.
- `422`: The record is invalid. The messages explain why.

---

[API](https://skmtc.dev/billingengine/apis/billingengine-api.md) · [All operations](https://skmtc.dev/billingengine/apis/billingengine-api/llms.txt) · [OpenAPI document](https://skmtc.dev/billingengine/apis/billingengine-api/revisions/71d8ea5fb554?raw)