> For the complete documentation index, see [llms.txt](https://helpcenter.talentlead.nl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://helpcenter.talentlead.nl/talent-assessment/api/referentie/personen.md).

# Personen

Personen in je talentpool: importeren vanuit je ATS, opvragen met filters, bijwerken en archiveren. Gebruik `externalId` om je eigen systeem-id te koppelen.

## List persons

> People in your talent pool, newest first, cursor-paginated. Requires the \`persons:read\` scope.

```json
{"openapi":"3.1.0","info":{"title":"TalentLead API","version":"1.0.0"},"tags":[{"name":"Persons","description":"People in your talent pool"}],"servers":[{"url":"https://assessment.talentlead.nl","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key (tl_live_...)","description":"API key from the TalentLead dashboard (Organisatie → API)."}}},"paths":{"/api/v1/persons":{"get":{"tags":["Persons"],"summary":"List persons","description":"People in your talent pool, newest first, cursor-paginated. Requires the `persons:read` scope.","operationId":"listPersons","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["active","archived"],"default":"active"}},{"name":"email","in":"query","schema":{"type":"string"},"description":"Exact match"},{"name":"externalId","in":"query","schema":{"type":"string"},"description":"Exact match on your own identifier"},{"name":"assessmentStatus","in":"query","schema":{"type":"string","enum":["not_started","in_progress","completed"]}},{"name":"updatedAfter","in":"query","schema":{"type":"string","format":"date-time"},"description":"Only persons changed after this moment — for incremental syncs"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Cursor from the previous page"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"A page of persons","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"Stable person id; use in all person endpoints","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"email":{"type":"string"},"firstName":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastName":{"anyOf":[{"type":"string"},{"type":"null"}]},"externalId":{"description":"Your own system's identifier (per organization)","anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["active","archived"]},"joinedVia":{"description":"How the person entered your pool, e.g. api, invitation_link, invitation_personal","type":"string"},"sharedExistingProfile":{"description":"Whether the person consented to sharing results from assessments taken before joining","type":"boolean"},"assessment":{"type":"object","properties":{"status":{"type":"string","enum":["not_started","in_progress","completed"]},"completedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"count":{"description":"Number of completed assessments","type":"number"}},"required":["status","completedAt","count"],"additionalProperties":false},"memberSince":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"archivedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]}},"required":["id","email","firstName","lastName","externalId","status","joinedVia","sharedExistingProfile","assessment","memberSince","updatedAt","archivedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"description":"Opaque cursor for the next page; pass as ?cursor=","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["hasMore","nextCursor"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"Invalid filter or cursor","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human-readable error message (English)","type":"string"},"code":{"description":"Stable machine-readable error code, e.g. person_limit_reached","type":"string"},"details":{"description":"Optional structured context"}},"required":["error","code"],"additionalProperties":false}}}},"401":{"description":"Missing, malformed, revoked or expired API key","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human-readable error message (English)","type":"string"},"code":{"description":"Stable machine-readable error code, e.g. person_limit_reached","type":"string"},"details":{"description":"Optional structured context"}},"required":["error","code"],"additionalProperties":false}}}},"403":{"description":"Plan without API access (plan_upgrade_required), inactive subscription for writes (subscription_inactive), or missing scope (insufficient_scope)","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human-readable error message (English)","type":"string"},"code":{"description":"Stable machine-readable error code, e.g. person_limit_reached","type":"string"},"details":{"description":"Optional structured context"}},"required":["error","code"],"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded; see Retry-After and X-RateLimit-* headers","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human-readable error message (English)","type":"string"},"code":{"description":"Stable machine-readable error code, e.g. person_limit_reached","type":"string"},"details":{"description":"Optional structured context"}},"required":["error","code"],"additionalProperties":false}}}}}}}}}
```

## Import a person

> Creates or reactivates a person in your talent pool (ATS sync). The person counts toward your plan's person limit immediately. Idempotent on email: an already-active member returns 200 with \`X-Existing-Resource: true\`. Optionally creates an assessment invitation in the same call via the nested \`invitation\` object. Supports the \`Idempotency-Key\` header. Requires the \`persons:write\` scope.

```json
{"openapi":"3.1.0","info":{"title":"TalentLead API","version":"1.0.0"},"tags":[{"name":"Persons","description":"People in your talent pool"}],"servers":[{"url":"https://assessment.talentlead.nl","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key (tl_live_...)","description":"API key from the TalentLead dashboard (Organisatie → API)."}}},"paths":{"/api/v1/persons":{"post":{"tags":["Persons"],"summary":"Import a person","description":"Creates or reactivates a person in your talent pool (ATS sync). The person counts toward your plan's person limit immediately. Idempotent on email: an already-active member returns 200 with `X-Existing-Resource: true`. Optionally creates an assessment invitation in the same call via the nested `invitation` object. Supports the `Idempotency-Key` header. Requires the `persons:write` scope.","operationId":"importPerson","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"firstName":{"type":"string","minLength":1,"maxLength":100},"lastName":{"type":"string","minLength":1,"maxLength":100},"externalId":{"type":"string","minLength":1,"maxLength":255},"invitation":{"description":"Create an assessment invitation in the same call","type":"object","properties":{"create":{"type":"boolean","const":true},"sendEmail":{"description":"true: TalentLead sends the invitation email; false: you send the returned url yourself","type":"boolean"},"expiresInDays":{"type":"integer","minimum":1,"maximum":90}},"required":["create","sendEmail"]}},"required":["email"]}}}},"responses":{"200":{"description":"Person was already an active member (X-Existing-Resource: true)","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"description":"Stable person id; use in all person endpoints","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"email":{"type":"string"},"firstName":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastName":{"anyOf":[{"type":"string"},{"type":"null"}]},"externalId":{"description":"Your own system's identifier (per organization)","anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["active","archived"]},"joinedVia":{"description":"How the person entered your pool, e.g. api, invitation_link, invitation_personal","type":"string"},"sharedExistingProfile":{"description":"Whether the person consented to sharing results from assessments taken before joining","type":"boolean"},"assessment":{"type":"object","properties":{"status":{"type":"string","enum":["not_started","in_progress","completed"]},"completedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"count":{"description":"Number of completed assessments","type":"number"}},"required":["status","completedAt","count"],"additionalProperties":false},"memberSince":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"archivedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"invitation":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"email":{"type":"string"},"firstName":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastName":{"anyOf":[{"type":"string"},{"type":"null"}]},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}]},"personId":{"description":"Linked person; set at creation when known, otherwise at accept","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"status":{"type":"string","enum":["pending","accepted","expired","revoked"]},"url":{"description":"Unique invitation link; send this yourself when sendEmail was false","type":"string"},"emailSentAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"acceptedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"revokedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","email","firstName","lastName","externalId","personId","status","url","emailSentAt","expiresAt","acceptedAt","revokedAt","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["id","email","firstName","lastName","externalId","status","joinedVia","sharedExistingProfile","assessment","memberSince","updatedAt","archivedAt","invitation"],"additionalProperties":false}}}},"201":{"description":"Person imported; invitation included when requested","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"description":"Stable person id; use in all person endpoints","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"email":{"type":"string"},"firstName":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastName":{"anyOf":[{"type":"string"},{"type":"null"}]},"externalId":{"description":"Your own system's identifier (per organization)","anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["active","archived"]},"joinedVia":{"description":"How the person entered your pool, e.g. api, invitation_link, invitation_personal","type":"string"},"sharedExistingProfile":{"description":"Whether the person consented to sharing results from assessments taken before joining","type":"boolean"},"assessment":{"type":"object","properties":{"status":{"type":"string","enum":["not_started","in_progress","completed"]},"completedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"count":{"description":"Number of completed assessments","type":"number"}},"required":["status","completedAt","count"],"additionalProperties":false},"memberSince":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"archivedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"invitation":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"email":{"type":"string"},"firstName":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastName":{"anyOf":[{"type":"string"},{"type":"null"}]},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}]},"personId":{"description":"Linked person; set at creation when known, otherwise at accept","anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"status":{"type":"string","enum":["pending","accepted","expired","revoked"]},"url":{"description":"Unique invitation link; send this yourself when sendEmail was false","type":"string"},"emailSentAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"acceptedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"revokedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","email","firstName","lastName","externalId","personId","status","url","emailSentAt","expiresAt","acceptedAt","revokedAt","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["id","email","firstName","lastName","externalId","status","joinedVia","sharedExistingProfile","assessment","memberSince","updatedAt","archivedAt","invitation"],"additionalProperties":false}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human-readable error message (English)","type":"string"},"code":{"description":"Stable machine-readable error code, e.g. person_limit_reached","type":"string"},"details":{"description":"Optional structured context"}},"required":["error","code"],"additionalProperties":false}}}},"401":{"description":"Missing, malformed, revoked or expired API key","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human-readable error message (English)","type":"string"},"code":{"description":"Stable machine-readable error code, e.g. person_limit_reached","type":"string"},"details":{"description":"Optional structured context"}},"required":["error","code"],"additionalProperties":false}}}},"403":{"description":"Plan without API access (plan_upgrade_required), inactive subscription for writes (subscription_inactive), or missing scope (insufficient_scope)","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human-readable error message (English)","type":"string"},"code":{"description":"Stable machine-readable error code, e.g. person_limit_reached","type":"string"},"details":{"description":"Optional structured context"}},"required":["error","code"],"additionalProperties":false}}}},"409":{"description":"Person limit reached (person_limit_reached), person deactivated by an administrator (person_deactivated), or Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human-readable error message (English)","type":"string"},"code":{"description":"Stable machine-readable error code, e.g. person_limit_reached","type":"string"},"details":{"description":"Optional structured context"}},"required":["error","code"],"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded; see Retry-After and X-RateLimit-* headers","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human-readable error message (English)","type":"string"},"code":{"description":"Stable machine-readable error code, e.g. person_limit_reached","type":"string"},"details":{"description":"Optional structured context"}},"required":["error","code"],"additionalProperties":false}}}}}}}}}
```

## GET /api/v1/persons/{id}

> Get a person

```json
{"openapi":"3.1.0","info":{"title":"TalentLead API","version":"1.0.0"},"tags":[{"name":"Persons","description":"People in your talent pool"}],"servers":[{"url":"https://assessment.talentlead.nl","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key (tl_live_...)","description":"API key from the TalentLead dashboard (Organisatie → API)."}}},"paths":{"/api/v1/persons/{id}":{"get":{"tags":["Persons"],"summary":"Get a person","operationId":"getPerson","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The person","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"description":"Stable person id; use in all person endpoints","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"email":{"type":"string"},"firstName":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastName":{"anyOf":[{"type":"string"},{"type":"null"}]},"externalId":{"description":"Your own system's identifier (per organization)","anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["active","archived"]},"joinedVia":{"description":"How the person entered your pool, e.g. api, invitation_link, invitation_personal","type":"string"},"sharedExistingProfile":{"description":"Whether the person consented to sharing results from assessments taken before joining","type":"boolean"},"assessment":{"type":"object","properties":{"status":{"type":"string","enum":["not_started","in_progress","completed"]},"completedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"count":{"description":"Number of completed assessments","type":"number"}},"required":["status","completedAt","count"],"additionalProperties":false},"memberSince":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"archivedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]}},"required":["id","email","firstName","lastName","externalId","status","joinedVia","sharedExistingProfile","assessment","memberSince","updatedAt","archivedAt"],"additionalProperties":false}}}},"401":{"description":"Missing, malformed, revoked or expired API key","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human-readable error message (English)","type":"string"},"code":{"description":"Stable machine-readable error code, e.g. person_limit_reached","type":"string"},"details":{"description":"Optional structured context"}},"required":["error","code"],"additionalProperties":false}}}},"403":{"description":"Plan without API access (plan_upgrade_required), inactive subscription for writes (subscription_inactive), or missing scope (insufficient_scope)","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human-readable error message (English)","type":"string"},"code":{"description":"Stable machine-readable error code, e.g. person_limit_reached","type":"string"},"details":{"description":"Optional structured context"}},"required":["error","code"],"additionalProperties":false}}}},"404":{"description":"Not a member of your organization","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human-readable error message (English)","type":"string"},"code":{"description":"Stable machine-readable error code, e.g. person_limit_reached","type":"string"},"details":{"description":"Optional structured context"}},"required":["error","code"],"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded; see Retry-After and X-RateLimit-* headers","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human-readable error message (English)","type":"string"},"code":{"description":"Stable machine-readable error code, e.g. person_limit_reached","type":"string"},"details":{"description":"Optional structured context"}},"required":["error","code"],"additionalProperties":false}}}}}}}}}
```

## Update a person

> \`externalId\` is always updatable. Names can only be filled in while empty — once the person has claimed their profile, they own it (409 conflict otherwise). Requires the \`persons:write\` scope.

```json
{"openapi":"3.1.0","info":{"title":"TalentLead API","version":"1.0.0"},"tags":[{"name":"Persons","description":"People in your talent pool"}],"servers":[{"url":"https://assessment.talentlead.nl","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key (tl_live_...)","description":"API key from the TalentLead dashboard (Organisatie → API)."}}},"paths":{"/api/v1/persons/{id}":{"patch":{"tags":["Persons"],"summary":"Update a person","description":"`externalId` is always updatable. Names can only be filled in while empty — once the person has claimed their profile, they own it (409 conflict otherwise). Requires the `persons:write` scope.","operationId":"updatePerson","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"externalId":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"null"}]},"firstName":{"type":"string","minLength":1,"maxLength":100},"lastName":{"type":"string","minLength":1,"maxLength":100}}}}}},"responses":{"200":{"description":"The updated person","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"description":"Stable person id; use in all person endpoints","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"email":{"type":"string"},"firstName":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastName":{"anyOf":[{"type":"string"},{"type":"null"}]},"externalId":{"description":"Your own system's identifier (per organization)","anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["active","archived"]},"joinedVia":{"description":"How the person entered your pool, e.g. api, invitation_link, invitation_personal","type":"string"},"sharedExistingProfile":{"description":"Whether the person consented to sharing results from assessments taken before joining","type":"boolean"},"assessment":{"type":"object","properties":{"status":{"type":"string","enum":["not_started","in_progress","completed"]},"completedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"count":{"description":"Number of completed assessments","type":"number"}},"required":["status","completedAt","count"],"additionalProperties":false},"memberSince":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"archivedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]}},"required":["id","email","firstName","lastName","externalId","status","joinedVia","sharedExistingProfile","assessment","memberSince","updatedAt","archivedAt"],"additionalProperties":false}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human-readable error message (English)","type":"string"},"code":{"description":"Stable machine-readable error code, e.g. person_limit_reached","type":"string"},"details":{"description":"Optional structured context"}},"required":["error","code"],"additionalProperties":false}}}},"401":{"description":"Missing, malformed, revoked or expired API key","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human-readable error message (English)","type":"string"},"code":{"description":"Stable machine-readable error code, e.g. person_limit_reached","type":"string"},"details":{"description":"Optional structured context"}},"required":["error","code"],"additionalProperties":false}}}},"403":{"description":"Plan without API access (plan_upgrade_required), inactive subscription for writes (subscription_inactive), or missing scope (insufficient_scope)","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human-readable error message (English)","type":"string"},"code":{"description":"Stable machine-readable error code, e.g. person_limit_reached","type":"string"},"details":{"description":"Optional structured context"}},"required":["error","code"],"additionalProperties":false}}}},"404":{"description":"Not a member of your organization","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human-readable error message (English)","type":"string"},"code":{"description":"Stable machine-readable error code, e.g. person_limit_reached","type":"string"},"details":{"description":"Optional structured context"}},"required":["error","code"],"additionalProperties":false}}}},"409":{"description":"Person already has a name","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human-readable error message (English)","type":"string"},"code":{"description":"Stable machine-readable error code, e.g. person_limit_reached","type":"string"},"details":{"description":"Optional structured context"}},"required":["error","code"],"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded; see Retry-After and X-RateLimit-* headers","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human-readable error message (English)","type":"string"},"code":{"description":"Stable machine-readable error code, e.g. person_limit_reached","type":"string"},"details":{"description":"Optional structured context"}},"required":["error","code"],"additionalProperties":false}}}}}}}}}
```

## Archive a person

> Archives the person (they disappear from your talent pool and free up a plan seat). Their data is retained; re-importing via POST /persons reactivates them. Requires the \`persons:write\` scope.

```json
{"openapi":"3.1.0","info":{"title":"TalentLead API","version":"1.0.0"},"tags":[{"name":"Persons","description":"People in your talent pool"}],"servers":[{"url":"https://assessment.talentlead.nl","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key (tl_live_...)","description":"API key from the TalentLead dashboard (Organisatie → API)."}}},"paths":{"/api/v1/persons/{id}":{"delete":{"tags":["Persons"],"summary":"Archive a person","description":"Archives the person (they disappear from your talent pool and free up a plan seat). Their data is retained; re-importing via POST /persons reactivates them. Requires the `persons:write` scope.","operationId":"archivePerson","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The archived person","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"description":"Stable person id; use in all person endpoints","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"email":{"type":"string"},"firstName":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastName":{"anyOf":[{"type":"string"},{"type":"null"}]},"externalId":{"description":"Your own system's identifier (per organization)","anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["active","archived"]},"joinedVia":{"description":"How the person entered your pool, e.g. api, invitation_link, invitation_personal","type":"string"},"sharedExistingProfile":{"description":"Whether the person consented to sharing results from assessments taken before joining","type":"boolean"},"assessment":{"type":"object","properties":{"status":{"type":"string","enum":["not_started","in_progress","completed"]},"completedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"count":{"description":"Number of completed assessments","type":"number"}},"required":["status","completedAt","count"],"additionalProperties":false},"memberSince":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"archivedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]}},"required":["id","email","firstName","lastName","externalId","status","joinedVia","sharedExistingProfile","assessment","memberSince","updatedAt","archivedAt"],"additionalProperties":false}}}},"401":{"description":"Missing, malformed, revoked or expired API key","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human-readable error message (English)","type":"string"},"code":{"description":"Stable machine-readable error code, e.g. person_limit_reached","type":"string"},"details":{"description":"Optional structured context"}},"required":["error","code"],"additionalProperties":false}}}},"403":{"description":"Plan without API access (plan_upgrade_required), inactive subscription for writes (subscription_inactive), or missing scope (insufficient_scope)","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human-readable error message (English)","type":"string"},"code":{"description":"Stable machine-readable error code, e.g. person_limit_reached","type":"string"},"details":{"description":"Optional structured context"}},"required":["error","code"],"additionalProperties":false}}}},"404":{"description":"No active person with this id","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human-readable error message (English)","type":"string"},"code":{"description":"Stable machine-readable error code, e.g. person_limit_reached","type":"string"},"details":{"description":"Optional structured context"}},"required":["error","code"],"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded; see Retry-After and X-RateLimit-* headers","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"description":"Human-readable error message (English)","type":"string"},"code":{"description":"Stable machine-readable error code, e.g. person_limit_reached","type":"string"},"details":{"description":"Optional structured context"}},"required":["error","code"],"additionalProperties":false}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://helpcenter.talentlead.nl/talent-assessment/api/referentie/personen.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.