Restore a deleted customer

POSThttps://<your-url>/api/v2/customers/{customer}/actions/restore

MCP id customers.actions.restore

Clears the soft-delete marker and returns the customer in the detail view.

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. Accepts If-Match. 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: Restore a deleted customer

curl -X POST \
  'https://<your-url>/api/v2/customers/1/actions/restore' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <key>' \
  -d '{}'

const response = await fetch('https://<your-url>/api/v2/customers/1/actions/restore', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Idempotency-Key': '<key>',
  },
  body: JSON.stringify({}),
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->withHeader('Idempotency-Key', '<key>')
    ->post('https://<your-url>/api/v2/customers/1/actions/restore', [
    ]);

import requests
response = requests.request(
    'POST',
    'https://<your-url>/api/v2/customers/1/actions/restore',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json', 'Content-Type': 'application/json', 'Idempotency-Key': '<key>'},
    json={},
)

Response

The shape of the response, with sample values.

{
  "data": {
    "id": 1,
    "name": "…",
    "code": "…",
    "color": "…",
    "status": "suspect",
    "email": "…",
    "phone": "…",
    "address": "…",
    "zip": "…",
    "city": "…",
    "country": "…",
    "lat": "…"
  },
  "meta": {
    "warnings": [
      {
        "…": "6 fields of warnings"
      }
    ]
  }
}

{
  "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/precondition-failed",
  "title": "Precondition failed",
  "status": 412,
  "detail": "The record changed since the version named in If-Match. Re-read it and retry.",
  "instance": "/api/v2/work-items/812",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S",
  "current_version": 12
}

24 more fields, listed under Response

Restoring additionally requires customers::delete as well as customers::create. Restoring a customer that is not deleted succeeds and returns an already_in_target_state warning. The customer's projects are not restored: deleting the customer soft-deleted each of them, and each is brought back through POST projects/{project}/actions/restore. The restore finds a deleted customer on its own, so the trashed parameter is not accepted.

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

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-Matchstring

The ETag a write is conditional on. A stale validator is 412 precondition-failed.

Idempotency-Keystring≤ 255

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

Response 200

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.
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

412 Precondition failed.

precondition-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 POST. Anything else answers 405.

Something wrong or missing on this page? Tell us

Access

Path parameters

Query parameters

Request headers

Response 200

Headers

Errors