- Purpose
- Keep candidate records aligned with the source system without duplicates.
- Prerequisites
- users.write scope
- Architecture
- POST /users is an upsert on external_id; GET /users?external_id= resolves.
Configuration
| Idempotency | Idempotency-Key header per source event |
Implementation steps
- 01Send the upsert on the order/stage event
- 02Persist the returned id alongside your own record
- 03Resolve by external_id thereafter
Examples
Upsert
json
{
"email": "jane.smith@example.com",
"first_name": "Jane",
"last_name": "Smith",
"external_id": "WC-8291",
"source_system": "commerce-platform"
}Testing procedure
- Send the same payload twice and assert one candidate
Troubleshooting
422 validation_failed
Normalise and trim inputs from the source system before sending.