> 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/resultaten-and-matching.md).

# Resultaten & matching

Assessmentresultaten, PDF-rapporten, competentieprofielen en matches. Vergelijkende endpoints geven bewust alleen het geaggregeerde matchpercentage en de categorie terug.

## Get a person's assessment results

> Cumulative results over all completed assessments: motivation-need scores per axis, competency aptitudes with band, and the AI personality description. Requires the \`results:read\` scope.

```json
{"openapi":"3.1.0","info":{"title":"TalentLead API","version":"1.0.0"},"tags":[{"name":"Results","description":"Assessment results, matches and reports"}],"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}/results":{"get":{"tags":["Results"],"summary":"Get a person's assessment results","description":"Cumulative results over all completed assessments: motivation-need scores per axis, competency aptitudes with band, and the AI personality description. Requires the `results:read` scope.","operationId":"getPersonResults","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Results, or hasResults: false when none yet","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"personId":{"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)$"},"hasResults":{"description":"false when the person has no completed assessment yet","type":"boolean"},"totals":{"anyOf":[{"type":"object","properties":{"assessments":{"type":"number"},"responses":{"type":"number"}},"required":["assessments","responses"],"additionalProperties":false},{"type":"null"}]},"motivationAxes":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"needs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"definition":{"type":"string"},"isAnchor":{"type":"boolean"},"score":{"description":"0-1, cumulative over all completed assessments","type":"number"},"exposure":{"type":"number"}},"required":["name","definition","isAnchor","score","exposure"],"additionalProperties":false}}},"required":["code","name","needs"],"additionalProperties":false}},{"type":"null"}]},"competencies":{"anyOf":[{"type":"object","properties":{"modelName":{"type":"string"},"mappingName":{"type":"string"},"scores":{"type":"array","items":{"type":"object","properties":{"competencyId":{"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)$"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"score":{"description":"Aptitude 0-1 (0.5 = neutral). Never compare between persons.","type":"number"},"band":{"description":"Aptitude band, symmetric around the neutral midpoint 0.5. high = strong natural aptitude (score >= 0.65), moderate = natural aptitude (0.55-0.65), some = neutral (0.45-0.55), limited = naturally costs more energy (< 0.45). Bands describe motivational support, not skill.","type":"string","enum":["limited","some","moderate","high"]}},"required":["competencyId","name","description","score","band"],"additionalProperties":false}}},"required":["modelName","mappingName","scores"],"additionalProperties":false},{"type":"null"}]},"personality":{"anyOf":[{"type":"object","properties":{"markdown":{"type":"string"},"generatedAt":{"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":["markdown","generatedAt"],"additionalProperties":false},{"type":"null"}]},"signal":{"description":"Measurement-quality indicator (Dutch UI term: meetkwaliteit). Reflects how consistent and differentiated the answer pattern was, not the person's ability or suitability. groen = high quality, oranje = interpret with some caution, rood = treat results as indicative (an extra session improves reliability). Null when not computable (e.g. imported sessions without response-level data).","anyOf":[{"type":"object","properties":{"score":{"description":"Signal strength 0-1, weighted across all counted sessions","type":"number"},"band":{"type":"string","enum":["groen","oranje","rood"]}},"required":["score","band"],"additionalProperties":false},{"type":"null"}]},"reportUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["personId","hasResults","totals","motivationAxes","competencies","personality","signal","reportUrl"],"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 an active 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}}}}}}}}}
```

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

> Download the person's PDF report

```json
{"openapi":"3.1.0","info":{"title":"TalentLead API","version":"1.0.0"},"tags":[{"name":"Results","description":"Assessment results, matches and reports"}],"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}/report":{"get":{"tags":["Results"],"summary":"Download the person's PDF report","operationId":"getPersonReport","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The assessment report as application/pdf"},"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 an active member, or no completed assessment yet","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}}}}}}}}}
```

## Match a person against all profiles

> How this person matches each competency profile, sorted best-first. Intra-individual, so the full per-competency breakdown is included. Requires the \`results:read\` scope.

```json
{"openapi":"3.1.0","info":{"title":"TalentLead API","version":"1.0.0"},"tags":[{"name":"Results","description":"Assessment results, matches and reports"}],"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}/matches":{"get":{"tags":["Results"],"summary":"Match a person against all profiles","description":"How this person matches each competency profile, sorted best-first. Intra-individual, so the full per-competency breakdown is included. Requires the `results:read` scope.","operationId":"getPersonMatches","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Matches per profile","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"personId":{"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)$"},"hasResults":{"type":"boolean"},"matches":{"type":"array","items":{"type":"object","properties":{"profileId":{"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)$"},"title":{"type":"string"},"matchPercentage":{"description":"Aggregated match 0-100; comparable across profiles for this person","type":"number"},"category":{"type":"string","enum":["low","moderate","high"]},"coverage":{"type":"number"},"confidence":{"type":"number"},"breakdown":{"type":"array","items":{"type":"object","properties":{"competencyId":{"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)$"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"weight":{"type":"number"},"aptitudeScore":{"description":"0-1; null when the person has no score for this competency","anyOf":[{"type":"number"},{"type":"null"}]}},"required":["competencyId","name","weight","aptitudeScore"],"additionalProperties":false}}},"required":["profileId","title","matchPercentage","category","coverage","confidence","breakdown"],"additionalProperties":false}}},"required":["personId","hasResults","matches"],"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 an active 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}}}}}}}}}
```

## GET /api/v1/profiles

> List competency profiles

```json
{"openapi":"3.1.0","info":{"title":"TalentLead API","version":"1.0.0"},"tags":[{"name":"Profiles","description":"Competency profiles"}],"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/profiles":{"get":{"tags":["Profiles"],"summary":"List competency profiles","operationId":"listProfiles","responses":{"200":{"description":"All profiles of your organization","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"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)$"},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"competencies":{"type":"array","items":{"type":"object","properties":{"competencyId":{"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)$"},"name":{"type":"string"},"weight":{"type":"number"}},"required":["competencyId","name","weight"],"additionalProperties":false}},"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","title","description","competencies","createdAt","updatedAt"],"additionalProperties":false}}},"required":["data"],"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}}}}}}}}}
```

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

> Get a competency profile

```json
{"openapi":"3.1.0","info":{"title":"TalentLead API","version":"1.0.0"},"tags":[{"name":"Profiles","description":"Competency profiles"}],"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/profiles/{id}":{"get":{"tags":["Profiles"],"summary":"Get a competency profile","operationId":"getProfile","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The profile","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","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)$"},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"competencies":{"type":"array","items":{"type":"object","properties":{"competencyId":{"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)$"},"name":{"type":"string"},"weight":{"type":"number"}},"required":["competencyId","name","weight"],"additionalProperties":false}},"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","title","description","competencies","createdAt","updatedAt"],"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":"Profile not found in 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}}}}}}}}}
```

## Rank your talent pool against a profile

> All active persons ranked by aggregated match percentage. Deliberately excludes per-competency scores: ipsative scores are not comparable between persons. Requires the \`results:read\` scope.

```json
{"openapi":"3.1.0","info":{"title":"TalentLead API","version":"1.0.0"},"tags":[{"name":"Results","description":"Assessment results, matches and reports"}],"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/profiles/{id}/matches":{"get":{"tags":["Results"],"summary":"Rank your talent pool against a profile","description":"All active persons ranked by aggregated match percentage. Deliberately excludes per-competency scores: ipsative scores are not comparable between persons. Requires the `results:read` scope.","operationId":"getProfileMatches","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Ranked matches plus persons without results","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"profileId":{"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)$"},"matches":{"type":"array","items":{"type":"object","properties":{"personId":{"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)$"},"firstName":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastName":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"type":"string"},"matchPercentage":{"description":"Aggregated match 0-100 — the only score that may be compared between persons","type":"number"},"category":{"type":"string","enum":["low","moderate","high"]},"lowCoverage":{"description":"true when the match is based on limited data","type":"boolean"},"lastAssessmentAt":{"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":["personId","firstName","lastName","email","matchPercentage","category","lowCoverage","lastAssessmentAt"],"additionalProperties":false}},"personsWithoutResults":{"type":"array","items":{"type":"object","properties":{"personId":{"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)$"},"firstName":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastName":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"type":"string"},"assessmentStatus":{"type":"string","enum":["not_started","in_progress"]}},"required":["personId","firstName","lastName","email","assessmentStatus"],"additionalProperties":false}}},"required":["profileId","matches","personsWithoutResults"],"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":"Profile not found in 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}}}}}}}}}
```


---

# 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/resultaten-and-matching.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.