Get Job Matches
curl --request GET \
--url https://api.example.com/api/v1/companies/me/jobs/{jobId}/matchesimport requests
url = "https://api.example.com/api/v1/companies/me/jobs/{jobId}/matches"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/api/v1/companies/me/jobs/{jobId}/matches', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/companies/me/jobs/{jobId}/matches",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/companies/me/jobs/{jobId}/matches"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/companies/me/jobs/{jobId}/matches")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/companies/me/jobs/{jobId}/matches")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"matches": [
{
"id": "<string>",
"jobSeekerId": "<string>",
"jobSeekerName": "<string>",
"jobSeekerTitle": "<string>",
"availabilityStatus": {},
"location": "<string>",
"matchScore": 123,
"createdAt": "<string>"
}
],
"total": 123,
"page": 123,
"limit": 123,
"totalPages": 123
}Matching
Get Job Matches
Retrieve candidate matches for a specific job posting with filtering and pagination
GET
/
api
/
v1
/
companies
/
me
/
jobs
/
{jobId}
/
matches
Get Job Matches
curl --request GET \
--url https://api.example.com/api/v1/companies/me/jobs/{jobId}/matchesimport requests
url = "https://api.example.com/api/v1/companies/me/jobs/{jobId}/matches"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/api/v1/companies/me/jobs/{jobId}/matches', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/companies/me/jobs/{jobId}/matches",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/companies/me/jobs/{jobId}/matches"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/companies/me/jobs/{jobId}/matches")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/companies/me/jobs/{jobId}/matches")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"matches": [
{
"id": "<string>",
"jobSeekerId": "<string>",
"jobSeekerName": "<string>",
"jobSeekerTitle": "<string>",
"availabilityStatus": {},
"location": "<string>",
"matchScore": 123,
"createdAt": "<string>"
}
],
"total": 123,
"page": 123,
"limit": 123,
"totalPages": 123
}Endpoint
GET /api/v1/companies/me/jobs/{jobId}/matches
http://localhost:3000/api/v1
This endpoint requires authentication and Company role.
Authentication
Include the access token in the Authorization header:Authorization: Bearer YOUR_ACCESS_TOKEN
Path Parameters
string
required
The unique identifier of the job posting (UUID)
Query Parameters
number
Minimum match score threshold (0-100)
enum
Filter by candidate availability status. Options:
OPEN_TO_WORK, NOT_LOOKING,
PASSIVELY_LOOKINGnumber
default:"1"
Page number for pagination
number
default:"10"
Number of items per page
Response
Success Response (200 OK)
{
"success": true,
"data": {
"matches": [
{
"id": "113f4d3d-120f-4e21-8d7a-1d825d748566",
"jobSeekerId": "20000000-0000-4000-8000-000000000004",
"jobSeekerName": "Youssef Khaled",
"jobSeekerTitle": "DevOps Engineer",
"availabilityStatus": "OPEN_TO_WORK",
"location": "Riyadh, Saudi Arabia",
"matchScore": 70,
"createdAt": "2026-04-17T11:57:59.572Z"
},
{
"id": "5f9f22ba-2d03-4e8e-a721-2243424f74d5",
"jobSeekerId": "f35b1c20-b18e-4902-9461-23bb653ee5fa",
"jobSeekerName": "Amr Mubarak",
"jobSeekerTitle": "Software Engineer",
"availabilityStatus": "OPEN_TO_WORK",
"location": "Egypt",
"matchScore": 62.5,
"createdAt": "2026-04-17T11:57:59.572Z"
},
{
"id": "9b3fa2e4-2aea-49e4-bdde-e3abf3b0da3e",
"jobSeekerId": "20000000-0000-4000-8000-000000000003",
"jobSeekerName": "Sara Nabil",
"jobSeekerTitle": "Product Designer",
"availabilityStatus": "PASSIVELY_LOOKING",
"location": "Alexandria, Egypt",
"matchScore": 58.33,
"createdAt": "2026-04-17T11:57:59.572Z"
}
],
"total": 5,
"page": 1,
"limit": 10,
"totalPages": 1
},
"message": "Company job matches retrieved successfully",
"meta": {
"timestamp": "2026-04-23T20:00:00.000Z",
"path": "/companies/me/jobs/1dce277f-4d30-4576-a8be-c636f0e85b7a/matches",
"method": "GET"
}
}
Response Fields
array
List of candidate matches sorted by match score (highest first).
Show Match Properties
Show Match Properties
string
Unique match identifier (UUID).
string
Unique job seeker identifier (UUID).
string
Candidate’s full name.
string
Candidate’s current job title.
enum
Candidate’s availability status. -
OPEN_TO_WORK - Actively looking for opportunities -
NOT_LOOKING - Not currently looking - PASSIVELY_LOOKING - Open to opportunities but not
actively searchingstring
Candidate’s location.
number
Match score percentage (0-100). Higher scores indicate better compatibility with the job
requirements.
string
Match creation date (ISO 8601 format).
number
Total number of candidate matches available.
number
Current page number.
number
Number of items per page.
number
Total number of pages available.
Error Responses
401 Unauthorized
{
"success": false,
"error": {
"message": "Unauthorized",
"statusCode": 401,
"timestamp": "2026-04-23T20:00:00.000Z",
"path": "/companies/me/jobs/{jobId}/matches",
"method": "GET",
"details": "Unauthorized"
}
}
403 Forbidden
{
"success": false,
"error": {
"message": "Forbidden resource",
"statusCode": 403,
"timestamp": "2026-04-23T20:00:00.000Z",
"path": "/companies/me/jobs/{jobId}/matches",
"method": "GET",
"details": "Forbidden"
}
}
400 Bad Request - Validation Error
{
"success": false,
"error": {
"message": ["availabilityStatus must be a valid enum value"],
"statusCode": 400,
"timestamp": "2026-04-23T20:00:00.000Z",
"path": "/companies/me/jobs/{jobId}/matches",
"method": "GET",
"details": "Bad Request"
}
}
Notes
Match Score Calculation: Candidates are sorted by match score in descending order. Candidates
with higher scores appear first in the results, indicating better compatibility with the job
requirements.
Availability Filtering: Use the
availabilityStatus parameter to filter candidates based on
their availability. OPEN_TO_WORK candidates are actively looking and may respond faster to
outreach.Minimum Score Filtering: Use the
minScore parameter to filter out low-quality matches. For
example, ?minScore=60 will only return candidates with a match score of 60 or higher, showing
only highly compatible candidates.Job Ownership: You can only retrieve matches for jobs that belong to your company. Attempting
to access matches for jobs from other companies will result in a 404 error.