CentraPoint

API

Customers API

Create, upsert, search, list, retrieve and update customers, keyed by your own externalReference, and send or create customer portal links.

On this page

Overview#

Customers are the people and businesses you invoice and take payments from. Keep them in sync with your own system by sending your ID as externalReference: creating with the same reference again updates the existing customer instead of duplicating it. Available on every plan that includes the REST API.

Customer endpoints
EndpointPurpose
POST /api/v1/customersCreate, or upsert by externalReference
GET /api/v1/customersList (paginated), search with q, filter by externalReference or email
GET /api/v1/customers/{id}Get one customer
GET /api/v1/customers/lookupFind one customer by email, externalReference or accountCode
PATCH /api/v1/customers/{id}Update fields
POST /api/v1/customers/{id}/portal-linkEmail the customer a portal sign-in link, or create a single-use sign-in link without email
GET /api/v1/customers/{id}/standingAccount standing
/api/v1/customers/{id}/cards…Saved cards

The customer object#

Customer
{
  "id": "cmg2c0s7t0003cust0001abcd",
  "accountCode": "CUS-00042",
  "externalReference": "CRM-1001",
  "contactType": "company",
  "email": "[email protected]",
  "billingEmail": "[email protected]",
  "firstName": "Thandi",
  "lastName": "Nkosi",
  "company": "Nkosi Trading (Pty) Ltd",
  "vatNumber": "4123456789",
  "phone": "+27821234567",
  "address": "12 Long Street, Cape Town, 8001",
  "active": true,
  "metadata": {
    "crmId": "0061x00000AbCdE"
  },
  "createdAt": "2026-09-25T08:00:00.000Z",
  "updatedAt": "2026-09-25T08:00:00.000Z"
}
Customer fields
FieldTypeDescription
idrequiredstringCentraPoint customer ID.
accountCoderequiredstringAccount code assigned by CentraPoint (shown on invoices and in accounting exports).
externalReferencerequiredstring | nullYour ID for the customer.
contactTyperequiredstringindividual or company.
emailrequiredstringStored in lower case. Also the customer's sign-in address for the customer portal.
billingEmailrequiredstring | nullSeparate billing address. When set, invoice emails, payment receipts for this customer's payments and subscription emails (including payment reminders) go here instead of email, and it is printed on invoice and statement PDFs. Portal sign-in emails and the welcome email still go to email, the portal login address. A payment confirmation from hosted checkout goes to the email the payer entered.
firstNamerequiredstring
lastName, company, vatNumber, phone, addressrequiredstring | nullOptional details, printed on invoices where relevant.
activerequiredbooleanInactive customers are kept for history.
metadatarequiredobjectYour key/value data; {} when empty. See metadata.
createdAt, updatedAtrequiredstringISO 8601 UTC timestamps.

Create or upsert a customer#

POST/api/v1/customers
Create customer fields
FieldTypeDescription
externalReferenceoptionalstring1–190 characters. Your ID; makes the request an upsert.
emailrequiredstring (email)Up to 200 characters.
contactTypeoptionalstringindividual (default) or company.
billingEmailoptionalstring (email) | nullUp to 320 characters.
firstNamerequiredstring1–100 characters.
lastNameoptionalstring | nullUp to 100 characters.
companyoptionalstring | nullUp to 200 characters.
vatNumberoptionalstring | nullUp to 30 characters.
phoneoptionalstring | nullUp to 30 characters.
addressoptionalstring | nullUp to 1000 characters.
metadataoptionalobjectKey/value data (rules).
curl -X POST "https://app.centrapoint.co.za/api/v1/customers" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 3f6c2a4e-8d1b-4f7a-9c2e-5b1d0a7e6f31" \
  -H "Content-Type: application/json" \
  -d '{
    "externalReference": "CRM-1001",
    "email": "[email protected]",
    "firstName": "Thandi",
    "lastName": "Nkosi",
    "company": "Nkosi Trading (Pty) Ltd",
    "vatNumber": "4123456789",
    "phone": "+27821234567",
    "metadata": {
      "crmId": "0061x00000AbCdE"
    }
  }'

Returns the customer object. Supports the Idempotency-Key header.

Upsert rules#

Create versus upsert outcomes
RequestSituationResult
No externalReference–201 new customer (even if the email already exists)
With externalReferenceA customer has this reference200 that customer updated with the sent fields
With externalReferenceNo match, but a customer with the same email has no reference200 that customer is adopted: the reference is set and fields updated
With externalReferenceNo match201 new customer

On update, fields you omit keep their values. Concurrent upserts with the same reference are serialised, so they never create two customers. Creating a customer counts towards your plan's customer limit (403 plan_limit).

List customers#

GET/api/v1/customers
List query parameters
FieldTypeDescription
qoptionalstringSearch (up to 100 characters): every word must appear (case-insensitive, anywhere) in the first or last name, company, email, billing email, accountCode or externalReference. For example q=nkosi trading.
externalReferenceoptionalstringExact match.
emailoptionalstringExact match, case-insensitive.
limitoptionalinteger1–100, default 20.
startingAfteroptionalstringKeyset pagination: the previous page's nextCursor.

Returns { "data": [ … ], "hasMore": false, "nextCursor": null }, newest first. Filters combine. startingAfter must be the id of a customer in the same filtered list, otherwise the request returns 400. Clients that only read data keep working.

curl -X GET "https://app.centrapoint.co.za/api/v1/customers?externalReference=CRM-1001" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"
curl -X GET "https://app.centrapoint.co.za/api/v1/customers?q=nkosi%20trading&limit=50" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Look up a customer#

GET/api/v1/customers/lookup
Lookup query parameters
FieldTypeDescription
emailoptionalstringExact match, case-insensitive (up to 200 characters).
externalReferenceoptionalstringExact match (up to 190 characters).
accountCodeoptionalstringExact match, e.g. CUS-00042 (up to 50 characters).

Send exactly one of the three (otherwise 400). Returns the customer object itself (not a list) or 404 not_found. When several customers share an email, the oldest one is returned; use the list endpoint to see them all.

curl -X GET "https://app.centrapoint.co.za/api/v1/customers/lookup?accountCode=CUS-00042" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Get a customer#

GET/api/v1/customers/{id}
curl -X GET "https://app.centrapoint.co.za/api/v1/customers/cmg2c0s7t0003cust0001abcd" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Update a customer#

PATCH/api/v1/customers/{id}

Partial update: send only the fields to change. null clears an optional field. metadata replaces the whole map (send null to clear it). active: false deactivates the customer. You can also set or change externalReference (it must not belong to another customer). Unknown fields are rejected with 400. The Idempotency-Key header is not used on PATCH, which is safe to repeat.

curl -X PATCH "https://app.centrapoint.co.za/api/v1/customers/cmg2c0s7t0003cust0001abcd" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+27829876543",
    "company": null
  }'
POST/api/v1/customers/{id}/portal-link

Emails the customer a sign-in link to your customer portal and returns it. No body is needed (or send { "email": true }). Each call sends an email (the Idempotency-Key header is ignored). To get a link without an email, see below.

curl -X POST "https://app.centrapoint.co.za/api/v1/customers/cmg2c0s7t0003cust0001abcd/portal-link" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"
200 response
{
  "object": "portal_link",
  "customerId": "cmg2c0s7t0003cust0001abcd",
  "url": "https://app.centrapoint.co.za/portal/acme",
  "sent": true
}
Portal link outcomes
StatuserrorWhen
200–Emailed.
409portal_disabledThe portal is off (Settings → Customer portal) or not in your plan.
422not_sentInactive customer, the portal link email template is disabled, or the email failed. url is included so you can share it another way.
404not_foundNo customer with this ID.

Send { "email": false } to receive a single-use sign-in link instead: opening it signs the customer straight in to the portal (a normal 24-hour portal session) without the emailed code, and nothing is emailed. Use it behind a "Billing" or "Pay invoice" button in your own app: create the link when the signed-in user clicks, then redirect the browser to url.

Sign-in link fields
FieldTypeDescription
emailrequiredbooleanfalse for a sign-in link. Default true (email the portal link, as above).
expiresInMinutesoptionalinteger1–1440 (24 hours), default 15. The link stops working after this, or once used.
sectionoptionalstringPortal page to open after sign-in: invoices, payments, subscriptions, statement, payment-methods or profile. Default the overview.
curl -X POST "https://app.centrapoint.co.za/api/v1/customers/cmg2c0s7t0003cust0001abcd/portal-link" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": false,
    "expiresInMinutes": 10,
    "section": "invoices"
  }'
200 response
{
  "object": "portal_link",
  "customerId": "cmg2c0s7t0003cust0001abcd",
  "url": "https://app.centrapoint.co.za/api/portal/auth/acme/link?token=q3Jx…&next=invoices",
  "sent": false,
  "expiresAt": "2026-10-01T08:10:00.000Z"
}
  • Treat url as a secret: it signs in as the customer. Don't log it, email it or show it to anyone but that customer; only a hash of it is stored. Link previewers and email scanners can use up a single-use link, so create it on demand rather than sending it by email (use the default email: true for that).
  • Used, expired or unknown links open the portal sign-in page with a notice; the customer can then sign in with the emailed code. Deactivating the customer ends their sessions and unused links.
  • Errors: 409 portal_disabled (portal off or not in your plan), 422 customer_inactive, 404 not_found, 400 when expiresInMinutes or section is sent without email: false.

Errors#

Customer errors
StatuserrorWhen
400invalid_requestValidation failed, invalid metadata, unknown field (PATCH), externalReference already used by another customer (PATCH), not exactly one lookup key, q longer than 100 characters or unknown startingAfter (list).
401unauthorizedMissing or invalid API key.
403plan_restricted / plan_limit / account_restrictedNo API access, customer limit reached, or account read-only (writes).
404not_foundNo customer with this ID in your organisation.
409idempotency_conflict / portal_disabledIdempotency-Key reused with a different body (POST), or the customer portal is off (portal link).
422not_sent / customer_inactivePortal link not emailed, or sign-in link for an inactive customer (see above).
429 / 500rate_limited / internal_errorSee Errors