Authentication

Base URL

All API requests use the following base URL:

https://api.planni.de/v1

API Keys

Every request must include an X-Api-Key header with a valid API key.

curl -H "X-Api-Key: your-api-key" https://api.planni.de/v1/contacts

API keys are created in the planni admin under Settings > Integrations.

Scopes

Each API key can be assigned one or more scopes to restrict access:

An API key created without scopes has full access. A key cannot be created with an empty scope list: the request is refused, so choosing no permissions never yields a full-access key.

Pagination

List endpoints support pagination with limit and offset query parameters:

curl -H "X-Api-Key: your-api-key" \
  "https://api.planni.de/v1/contacts?limit=10&offset=20"

Record IDs

Every record carries an id. Its shape depends on the account:

planni moves each account to UUID keys once. From then on responses return the UUID string in id.

Both shapes are accepted on input. An integer id you stored before the move keeps working afterwards and serves the same record as its UUID, so PUT /v1/contacts/42 and PUT /v1/contacts/0192f5a1-7b3c-7d2e-8f00-123456789abc update the same contact. Order ids have always been UUIDs: an integer order id answers 404.

An id that names no record, or that is neither a plain integer nor a UUID (for example 007, +42 or 42.0), answers 404 Not Found. In PUT /v1/contacts/{id} and GET /v1/orders/{id}, an id longer than 64 characters is refused with 400 Bad Request, except an order id made only of digits, which answers 404.

Recommendations:

• Store ids as strings and compare them as strings, so both shapes fit.
• Do not parse or do arithmetic with ids.
• A tool that deduplicates on id (such as a Zapier trigger) sees each existing record under its new id once after the move.
• Ids copied into an order when it was placed (for example the product of an order item) keep the value they had then.

Error Handling

The API returns standard HTTP status codes.

Error Responses

{
  "error": "Unauthorized",
  "message": "Missing or invalid API key"
}

Status Codes

Rate Limiting

There are currently no rate limits enforced. This may change in future versions.