GET Candidates Invited for an Assessment V2

This API retrieves candidates invited to an assessment, including assessment metadata and detailed report data for candidates who have completed it. Candidates can be filtered by their current invitation status.

Request URL

GET /assessments/invited/v2/<assessment_id>

Warning

Make sure to add your API key in the request header.

Path Parameters

Parameter	Type	Description
assessment_id	integer	Assessment ID for which invited candidates are to be fetched.

Query Parameters

Parameter	Type	Description
status	string	Optional. Filters candidates by Pending, Started, Completed, Expired, or Revoked.
page	integer	Optional. Page number, starting at 1. Defaults to 1.
limit	integer	Optional. Candidates per page. Defaults to 25; values must be between 1 and 200.

Response

The response contains assessment details and the invited candidates. A report object is included only when report data is available for a completed candidate. Report links expire after seven days.

{
    "assessment_id": 123,
    "assessment_name": "Software Engineer Assessment",
    "cut_off": 60,
    "total_invited_candidates": 54,
    "candidates": [
        {
            "candidate_id": 456,
            "email": "[email protected]",
            "name": "Candidate Name",
            "report_id": 789,
            "invite_status": "Completed",
            "report": {
                "candidate_id": 456,
                "email": "[email protected]",
                "name": "Candidate Name",
                "report_id": 789,
                "overall_percentage": 82.5,
                "integrity": "Clear",
                "qualification": "Qualified",
                "report_link": "https://example.com/signed-report-link",
                "completed_date": "2026-07-13T10:30:00",
                "sections": [
                    {
                        "section_name": "Programming",
                        "percentage": 85.0,
                        "skills": [
                            {
                                "skill": "Python",
                                "percentage": 90.0
                            }
                        ]
                    }
                ]
            }
        },
        {
            "candidate_id": 457,
            "email": "[email protected]",
            "name": "Pending Candidate",
            "report_id": 790,
            "invite_status": "Pending"
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 25,
        "total": 40,
        "total_pages": 2,
        "has_next": true,
        "has_previous": false
    }
}

total_invited_candidates is the count of all invitations before applying the optional status filter. pagination.total is the count after filtering. The integrity field is a label: Clear, Review Needed, or Action Required.

If no candidates match the request, the API returns assessment details, an empty candidates array, pagination metadata, and the message No candidates found.

Response Status Codes

Status Code	Description
200	Candidates were retrieved successfully, including an empty result.
400	The supplied status, page, or limit value is invalid.
404	The assessment was not found.
500	Candidate information could not be fetched.