- Purpose
- Avoid duplicate or orphaned candidates when people change name, email or employer.
- Prerequisites
- Access to the source system's identifier scheme
- Architecture
- external_id is the join key. Email is a contact attribute, never an identity.
Configuration
| Format | Opaque string, ≤64 chars, unique per tenant |
Implementation steps
- 01Select an immutable identifier from the source system.
- 02Store it on the candidate at creation time.
- 03Resolve by external_id on every subsequent operation.
- 04Define behaviour when the same external_id arrives with a new email.
Examples
Lookup
bash
GET /api/v1/users?external_id=WC-8291Testing procedure
- Change the candidate's email upstream and confirm one record remains
Troubleshooting
409 external_id_conflict
The identifier is reused across people. Fix the source scheme before go-live.