Create a customer

POSThttps://<your-url>/api/v2/customers

MCP id customers.storeAlso on this path: GET List customers

Creates a customer and returns it in the detail view with a Location header. name, code, color, status and account_manager_id are required: the first four have no default, and an account manager is mandatory on the customer form in plnnrly. code must be unique. color must be a CSS hex triplet or sextet; any other value would read back as #6b7280.

Token scope: api:write:customers
Without it: 403 insufficient-token-scope.
Permission: customers::create
Without it: 403 insufficient-permission.
Rate cost: 1 unit, write bucket. A write costs the same whatever view you ask for.
Also: Accepts Idempotency-Key. Never cached: private, no-store. Unknown body keys are refused, never dropped.

Both are checked, scope first. A token never does more than its user. How access is checked

Request

Example: A new active customer

curl -X POST \
  'https://<your-url>/api/v2/customers' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <key>' \
  -d '{
    "name": "Acme Industries",
    "code": "ACM",
    "color": "#1d4ed8",
    "status": "active",
    "email": "hello@acme.test",
    "address": "Keizersgracht 1",
    "zip": "1015 CJ",
    "city": "Amsterdam",
    "country": "NL",
    "customer_since": "2026-01-15",
    "account_manager_id": 1
  }'

const response = await fetch('https://<your-url>/api/v2/customers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Idempotency-Key': '<key>',
  },
  body: JSON.stringify({
    "name": "Acme Industries",
    "code": "ACM",
    "color": "#1d4ed8",
    "status": "active",
    "email": "hello@acme.test",
    "address": "Keizersgracht 1",
    "zip": "1015 CJ",
    "city": "Amsterdam",
    "country": "NL",
    "customer_since": "2026-01-15",
    "account_manager_id": 1
  }),
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->withHeader('Idempotency-Key', '<key>')
    ->post('https://<your-url>/api/v2/customers', [
        'name' => 'Acme Industries',
        'code' => 'ACM',
        'color' => '#1d4ed8',
        'status' => 'active',
        'email' => 'hello@acme.test',
        'address' => 'Keizersgracht 1',
        'zip' => '1015 CJ',
        'city' => 'Amsterdam',
        'country' => 'NL',
        'customer_since' => '2026-01-15',
        'account_manager_id' => 1,
    ]);

import requests
response = requests.request(
    'POST',
    'https://<your-url>/api/v2/customers',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json', 'Content-Type': 'application/json', 'Idempotency-Key': '<key>'},
    json={'name': 'Acme Industries', 'code': 'ACM', 'color': '#1d4ed8', 'status': 'active', 'email': 'hello@acme.test', 'address': 'Keizersgracht 1', 'zip': '1015 CJ', 'city': 'Amsterdam', 'country': 'NL', 'customer_since': '2026-01-15', 'account_manager_id': 1},
)

Response

The shape of the response, with sample values.

{
  "data": {
    "id": 1,
    "name": "Acme Industries",
    "code": "ACM",
    "color": "#1d4ed8",
    "status": "active",
    "email": "hello@acme.test",
    "phone": "…",
    "address": "Keizersgracht 1",
    "zip": "1015 CJ",
    "city": "Amsterdam",
    "country": "NL",
    "lat": "…"
  }
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/idempotency-key-in-flight",
  "title": "Idempotency key in flight",
  "status": 409,
  "detail": "The original request for this Idempotency-Key is still being processed. Retry shortly.",
  "instance": "/api/v2/worklogs",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S"
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "3 fields failed validation.",
  "instance": "/api/v2/worklogs",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S",
  "errors": [
    {
      "pointer": "/date",
      "code": "date_format",
      "detail": "The date does not match the format Y-m-d."
    },
    {
      "pointer": "/minutes",
      "code": "min",
      "detail": "The minutes must be at least 1."
    },
    {
      "pointer": "/description",
      "code": "required",
      "detail": "The description field is required."
    }
  ]
}

24 more fields, listed under Response

tag_ids replaces the whole tag set and may be omitted. Sending address, zip or city geocodes the address server-side and fills lat and lng, which are not writable. debtor_code additionally requires billing_settings::update.

Query parameters

Unknown parameters are refused with 400, naming the parameter.

viewstring

Which field set to render.

summarydetaildefault

Request headers

X-Request-Idstringpattern

A correlation id of your own. It is recorded in our logs next to the server's request id but never returned: the response header always carries the server's id. A value that does not match the pattern is discarded silently, never rejected.

Idempotency-Keystring≤ 255

A caller-chosen key that makes this POST safe to retry. Replaying it returns the original response with Idempotency-Replayed: true.

Request body

Unknown keys are refused with 422, naming the key.

namestring≤ 255Required

Customer name. This is the default sort key and one of the fields ?q= searches.

codestring≤ 255UniqueRequired

Short customer code, e.g. ACM. Prefixes every work item's issue key, is enforced unique on write, and is one of the fields ?q= searches.

Must be unique across Customer.

colorstringpatternRequired

Chip colour as a CSS hex triplet or sextet, e.g. #1d4ed8. A stored value that is not valid hex reads back as #6b7280.

statusstringRequired

Where the customer sits in the sales lifecycle.

suspect: An unqualified lead; nobody has established a need yet.
prospect: A qualified lead being actively pursued towards a first deal.
future-opportunity: A real opportunity, parked until a later moment.
active: A paying customer with work or a subscription running.
inactive: A former customer, kept for history and no longer pursued.

New values may be added.

account_manager_idinteger → User.idRequired

Responsible account manager. Required on create; unassigned when the user is deleted.

emailemail or null≤ 255

Primary email address. The third field ?q= searches; not unique.

phonestring or null≤ 255

Phone number.

addressstring or null≤ 255

Street address. Writing this, zip or city re-geocodes lat and lng.

zipstring or null≤ 255

Postal code.

citystring or null≤ 255

City.

Response 201

Returns a Customer in the detail view.

Headers

ETag: A strong validator of exactly this representation.
Idempotency-Replayed: true when this response was replayed from a stored Idempotency-Key rather than produced by a new write.
Location: The absolute URL of the created or queued resource.
RateLimit: The IETF httpapi-ratelimit-headers form of your remaining allowance on the tightest bucket this request touched.
RateLimit-Policy: The ceiling and window of that bucket, as <limit>;w=<seconds>.
X-Request-Id: The server-generated ULID correlating this response with our logs.

Every response also carries Cache-Control, Vary, X-Content-Type-Options, X-Plnnrly-Api-Version, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Headers and versioning

idinteger

Unique identifier.

namestring≤ 255

Customer name. This is the default sort key and one of the fields ?q= searches.

codestring≤ 255

Short customer code, e.g. ACM. Prefixes every work item's issue key, is enforced unique on write, and is one of the fields ?q= searches.

colorstring≤ 255

Chip colour as a CSS hex triplet or sextet, e.g. #1d4ed8. A stored value that is not valid hex reads back as #6b7280.

statusstring

Where the customer sits in the sales lifecycle.

suspectprospectfuture-opportunityactiveinactive

New values may be added.

emailstring or null≤ 255

Primary email address. The third field ?q= searches; not unique.

phonestring or null≤ 255

Phone number.

addressstring or null≤ 255

Street address. Writing this, zip or city re-geocodes lat and lng.

zipstring or null≤ 255

Postal code.

citystring or null≤ 255

City.

countrystring or null≤ 255

Country as an ISO 3166-1 alpha-2 code, e.g. NL, as plnnrly writes it. Older records may hold any string.

latstring or null≤ 255Server-assigned

Latitude, geocoded from the address whenever address, zip or city changes. Not writable.

lngstring or null≤ 255Server-assigned

Longitude, geocoded from the address whenever address, zip or city changes. Not writable.

founded_atdate (YYYY-MM-DD) or null

Day the customer's company was founded.

customer_sincedate (YYYY-MM-DD) or null

Day this customer became a customer.

is_vat_exemptboolean

Whether invoices to this customer are issued without VAT.

payment_daysinteger or nullServer-assigned

Payment term in days, as held by the accounting integration. Read by the invoice composer; written only by the Exact sync.

debtor_codestring or null≤ 255

Debtor number in the accounting system. Writing it requires billing_settings::update.

exact_account_idstring or null≤ 255Server-assigned

Account identifier in Exact Online, written by the sync.

exact_synced_attimestamp (YYYY-MM-DDThh:mm:ssZ) or nullServer-assigned

When the Exact sync last handled this customer, or null if never.

exact_keep_local_addressbooleanServer-assigned

Whether the Exact sync leaves this customer's local address alone although it differs from the one in Exact. Set when a user accepts the difference on the Exact customers screen in plnnrly; not writable.

account_manager_idinteger or null

Responsible account manager. Required on create; unassigned when the user is deleted.

customer_category_idinteger or null

Customer category, or null.

company_type_idinteger or null

Company type, or null. Company types are your organisation's own list, maintained in plnnrly and not exposed as a collection.

company_size_idinteger or null

Company size band, or null. Company sizes are your organisation's own list, maintained in plnnrly and not exposed as a collection.

company_branch_idinteger or null

Industry branch, or null.

created_attimestamp (YYYY-MM-DDThh:mm:ssZ)

Creation timestamp.

updated_attimestamp (YYYY-MM-DDThh:mm:ssZ)

Last-write timestamp; use for incremental sync.

deleted_attimestamp (YYYY-MM-DDThh:mm:ssZ) or null

Soft-delete timestamp, null while live.

customer_categoryRef or CustomerCategorySummary or null

The customer's category. Rendered as {"id": N} until named in ?include=customer_category, and null where none is assigned.

company_branchRef or CompanyBranchSummary or null

The customer's industry branch. Rendered as {"id": N} until named in ?include=company_branch, and null where none is assigned.

projects_countinteger≥ 0

Number of live projects for this customer. Soft-deleted projects are not counted.

contacts_countinteger≥ 0

Number of contacts on this customer.

tags_countinteger≥ 0

Number of tags on this customer.

linksCustomerLinks

Show 3 child fields

links.selfurl

The canonical URI of this record.

links.projectsurl

Projects for this customer.

links.contactsurl

Contacts on this customer.

tagsarray of TagSummary≤ 50Only with include

Tags on this customer. A customer takes at most 50 tags, so the include lists them all. tag_ids replaces the whole set.

Wrapped in { data, meta }; meta.truncated says whether the cap was hit and meta.count is the full count.

Show 2 child fields

tags.idinteger

Unique identifier.

tags.titlestring≤ 255

Tag title as shown in the UI.

Errors

403 Forbidden.

forbidden-by-policy insufficient-permission insufficient-token-scope

409 Conflict.

idempotency-key-in-flight idempotency-key-reused

415 Unsupported media type.

unsupported-media-type

422 Unprocessable content.

unprocessable-relationship validation-failed

7 errors every operation can return: 400, 401, 404, 406, 429, 500, 503

400 Bad request.

idempotency-key-required invalid-cursor invalid-query-parameter malformed-request unsupported-parameter

401 Unauthenticated.

token-expired unauthenticated

404 Not found.

endpoint-not-found resource-not-found

406 Not acceptable.

not-acceptable

429 Too many requests.

rate-limit-exceeded

500 Server error.

internal-error

503 Service unavailable.

tenant-unavailable

This path allows GET, POST. Anything else answers 405.

Something wrong or missing on this page? Tell us

Access

Query parameters

Request headers

Request body

Response 201

Headers

Errors