Create or update a customer
const url = 'https://app.nexym.nl/api/connect/customers';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"reference":"CUST-0099","name":"Acme Interiors","email":"ops@example.com","phone":"+31 10 123 4567"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://app.nexym.nl/api/connect/customers \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "reference": "CUST-0099", "name": "Acme Interiors", "email": "ops@example.com", "phone": "+31 10 123 4567" }'Upserts a customer by reference within the key’s project. An existing record is
matched on (project_id, reference); only the fields present in the payload are
written, and any key not listed in the request schema is ignored rather than
rejected.
Requires customers: write.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”The write payload for a customer. Only these four keys are read; anything else in the body is ignored.
object
Matched against an existing customer in this project.
Must be a valid address when present.
Responses
Section titled “Responses”An existing customer was updated.
A customer record. Personal data — every read of this resource is written to the project’s access log.
object
The canonical customer key. A guest, which has no customer number at the source, is keyed by e-mail address instead.
Inferred from an order rather than synced from the system that owns customers.
Which entity the record was first seen on, for a guest.
A date-only value, serialised at midnight.
A denormalised address or contact block, stored as JSON exactly as the mapping produced it. Keys vary by connector and by project mapping; treat it as an open object rather than a fixed shape.
A denormalised address or contact block, stored as JSON exactly as the mapping produced it. Keys vary by connector and by project mapping; treat it as an open object rather than a fixed shape.
Free-form store for fields the universal schema does not define for everybody: a connector’s declared extension fields and a project’s own customer fields, each under its own name.
Example
{ "id": 2201, "project_id": 3, "reference": "CUST-0099", "name": "Acme Interiors", "email": "ops@example.com", "is_guest": false, "discovered_via": "order", "phone": "+31 10 123 4567", "vat_number": "NL123456789B01", "gender": null, "date_of_birth": "1984-03-02T00:00:00.000000Z", "billing": { "name": "Acme Interiors", "street": "Voorstraat 12", "postcode": "1234 AB", "city": "Middelburg", "country": "NL" }, "shipping": { "name": "Acme Interiors", "street": "Voorstraat 12", "postcode": "1234 AB", "city": "Middelburg", "country": "NL" }, "meta": { "service_code": "INSTALL-STD" }, "source_connection_id": 7, "created_at": "2026-04-11T09:55:12.000000Z", "updated_at": "2026-09-14T13:41:05.000000Z"}A new customer was created.
A customer record. Personal data — every read of this resource is written to the project’s access log.
object
The canonical customer key. A guest, which has no customer number at the source, is keyed by e-mail address instead.
Inferred from an order rather than synced from the system that owns customers.
Which entity the record was first seen on, for a guest.
A date-only value, serialised at midnight.
A denormalised address or contact block, stored as JSON exactly as the mapping produced it. Keys vary by connector and by project mapping; treat it as an open object rather than a fixed shape.
A denormalised address or contact block, stored as JSON exactly as the mapping produced it. Keys vary by connector and by project mapping; treat it as an open object rather than a fixed shape.
Free-form store for fields the universal schema does not define for everybody: a connector’s declared extension fields and a project’s own customer fields, each under its own name.
Example
{ "id": 2201, "project_id": 3, "reference": "CUST-0099", "name": "Acme Interiors", "email": "ops@example.com", "is_guest": false, "discovered_via": "order", "phone": "+31 10 123 4567", "vat_number": "NL123456789B01", "gender": null, "date_of_birth": "1984-03-02T00:00:00.000000Z", "billing": { "name": "Acme Interiors", "street": "Voorstraat 12", "postcode": "1234 AB", "city": "Middelburg", "country": "NL" }, "shipping": { "name": "Acme Interiors", "street": "Voorstraat 12", "postcode": "1234 AB", "city": "Middelburg", "country": "NL" }, "meta": { "service_code": "INSTALL-STD" }, "source_connection_id": 7, "created_at": "2026-04-11T09:55:12.000000Z", "updated_at": "2026-09-14T13:41:05.000000Z"}No key, a key that does not match, a revoked key, or an expired one. The body says which, and nothing else — an unusable key is never described further.
Every error this API returns carries a single human-readable message.
object
Examples
No bearer token, or one too short to hold a prefix
{ "message": "Missing or invalid API key."}Unknown key, or a failed hash check
{ "message": "Invalid API key."}The key was revoked in the dashboard
{ "message": "API key has been revoked."}The key's expiry has passed
{ "message": "API key has expired."}The key is valid but its abilities do not cover this resource at this right.
Every error this API returns carries a single human-readable message.
object
Examples
{ "message": "This API key lacks read access to orders."}{ "message": "This API key lacks write access to stock."}The payload failed validation. The framework’s standard shape: a summary
message plus an errors map of field to messages. Requires
Accept: application/json — without it the response is a 302 redirect instead.
object
Field name to the list of messages that field failed on.
object
Examples
{ "message": "The reference field is required. (and 1 more error)", "errors": { "reference": [ "The reference field is required." ], "name": [ "The name field is required." ] }}The per-minute rate limit was exceeded. The limit is 120 requests per minute by
default (CONNECT_API_RATE_PER_MIN), counted per API key — or per IP address for
a request that never authenticated.
Every error this API returns carries a single human-readable message.
object
Examples
{ "message": "Too many requests — slow down."}Headers
Section titled “Headers”Seconds until the limit resets.
Requests allowed per minute.
Requests left in the current window.