---
updatedAt: 2026-05-05T13:44:18.000Z
---

Fetch the complete documentation index at: https://apidocs.eightfold.ai/llms.txt. Use this file to discover all available pages before exploring further.

# List Matched Candidates for Position

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.

# OpenAPI definition

```json
{
  "servers": [
    {
      "url": "https://apiv2.{domain}.ai",
      "variables": {
        "domain": {
          "default": "eightfold",
          "enum": [
            "eightfold",
            "eightfold-eu",
            "eightfold-gov",
            "eightfold-ca",
            "eightfold-me",
            "eightfold-wu",
            "eightfold-ap"
          ]
        }
      }
    }
  ],
  "paths": {
    "/api/v2/core/positions/{positionId}/matched-candidates": {
      "get": {
        "description": "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.",
        "operationId": "list_profile_matched_candidates",
        "parameters": [
          {
            "description": "The secret key to access the api. It starts with the bearer token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Specifies the offset value to start for the page",
            "in": "query",
            "name": "start",
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "Specifies the number of entries to be returned for the page",
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "filter query using predefined filter arguments documented [here](https://apidocs.eightfold.ai/v2.0/docs#the-filterquery-parameter)",
            "in": "query",
            "name": "filterQuery",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Position ID",
            "in": "path",
            "name": "positionId",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Request leads profiles for this position, as shown on the pipeline page",
            "in": "query",
            "name": "leads",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Request validated and missing skills, as shown on the profile page matching insights",
            "in": "query",
            "name": "validatedSkills",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Exclude specific fields in the response. Possible values are the names of the top level fields present in corresponding API schema. To check API schema, expand the response section below.",
            "in": "query",
            "name": "exclude",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Allows selective control over the fields returned in the API response. If the keyList is empty, all fields will be returned. Possible values are the names of the top level fields present in corresponding API schema. To check API schema, expand the response section below.",
            "in": "query",
            "name": "keyList",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "$ref": "#/components/schemas/MatchingProfilesSchema"
                      },
                      "type": "array"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/MetaSchema"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "OK"
          }
        },
        "summary": "List Matched Candidates for Position",
        "tags": [
          "Position"
        ]
      }
    }
  },
  "info": {
    "title": "Api_server_v2_service Service",
    "version": "1.0.0"
  },
  "openapi": "3.0.2",
  "components": {
    "schemas": {
      "MatchingProfilesSchema": {
        "type": "object",
        "properties": {
          "missingSkills": {
            "type": "array",
            "readOnly": true,
            "nullable": true,
            "description": "Position skills missing in candidate's profile",
            "items": {
              "type": "string"
            }
          },
          "skillScoreRelevance": {
            "type": "number",
            "format": "float",
            "readOnly": true,
            "nullable": true,
            "description": "Skill relevance score based on matching of job and candidate profile"
          },
          "fullName": {
            "type": "string",
            "readOnly": true,
            "nullable": true,
            "description": "full name of the matching profile"
          },
          "matchScore": {
            "type": "number",
            "format": "float",
            "readOnly": true,
            "nullable": true,
            "description": "match score of the candidate for a position, with range (0-5)"
          },
          "atsEntityId": {
            "type": "string",
            "readOnly": true,
            "nullable": true,
            "description": "candidate ID from the connected ATS system"
          },
          "profileId": {
            "type": "string",
            "readOnly": true,
            "nullable": true,
            "description": "unique identifier for profile"
          },
          "candidateInsights": {
            "type": "array",
            "readOnly": true,
            "nullable": true,
            "description": "indicates whether profile is employee, alumni, competitor or other.",
            "items": {
              "type": "string"
            }
          },
          "validatedSkills": {
            "type": "array",
            "readOnly": true,
            "nullable": true,
            "description": "Position skills validated in candidate's profile",
            "items": {
              "type": "string"
            }
          },
          "titleScoreRelevance": {
            "type": "number",
            "format": "float",
            "readOnly": true,
            "nullable": true,
            "description": "Title relevance score based on matching of job and candidate profile"
          }
        }
      },
      "MetaSchema": {
        "type": "object",
        "properties": {
          "totalCount": {
            "type": "integer",
            "format": "int32",
            "readOnly": true,
            "nullable": true,
            "description": ""
          },
          "pageTotalCount": {
            "type": "integer",
            "format": "int32",
            "readOnly": true,
            "nullable": true,
            "description": ""
          },
          "pageStartIndex": {
            "type": "integer",
            "format": "int32",
            "readOnly": true,
            "nullable": true,
            "description": ""
          }
        }
      }
    }
  }
}
```