---
title: "List Matched Candidates for Position"
method: GET
path: "/api/v2/core/positions/{positionId}/matched-candidates"
tags: ["Position"]
---

# List Matched Candidates for Position

`GET /api/v2/core/positions/{positionId}/matched-candidates`

## Request

- Base URL: `https://apiv2.eightfold.ai`
- URL: `https://apiv2.eightfold.ai/api/v2/core/positions/{positionId}/matched-candidates`
- Auth: none declared. Required headers: `Authorization`
- TypeScript: <https://skmtc.dev/eightfold/apis/api-server-v2-service-service/docs/api/v2/core/positions/:positionId/matched-candidates/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns all the matching candidates for a position based on the filter query params provided in the API request. NOTE: The output may differ from UI pages as those pages may use additional configs, that are configured separately. Top 1000 Leads can be requested using the leads query parameter.

## Path parameters

- `positionId` string, required

## Query parameters

- `start` integer
- `limit` integer
- `filterQuery` string
- `leads` string
- `validatedSkills` string
- `exclude` string
- `keyList` string

## Headers

- `Authorization` string, required

## Response `200`

OK

- object
  - `data` MatchingProfilesSchema[]
    - `missingSkills` string[], nullable: Position skills missing in candidate's profile
    - `skillScoreRelevance` number, float, nullable: Skill relevance score based on matching of job and candidate profile
    - `fullName` string, nullable: full name of the matching profile
    - `matchScore` number, float, nullable: match score of the candidate for a position, with range (0-5)
    - `atsEntityId` string, nullable: candidate ID from the connected ATS system
    - `profileId` string, nullable: unique identifier for profile
    - `candidateInsights` string[], nullable: indicates whether profile is employee, alumni, competitor or other.
    - `validatedSkills` string[], nullable: Position skills validated in candidate's profile
    - `titleScoreRelevance` number, float, nullable: Title relevance score based on matching of job and candidate profile
  - `meta` MetaSchema
    - `totalCount` integer, nullable
    - `pageTotalCount` integer, nullable
    - `pageStartIndex` integer, nullable

---

[API](https://skmtc.dev/eightfold/apis/api-server-v2-service-service.md) - [All operations](https://skmtc.dev/eightfold/apis/api-server-v2-service-service/llms.txt) - [OpenAPI document](https://skmtc.dev/eightfold/apis/api-server-v2-service-service/revisions/9a8b3a927e93?raw)