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. The body must include all required fields (isCompany, address, postcode, city, extras); optional fields you omit are preserved.
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": "003" }.
POST /customers/import/upload	POST	Upload a CSV file for bulk import (multipart/form-data). Returns { "id": "<uuid>" }. Pass this id as fileId to /customers/import.
POST /customers/import	POST	Bulk-import customers from a previously uploaded CSV file. Returns an array of created customer objects.
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. Default 25, max 1000 (clamped silently).
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: Bulk import customers from CSV

Importing customers is a two-step process: first upload the CSV file to get a fileId, then pass it to the import endpoint.

Step 1 — Upload the CSV file

curl -X POST \
  -H "X-API-KEY: your-api-token" \
  -F "file=@customers.csv;type=text/csv" \
  https://api.faktoora.com/api/v1/customers/import/upload

Response (200 OK)

{ "id": "550e8400-e29b-41d4-a716-446655440000" }

Accepted MIME types: text/csv, application/vnd.ms-excel, application/csv, text/x-csv, application/x-csv, text/comma-separated-values, text/x-comma-separated-values. Both , and ; delimiters are supported. Supported export formats: Google Contacts, Outlook, Lexware, sevDesk.

If the CSV rows omit a customerId column, customer numbers are auto-assigned based on your tenant's existing sequence.

Step 2 — Import the customers

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: 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: 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 }