Use a stable upstream identifier whenever possible. Email addresses and phone
numbers can change, be shared, or be entered differently across systems.
Identity strategy
external_ref is unique within a Perkstar business. Namespace the value when
more than one source or account can produce the same native ID:
When POST /customers includes an external_ref:
- an existing match is returned with
200 and is not overwritten;
- a missing match is created with
201; and
- retries remain safe beyond the request idempotency window.
Initial import
- Page through the source system in stable order.
- Upsert each customer with
external_ref.
- Store the returned Perkstar customer ID in the source system.
- Checkpoint progress after each completed page.
- Run a second pass for records changed during the import.
Limit concurrency and respect Perkstar’s rate-limit headers. A large import
should use a durable job queue, not one browser request.
Consent
Consent is not a convenience flag. Set consent_marketing or
consent_ad_tracking only when the source system contains a valid, auditable
permission for that purpose. A blank source value should not become true.
Updates and deletion
- Send PATCH only for fields your integration owns.
- Normalise upstream phone numbers before matching where possible.
- Treat a Perkstar anonymisation response as permanent.
- Do not recreate an anonymised person automatically from a stale export.
- Keep API keys and personal payloads out of logs.
Test keys can read customer records but cannot create, edit, or anonymise
them. Perform customer writes only after certification with a live key that
has CUSTOMERS_WRITE.
