Customers¶

The Customers API manages all customers and their assignments.

Visibility

By default, users can only see customers within their own group. With the inventory_global permission, all customers become visible.

Endpoints¶

Method	Path	Description	Permission
`GET`	`/api/v2/customers`	List all customers	`customers_view`
`GET`	`/api/v2/customers/{id}`	Retrieve a single customer	`customers_view`
`POST`	`/api/v2/customers`	Create a customer	`customers_edit`
`PUT`	`/api/v2/customers/{id}`	Update a customer	`customers_edit`
`DELETE`	`/api/v2/customers/{id}`	Delete a customer	`customers_delete`

Field Mapping¶

Metrology Code	API Field Name	Description
`K4601`	`name`	Customer name
`K4602`	`contact`	Contact person
`K4603`	`city`	City
`K4604`	`postal_code`	Postal code

List All Customers¶

curl -X GET "https://example.com/api/v2/customers?page=1&per_page=25" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Query Parameters¶

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 25)
`sort`	string	Sort field, e.g. `name` or `-city` (descending)
`filter[name]`	string	Filter by customer name
`filter[city]`	string	Filter by city
`filter[postal_code]`	string	Filter by postal code

Response¶

{
  "data": [
    {
      "id": 5,
      "name": "Mustermann GmbH",
      "contact": "Max Mustermann",
      "city": "München",
      "postal_code": "80331",
      "address": "Industriestraße 42",
      "email": "info@mustermann.de",
      "phone": "+49 89 1234567"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 87,
    "last_page": 4
  },
  "links": {
    "first": "/api/v2/customers?page=1",
    "last": "/api/v2/customers?page=4",
    "next": "/api/v2/customers?page=2",
    "prev": null
  }
}

Retrieve a Single Customer¶

curl -X GET "https://example.com/api/v2/customers/5" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Create a Customer¶

curl -X POST "https://example.com/api/v2/customers" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Neuer Kunde AG",
    "contact": "Erika Musterfrau",
    "city": "Berlin",
    "postal_code": "10115",
    "address": "Hauptstraße 1",
    "email": "info@neuer-kunde.de",
    "phone": "+49 30 9876543"
  }'

Required Fields

The name field is required. All other fields are optional.

Successful Response (201)¶

{
  "data": {
    "id": 88,
    "name": "Neuer Kunde AG",
    "contact": "Erika Musterfrau",
    "city": "Berlin",
    "postal_code": "10115",
    "address": "Hauptstraße 1",
    "email": "info@neuer-kunde.de",
    "phone": "+49 30 9876543"
  }
}

Update a Customer¶

curl -X PUT "https://example.com/api/v2/customers/88" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": "Hans Meier",
    "phone": "+49 30 1111111"
  }'

Partial Updates

Only the fields to be changed need to be sent.

Delete a Customer¶

curl -X DELETE "https://example.com/api/v2/customers/88" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Caution

A customer can only be deleted if no inventory items are still linked to them.

Group Scoping¶

The Customers API automatically takes the authenticated user's group membership into account:

Permission	Visibility
Without `inventory_global`	Only customers within the user's own group
With `inventory_global`	All customers in the system

# User without inventory_global sees only their own customers
curl "https://example.com/api/v2/customers" \
  -H "Authorization: Bearer {token_without_global}"
# → Only customers from the user's group

# User with inventory_global sees all customers
curl "https://example.com/api/v2/customers" \
  -H "Authorization: Bearer {token_with_global}"
# → All customers in the system

Sorting and Filtering¶

# Sorted by name
curl "https://example.com/api/v2/customers?sort=name" \
  -H "Authorization: Bearer {token}"

# Customers in Munich
curl "https://example.com/api/v2/customers?filter[city]=München" \
  -H "Authorization: Bearer {token}"

# Filter by postal code, sorted descending
curl "https://example.com/api/v2/customers?filter[postal_code]=80331&sort=-name" \
  -H "Authorization: Bearer {token}"

Error Codes¶

HTTP Status	Meaning
`401`	Not authenticated — invalid or missing token
`403`	Insufficient permissions (`customers_view`, `customers_edit`, or `customers_delete` missing)
`404`	Customer not found or not within the user's own group
`409`	Customer cannot be deleted — linked inventory items exist
`422`	Validation error — e.g. missing customer name
`429`	Rate limit exceeded