Read this before you build
The few things to understand, not implement, so the integration is predictable.
Authentication
Thomas uses machine-to-machine API keys, server to server. There is no end-user OAuth flow to build: your backend holds one key and calls Thomas on your users’ behalf. Send the key as a bearer token on every request.
curl https://api.thomas.co/v1/assessments/profile/ind_7Qk2 \ -H "Authorization: Bearer $THOMAS_KEY"
Each key carries only the scopes it needs. No key grants bulk access to raw scoring or the item bank.
401 Unauthorized
{ "error": "unauthorized", "message": "Missing or invalid API key." }Identity & reconciliation
Email is the identity key. Send a person's email and we resolve them to one Thomas identity, the same person across every organisation. Matching is exact and case-insensitive. Because this is psychometric data, we never guess with fuzzy or probabilistic matches.
Global and exact. One email, one identity, even across organisations.
Scoped to your company. The same HRIS id at another company is a different person.
No match creates a new identity. If email and HRIS id point at different people, we flag it for review, never a silent merge.
partner reference instead: an opaque id, scoped to your org. Same resolution, no personal data has to leave your system.{ "email": "alex@acme.com" }
→ { "individualId": "ind_7Qk2", "created": false }
# Or resolve without sending an email:
{ "partnerReference": "u_84217" }
→ { "individualId": "ind_7Qk2", "created": false }