Customers

This section covers the Customers API for managing your customer (buyer) database. Customers can be companies or individuals and are referenced when creating invoices.

---

Customer Endpoints

All customer endpoints require apiKeyAuth.

Endpoint	Method	Description
GET /customers	GET	Paginated list of all customers. Supports filtering, sorting, and relation loading.
GET /customer/{id}	GET	Get a single customer by its ID.
POST /customer	POST	Create a new customer.
PATCH /customer/{id}	PATCH	Update an existing customer (partial update).
DELETE /customer/{id}	DELETE	Delete a customer. Returns { "succeed": true }.
GET /customers/generate-number	GET	Generate the next customer number based on the current sequence. Returns { "value": "CUST-0042" }.
POST /customers/import	POST	Bulk-import customers from a CSV file previously uploaded to faktoora. Returns an array of created customers.
GET /customer/verify-customer-number	GET	Check whether a customer number is unique. Returns { "succeed": true/false }.

---

Query Parameters for GET /customers

Parameter	Type	Description
page	number	Page number (1-based).
perPage	number	Results per page.
sort	string	Field to sort by: customerId, name, nameAuthorisedSignatory, address, phoneNo, category, isCompany, email, faktooraId, vatId, taxId, invoiceProfile, supplierNumber, routeId, peppolId, createdAt, updatedAt.
order	string	Sort direction: asc or desc.
category	string	Filter by customer category.
keywords	string[]	Array of search terms matched across customer fields.
relationFields	string[]	Eager-load related data. Options: user, legalform, importedFile, customerContacts, invoiceTemplate, customerDeliveryAddresses.

---

Customer Fields

Field	Type	Required	Description
isCompany	boolean	✓	true for a company, false for an individual.
address	string	✓	Street address.
postcode	string	✓	Postal code. Validated per country (DE: 5 digits, AT/CH: 4 digits).
city	string	✓	City name.
extras	object	✓	Additional metadata object (can be {}).
name	string		Company name (for companies).
firstName	string		First name (for individuals).
lastName	string		Last name (for individuals).
email	string		Contact email address.
customerId	string		Your internal customer number/ID.
country	string		ISO 3166-1 alpha-2 country code (e.g., DE, AT, CH).
phoneNo	string		Phone number.
vatId	string		VAT registration number (e.g., DE123456789).
taxId	string		Tax ID (Steuernummer).
peppolId	string		PEPPOL participant ID for e-invoicing network delivery.
glnId	string		Global Location Number (GLN).
dunsId	string		D-U-N-S number.
invoiceProfile	string		Default invoice format profile for this customer.
deliveryAddresses	array		Array of delivery address objects.
customerContacts	array		Array of contact person objects.

Example: Create a company customer

curl -X POST \
  -H "X-API-KEY: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "isCompany": true,
    "name": "Acme GmbH",
    "address": "Musterstraße 1",
    "postcode": "10115",
    "city": "Berlin",
    "country": "DE",
    "email": "billing@acme.example.com",
    "vatId": "DE123456789",
    "extras": {}
  }' \
  https://api.faktoora.com/api/v1/customer

Response (200 OK) — the created customer object including its id.

Example: List customers with filtering

curl -G -H "X-API-KEY: your-api-token" \
     --data-urlencode "keywords[]=Acme" \
     --data-urlencode "page=1" \
     --data-urlencode "perPage=20" \
     --data-urlencode "sort=name" \
     --data-urlencode "order=asc" \
     https://api.faktoora.com/api/v1/customers

Example: Generate next customer number

curl -H "X-API-KEY: your-api-token" \
     https://api.faktoora.com/api/v1/customers/generate-number

Response (200 OK)

{ "value": "003" }

The returned value is the next free number in your tenant's existing sequence — typically a zero-padded integer (the default pad length is 3). If your tenant uses a custom format (e.g. CUST-001), the response follows that format instead. Use this value as the customerId when creating the next customer to maintain a consistent numbering sequence.

Example: Verify a customer number

curl -G -H "X-API-KEY: your-api-token" \
     --data-urlencode "value=CUST-0042" \
     https://api.faktoora.com/api/v1/customer/verify-customer-number

Response (200 OK)

{ "succeed": true }

succeed: true means the number is available (not yet in use).

Example: Bulk import customers from CSV

Upload a CSV file first to get a fileId, then pass it to the import endpoint:

curl -X POST \
  -H "X-API-KEY: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": "550e8400-e29b-41d4-a716-446655440000"
  }' \
  https://api.faktoora.com/api/v1/customers/import

Response (200 OK) — array of created customer objects.

Example: Delete a customer

curl -X DELETE \
  -H "X-API-KEY: your-api-token" \
  https://api.faktoora.com/api/v1/customer/cust_abc123

Response (200 OK)

{ "succeed": true }