List customers

Returns a paginated list of customers. Use inactive to restrict the result to active or inactive customers — note that an unsupported filter is ignored rather than rejected, so a misspelled parameter silently returns everything.

Availability: Full version only — a Clock instance answers 404 for this endpoint.

Request

GET /api/v1/customers

curl --request GET \
     --url 'https://www.zep-online.de/zepinstanz/next/api/v1/customers' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer {token}'

Query parameters

Name
perPage
Type
integer, nullable
Description
Ignored on this endpoint — send limit instead. Any value given here is replaced by limit, or by the default when limit is absent.
Name
page
Type
integer, nullable
Description
The page of results to return, counting from 1.
Name
orderBy
Type
string, nullable
Description
Name of the field to sort by.
Name
order
Type
string, nullable
Description
Sort direction, ascending or descending.
One of: "asc", "desc"
Name
limit
Type
integer, nullable
Description
The number of records per page, 1 to 200. Defaults to 15.
Name
modified_after
Type
string (date-time)
Description
Only return records modified after this timestamp (ISO 8601, or “Y-m-d H:i:s”).
Name
modified_before
Type
string (date-time)
Description
Only return records modified before or at this timestamp (ISO 8601, or “Y-m-d H:i:s”).
Name
start_date
Type
string (date)
Description
Name
end_date
Type
string (date)
Description
Name
customer_number[]
Type
array of string, nullable
Description
Name
inactive
Type
boolean, nullable
Description
Restrict the result by active state: true returns only inactive customers, false only active ones. Supersedes the status filter as of 7.12.49, which stays available as a deprecated alias with the opposite polarity.
Name
status
Type
integer, nullable
Description
Deprecated alias for the inverse of inactive: 1 means active, 0 inactive. An explicit inactive wins, and an unparseable value is ignored rather than guessed.

Response

{
  "data": [
    {
      "customer_number": "K-12345",
      "name": "EU",
      "additional_name": "ACME Corp",
      "website": "www.acme-corp.com",
      "email": "erika.mustermann@acme-corp.de",
      "phone": "+49 30 12345678",
      "fax": "+1-555-0124",
      "currency": "EUR",
      "comments": "Wichtiger Kunde - mit Sorgfalt behandeln",
      "industry": "Technologie",
      "vat": "string",
      "tax_number": "DE123456789",
      "iban": "DE89370400440532013000",
      "bic": "COBADEFFXXX",
      "payment_target": "string",
      "payment_target_discount": 2,
      "inactive": false,
      "status": {
        "value": 0,
        "label": "Inactive"
      },
      "created": "2024-07-20T11:30:00.000000Z",
      "modified": "2024-07-20T12:30:00.000000Z",
      "billing_procedure": true,
      "automated_invoicing": true,
      "debit_payment": false,
      "department_id": 1,
      "addresses": [
        {
          "id": 1,
          "name": "EU",
          "address": "Musterstraße 123",
          "address_line_2": "string",
          "address_line_3": "string",
          "zip_code": "10115",
          "city": "Berlin",
          "country": "Deutschland",
          "is_default": true,
          "is_billing_address": true,
          "is_shipping_address": true,
          "email": "erika.mustermann@acme-corp.de",
          "email_cc": "string",
          "email_bcc": "string",
          "country_code": "string",
          "inactive": false,
          "machine_readable_invoice_version": {
            "id": 1,
            "name": "ZUGFeRD1"
          }
        }
      ],
      "managers": [
        {
          "username": "max.mustermann",
          "has_edit_customer_data_permission": true,
          "has_budget_responsibility_permission": true,
          "is_primary_employee": true
        }
      ],
      "categories": [
        {
          "name": "EU",
          "description": {
            "de": "string",
            "en": "string",
            "fr": "string",
            "es": "string",
            "pl": "string"
          },
          "type": {
            "id": "string",
            "name": "Mitarbeiter/in"
          }
        }
      ],
      "dynamicAttributes": [
        {
          "name": "EU",
          "value": "Max Mustermann (Bruder)",
          "type": "Text",
          "description": {
            "de": "string",
            "en": "string",
            "fr": "string",
            "es": "string",
            "pl": "string"
          }
        }
      ],
      "addresses_count": 2,
      "managers_count": 1,
      "categories_count": 0,
      "dynamicAttributes_count": 0,
      "contacts_count": 3,
      "priceTables": [
        {
          "id": 1,
          "start_date": "2024-01-15T00:00:00.000000Z",
          "customer_number": "K-12345",
          "project_id": 16,
          "type": {
            "id": "string",
            "name": "Basispreistabelle"
          },
          "prices": [
            {
              "id": 1,
              "price_group": "Junior-Entwickler",
              "price": 1.5,
              "price_table_id": "string",
              "type": {},
              "activity": "string",
              "ahr_factor": 1.5
            }
          ],
          "factors": [
            {
              "id": 1,
              "day": {},
              "start_time": "11:10:49",
              "end_time": "15:10:49",
              "factor": 1.5,
              "price_table_id": 1,
              "activity_id": 1
            }
          ]
        }
      ]
    }
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": "string",
        "label": "string",
        "active": true
      }
    ],
    "path": "string",
    "per_page": 1,
    "to": 1,
    "total": 1
  }
}

Response fields

Name
customer_number
Type
string
Description
The customer’s unique identifier, and the value used as its primary key in the URL.
Name
name
Type
string, nullable
Description
The customer’s name.
Name
additional_name
Type
string, nullable
Description
An additional name line for the customer, printed below name on documents.
Name
website
Type
string, nullable
Description
The customer’s website URL.
Name
email
Type
string, nullable
Description
The customer’s general contact e-mail address.
Name
phone
Type
string, nullable
Description
The customer’s phone number.
Name
fax
Type
string, nullable
Description
The customer’s fax number.
Name
currency
Type
string, nullable
Description
The ISO currency code used for offers and invoices for this customer.
Name
comments
Type
string, nullable
Description
Free-text internal notes about the customer.
Name
industry
Type
string, nullable
Description
The name of the industry sector this customer belongs to.
Name
vat
Type
string, nullable
Description
The customer’s VAT (value-added tax) rate, as a percentage.
Name
tax_number
Type
string, nullable
Description
The customer’s VAT ID (Umsatzsteuer-Identifikationsnummer) — not the tax rate, see vat.
Name
iban
Type
string, nullable
Description
The customer’s IBAN, used for SEPA direct debit.
Name
bic
Type
string, nullable
Description
The customer’s BIC, used together with iban for SEPA direct debit.
Name
payment_target
Type
string, nullable
Description
The number of days the customer has to pay an invoice, counted from the invoice date.
Name
payment_target_discount
Type
integer, nullable
Description
The number of days within which paying grants the customer an early-payment discount (Skonto).
Name
inactive
Type
boolean
Description
Whether the customer is inactive and hidden from active-customer lists.
Name
status
Type
object
Description
The legacy alias of inactive, kept for backward compatibility. Read inactive instead. label is delivered translated into the tenant’s language and must not be evaluated — compare value instead. Deprecated since 2025-10-28. Use inactive instead. May be removed on or after 2027-08-31. Not present from API v2 onwards.
Name
status.value
Type
integer
Description
1 if the customer is active, 0 if inactive — the inverse of inactive.
One of: 0, 1
Name
status.label
Type
string
Description
The status as a translated, human-readable string. Do not parse this, compare value instead.
One of: "Inactive", "Active"
Name
created
Type
string (date-time), nullable
Description
When the customer record was created.
Name
modified
Type
string (date-time), nullable
Description
When the customer record was last modified.
Name
billing_procedure
Type
boolean, nullable
Description
Whether this customer is billed via standard invoices or via the incoming-credit-note (self-billing) procedure.
Name
automated_invoicing
Type
boolean, nullable
Description
Whether invoices for this customer are generated automatically rather than created manually.
Name
debit_payment
Type
boolean, nullable
Description
Whether this customer pays by SEPA direct debit rather than by bank transfer.
Name
department_id
Type
integer
Description
The id of the department this customer is assigned to.
Name
addresses
Type
array of CustomerAddress
Description
The customer’s addresses. Present on GET /customers/{customer}, POST /customers and PUT /customers/{customer}; absent on GET /customers (the list endpoint).
Name
addresses.id
Type
integer
Description
The address’s unique identifier.
Name
addresses.name
Type
string
Description
The recipient name printed on this address.
Name
addresses.address
Type
string, nullable
Description
The first address line (street and house number).
Name
addresses.address_line_2
Type
string, nullable
Description
An optional second address line.
Name
addresses.address_line_3
Type
string, nullable
Description
An optional third address line.
Name
addresses.zip_code
Type
string, nullable
Description
The postal code.
Name
addresses.city
Type
string, nullable
Description
The city this address is located in.
Name
addresses.country
Type
string, nullable
Description
The country name.
Name
addresses.is_default
Type
boolean, nullable
Description
Whether this is the customer’s default address.
Name
addresses.is_billing_address
Type
boolean, nullable
Description
Whether invoices are sent to this address.
Name
addresses.is_shipping_address
Type
boolean, nullable
Description
Whether deliveries are sent to this address.
Name
addresses.email
Type
string, nullable
Description
The e-mail address documents for this address are sent to.
Name
addresses.email_cc
Type
string, nullable
Description
An additional e-mail address copied (CC) on documents sent to this address.
Name
addresses.email_bcc
Type
string, nullable
Description
An additional e-mail address blind-copied (BCC) on documents sent to this address.
Name
addresses.country_code
Type
string, nullable
Description
The ISO country code used for e-invoicing (ZUGFeRD/XRechnung).
Name
addresses.inactive
Type
boolean, nullable
Description
Whether this address is inactive and no longer used.
Name
addresses.machine_readable_invoice_version
Type
object, nullable
Description
The machine-readable e-invoice format (e.g. ZUGFeRD, XRechnung) this address supports, if any.
Name
managers
Type
array of CustomerEmployee
Description
The employees responsible for this customer. Present on GET /customers/{customer}, POST /customers and PUT /customers/{customer}; absent on GET /customers.
Name
managers.username
Type
string
Description
The username of the employee responsible for this customer.
Name
managers.has_edit_customer_data_permission
Type
boolean, nullable
Description
Whether this employee may edit the customer’s master data.
Name
managers.has_budget_responsibility_permission
Type
boolean, nullable
Description
Whether this employee has budget responsibility for this customer.
Name
managers.is_primary_employee
Type
boolean, nullable
Description
Whether this employee is the customer’s primary responsible employee.
Name
categories
Type
array of Category
Description
The categories assigned to this customer. Present on all four customer endpoints (GET /customers, GET /customers/{customer}, POST /customers, PUT /customers/{customer}).
Name
categories.name
Type
string
Description
Name of the category, shown wherever an entity is tagged with it.
Name
categories.description
Type
object
Description
Longer explanation of what this category should be used for.
Name
categories.type
Type
object
Description
The kind of entity this category can be attached to, e.g. employee, project or customer.
Name
dynamicAttributes
Type
array of DynamicAttribute
Description
The customer’s custom dynamic attributes. Present on all four customer endpoints (GET /customers, GET /customers/{customer}, POST /customers, PUT /customers/{customer}).
Name
dynamicAttributes.name
Type
string
Description
Name of the dynamic attribute definition this value was entered for.
Name
dynamicAttributes.value
Type
any
Description
The stored value; its shape depends on the neighbouring type field (a string, a number, a boolean, a date, an employee reference, or a list of option values).
Name
dynamicAttributes.type
Type
string
Description
The data type of this attribute, e.g. text, number, date or options, which decides how to interpret value.
One of: "Text", "Integer", "Float", "URL", "E-Mail", "Datum", "Uhrzeit", "Datetime", "Boolean", "Betrag", "Optionen", "Prozent", "Time period", "Textarea", "Users", "Upload"
Name
dynamicAttributes.description
Type
object, nullable
Description
Explanation of what this attribute captures, as configured on its definition.
Name
addresses_count
Type
integer
Description
The number of addresses for this customer. Present only on GET /customers (the list endpoint).
Name
managers_count
Type
integer
Description
The number of employees responsible for this customer. Present only on GET /customers.
Name
categories_count
Type
integer
Description
The number of categories assigned to this customer. Present only on GET /customers.
Name
dynamicAttributes_count
Type
integer
Description
The number of custom dynamic attributes set on this customer. Present only on GET /customers.
Name
contacts_count
Type
integer
Description
The number of contacts for this customer. Present only on GET /customers.
Name
priceTables
Type
array of PriceTable
Description
The customer’s price tables — its own if assigned, otherwise the base price tables. Present on GET /customers/{customer}, POST /customers and PUT /customers/{customer}; absent on GET /customers (the list endpoint). There is no client-side parameter to request or suppress it.
Name
priceTables.id
Type
integer
Description
Unique identifier of the price table.
Name
priceTables.start_date
Type
string (date-time), nullable
Description
Date from which the price table applies.
Name
priceTables.customer_number
Type
string, nullable
Description
Number of the customer this price table belongs to, for a customer-level price table.
Name
priceTables.project_id
Type
integer, nullable
Description
Identifier of the project this price table belongs to, for a project-level price table.
Name
priceTables.type
Type
object, nullable
Description
Whether the price table is scoped to a customer or a project.
Name
priceTables.prices
Type
array of Price
Description
Prices defined in this price table.
Name
priceTables.factors
Type
array of PriceFactor
Description
Time-based factors defined in this price table, e.g. for night or weekend surcharges.

Generated from the OpenAPI specification — edit the source code, not this page.

Customers GET Get a customer