Read a customer

GEThttps://<your-url>/api/v2/customers/{customer}

MCP id customers.showAlso on this path: PATCH Update a customer, DELETE Delete a customer

Returns one customer in the detail view.

Token scope: api:read:customers
Without it: 403 insufficient-token-scope.
Permission: customers::read
Without it: 403 insufficient-permission.
Rate cost: 1 unit, read bucket.
Also: If-None-Match answers 304 when nothing changed. Never cached: private, no-store. Unknown query parameters are refused, never ignored.

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

Request

Example: One customer with its category and tags

curl -G \
  'https://<your-url>/api/v2/customers/1' \
  --data-urlencode 'include=customer_category,company_branch,tags' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json'

const response = await fetch('https://<your-url>/api/v2/customers/1?include=customer_category%2Ccompany_branch%2Ctags', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
  },
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->get('https://<your-url>/api/v2/customers/1?include=customer_category%2Ccompany_branch%2Ctags');

import requests
response = requests.request(
    'GET',
    'https://<your-url>/api/v2/customers/1?include=customer_category%2Ccompany_branch%2Ctags',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json'},
)

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": "…"
  },
  "meta": {
    "actions": [
      "restore"
    ]
  }
}

24 more fields, listed under Response

The response carries a strong ETag derived from updated_at; send it back as If-None-Match to get a 304. A trashed customer is 404 unless trashed=with is passed, which needs only customers::read.

Path parameters

customerintegerRequired

The Customer's numeric id. Accepts a soft-deleted record.

Query parameters

Unknown parameters are refused with 400, naming the parameter.

viewstring

Which field set to render.

summarydetaildefault

trashedstring

Whether soft-deleted rows are included.

withoutdefaultwithonly

metaarray of string

Optional meta members to compute for this response.

actions

New values may be added.

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.

If-None-Matchstring

The ETag a read is conditional on. A match is answered 304 with no body.

Response 200

Returns a Customer in the detail view.

Headers

ETag: A strong validator of exactly this representation.
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

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

304 Not modified.

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, PATCH, DELETE. Anything else answers 405.

Something wrong or missing on this page? Tell us

Access

Path parameters

Query parameters

Request headers

Response 200

Headers

Errors