Test Takers
List Test Takers
Make a GET request to /test-takers to retrieve a list of Test Takers in your account. By default, results are ordered by most recently created and limited to the 50 most recent test takers.
Pass optional query parameters to narrow results. Use team_id to scope the list to one team (similar to working in a selected team in JOFI). Use custom_id or email to search within the account (or within a team if you also pass team_id). API callers often filter by custom_id to group candidates by job requisition number or participations by group number, for example.
GET /test-takers?team_id=100
GET /test-takers?custom_id=ABC123
GET /test-takers?email=linda.sample@
| Query parameter | Required | Description |
|---|---|---|
team_id | No | Scope results to a single team. Exact match. Must belong to your account (use the Teams API route to list valid IDs). Returns 400 Bad Request with team_id not found if the team is not in your account. |
custom_id | No | Filter by invitation custom_id. Partial match, case-insensitive. Max 50 characters. |
email | No | Filter by participant email address. Partial match, case-insensitive. Max 255 characters. |
note
Pagination and the ability to request the next set of items is coming soon. Use has_more to determine if additional matching records exist beyond the current response. Requests return up to 50 items by default (including when only team_id is provided). Requests that include custom_id and/or email return up to 150 items.
GET /test-takers
{
"mode": "live",
"object": "list",
"total_count": 106,
"has_more": true,
"data": [
{
"object": "test_taker_list_item",
"id": 12345,
"first_name": "Linda",
"last_name": "Sample",
"email": "linda.sample@jofiscore.com",
"invitation_created_at": "2026-12-11T22:23:05.312696+00:00",
"invitation_id": 12345,
"custom_id": "ABC123",
"person_id": "1bb2141c-4100-4b21-9cd2-a998b76cf736",
"career_navigation_profile_id": "CNP1234567890",
"assessment_url": "https://www.jofiscore.com/welcome/69608c33-1425-4123-9c49-22c5d9d7838c",
"career_navigation_url": "https://www.careernavigation.org?c=CNP1234567890",
"scorecard_url": "https://www.jofiscore.com/team/100/test-takers/12345/scorecard",
"job_fit_summary_url": "https://www.jofiscore.com/test-takers/CNP1234567890/job-fit?r=jfs&zones=1_5",
"career_options_spotlight_url": "https://www.jofiscore.com/test-takers/CNP1234567890/job-fit?r=cor&zones=1_5",
"team": {
"id": 100,
"display_name": "Recruiting"
},
"account": {
"id": 200,
"display_name": "Example Company Inc"
}
},
{
"object": "test_taker_list_item",
"id": 23456,
"first_name": "Oliver",
"last_name": "Sample",
"email": "oliver.sample@jofiscore.com",
"invitation_created_at": "2026-12-03T05:04:04.673371+00:00",
"invitation_id": 78901,
"custom_id": "ABC456",
"person_id": "2bb2141c-4100-4b21-9cd2-a998b76cf737",
"career_navigation_profile_id": null,
"assessment_url": "https://www.jofiscore.com/welcome/1b9617a2-0297-47c7-930b-8fb8e8d4e4b7",
"career_navigation_url": null,
"scorecard_url": "https://www.jofiscore.com/team/100/test-takers/23456/scorecard",
"job_fit_summary_url": null,
"career_options_spotlight_url": null,
"team": {
"id": 100,
"display_name": "Recruiting"
},
"account": {
"id": 200,
"display_name": "Example Company Inc"
}
},
// truncated for brevity
{
"object": "test_taker_list_item",
"id": 34567,
"first_name": "Charlotte",
"last_name": "Sample",
"email": "charlotte.sample@jofiscore.com",
"invitation_created_at": "2026-08-04T19:06:53.921424+00:00",
"invitation_id": 89012,
"custom_id": "ABC456",
"person_id": "3bb2141c-4100-4b21-9cd2-a998b76cf738",
"career_navigation_profile_id": "CNP2345678901",
"assessment_url": "https://www.jofiscore.com/welcome/f6b8646a-6f40-4df0-99a7-94aae3291d45",
"career_navigation_url": "https://www.careernavigation.org?c=CNP2345678901",
"scorecard_url": "https://www.jofiscore.com/team/100/test-takers/34567/scorecard",
"job_fit_summary_url": "https://www.jofiscore.com/test-takers/CNP2345678901/job-fit?r=jfs&zones=1_5",
"career_options_spotlight_url": "https://www.jofiscore.com/test-takers/CNP2345678901/job-fit?r=cor&zones=1_5",
"team": {
"id": 100,
"display_name": "Recruiting"
},
"account": {
"id": 200,
"display_name": "Example Company Inc"
}
},
{
"object": "test_taker_list_item",
"id": 45678,
"first_name": "Lorna",
"last_name": "Montey",
"email": "qa+testuser@jofiscore.com",
"invitation_created_at": "2026-07-21T02:22:35.502828+00:00",
"invitation_id": 90123,
"custom_id": "ABC789",
"person_id": "4bb2141c-4100-4b21-9cd2-a998b76cf739",
"career_navigation_profile_id": "CNP3456789012",
"assessment_url": "https://www.jofiscore.com/welcome/ce7e51b6-7370-41cf-93ef-8072628c2b6d",
"career_navigation_url": "https://www.careernavigation.org?c=CNP3456789012",
"scorecard_url": "https://www.jofiscore.com/team/100/test-takers/45678/scorecard",
"job_fit_summary_url": "https://www.jofiscore.com/test-takers/CNP3456789012/job-fit?r=jfs&zones=1_5",
"career_options_spotlight_url": "https://www.jofiscore.com/test-takers/CNP3456789012/job-fit?r=cor&zones=1_5",
"team": {
"id": 100,
"display_name": "Recruiting"
},
"account": {
"id": 200,
"display_name": "Example Company Inc"
}
}
]
}
GET /test-takers?custom_id=ABC456
{
"mode": "live",
"object": "list",
"total_count": 2,
"has_more": false,
"data": [
{
"object": "test_taker_list_item",
"id": 23456,
"first_name": "Oliver",
"last_name": "Sample",
"email": "oliver.sample@jofiscore.com",
"invitation_created_at": "2026-12-03T05:04:04.673371+00:00",
"invitation_id": 78901,
"custom_id": "ABC456",
"person_id": "2bb2141c-4100-4b21-9cd2-a998b76cf737",
"career_navigation_profile_id": null,
"assessment_url": "https://www.jofiscore.com/welcome/1b9617a2-0297-47c7-930b-8fb8e8d4e4b7",
"career_navigation_url": null,
"scorecard_url": "https://www.jofiscore.com/team/100/test-takers/23456/scorecard",
"job_fit_summary_url": null,
"career_options_spotlight_url": null,
"team": {
"id": 100,
"display_name": "Recruiting"
},
"account": {
"id": 200,
"display_name": "Example Company Inc"
}
},
{
"object": "test_taker_list_item",
"id": 34567,
"first_name": "Charlotte",
"last_name": "Sample",
"email": "charlotte.sample@jofiscore.com",
"invitation_created_at": "2026-08-04T19:06:53.921424+00:00",
"invitation_id": 89012,
"custom_id": "ABC456",
"person_id": "3bb2141c-4100-4b21-9cd2-a998b76cf738",
"career_navigation_profile_id": "CNP2345678901",
"assessment_url": "https://www.jofiscore.com/welcome/f6b8646a-6f40-4df0-99a7-94aae3291d45",
"career_navigation_url": "https://www.careernavigation.org?c=CNP2345678901",
"scorecard_url": "https://www.jofiscore.com/team/100/test-takers/34567/scorecard",
"job_fit_summary_url": "https://www.jofiscore.com/test-takers/CNP2345678901/job-fit?r=jfs&zones=1_5",
"career_options_spotlight_url": "https://www.jofiscore.com/test-takers/CNP2345678901/job-fit?r=cor&zones=1_5",
"team": {
"id": 100,
"display_name": "Recruiting"
},
"account": {
"id": 200,
"display_name": "Example Company Inc"
}
}
]
}
Get Test Taker by ID
GET /test-takers/:testTakerId
{
"mode": "live",
"object": "test_taker",
"id": 12345,
"first_name": "Linda",
"last_name": "Sample",
"email": "linda.sample@jofiscore.com",
"phone": "+15555550100",
"invitation_created_at": "2026-12-11T22:23:05.312696+00:00",
"assigned_assessments": [
{
"id": 11111,
"created_at": "2026-12-11T22:23:28.311243+00:00",
"progress_saved_at": "2026-12-11T22:24:53.081+00:00",
"started_at": "2026-12-11T22:24:28.87+00:00",
"completed_at": "2026-12-11T22:24:53.996+00:00",
"is_used_for_scoring": true,
"language": "en",
"assessment": {
"id": 8,
"display_name": "JOFI Career Interests",
"short_name": "Interests"
}
},
{
"id": 22222,
"created_at": "2026-12-11T22:23:28.311243+00:00",
"progress_saved_at": "2026-12-11T22:24:19.155+00:00",
"started_at": "2026-12-11T22:23:43.43+00:00",
"completed_at": "2026-12-11T22:24:20.518+00:00",
"is_used_for_scoring": true,
"language": "en",
"assessment": {
"id": 6,
"display_name": "JOFI Personality Traits",
"short_name": "Personality"
}
}
],
"invited_by_user": {
"id": 33333,
"first_name": "Jane",
"last_name": "Recruiter",
"email": "jane.recruiter@jofiscore.com"
},
"team": {
"id": 100,
"display_name": "Recruiting"
},
"account": {
"id": 200,
"display_name": "Example Company Inc"
},
"assessment_url": "https://www.jofiscore.com/welcome/69608c33-1425-4123-9c49-22c5d9d7838c",
"career_navigation_url": "https://www.careernavigation.org?c=CNP1234567890",
"scorecard_url": "https://www.jofiscore.com/team/100/test-takers/12345/scorecard",
"job_fit_summary_url": "https://www.jofiscore.com/test-takers/CNP1234567890/job-fit?r=jfs&zones=1_5",
"career_options_spotlight_url": "https://www.jofiscore.com/test-takers/CNP1234567890/job-fit?r=cor&zones=1_5",
"invitation_id": 12345,
"custom_id": "ABC123",
"person_id": "1bb2141c-4100-4b21-9cd2-a998b76cf736",
"career_navigation_profile_id": "CNP1234567890"
}
Response fields
List envelope (GET /test-takers)
| Field | Description |
|---|---|
mode | "live" or "test" depending on your API key |
object | Always "list" |
total_count | Total number of test takers matching the request (all in your account, or all matching the provided filters) |
has_more | true if more matching items exist beyond the current response. Requests return up to 50 items by default (including when only team_id is provided); requests that include custom_id and/or email return up to 150 items. |
data | Array of test_taker_list_item objects |
test_taker_list_item fields
| Field | Description |
|---|---|
object | Always "test_taker_list_item" |
id | Test taker ID |
first_name | Participant first name |
last_name | Participant last name |
email | Participant email address |
invitation_created_at | ISO 8601 timestamp when the invitation was created |
invitation_id | Invitation ID |
custom_id | Your grouping identifier, or null |
person_id | Your system's participant identifier, or null |
career_navigation_profile_id | Career Navigation profile ID, or null |
assessment_url | Assessment link, or null |
career_navigation_url | Career Navigation URL, or null |
scorecard_url | JOFI scorecard URL |
job_fit_summary_url | Job Fit Summary report URL, or null |
career_options_spotlight_url | Career Options Spotlight report URL, or null |
team | Team the test taker belongs to ({ id, display_name }) |
account | Account the test taker belongs to ({ id, display_name }) |
test_taker object (GET /test-takers/:testTakerId)
| Field | Description |
|---|---|
mode | "live" or "test" depending on your API key |
object | Always "test_taker" |
id | Test taker ID |
first_name | Participant first name |
last_name | Participant last name |
email | Participant email address |
phone | Invitation phone number, or null |
invitation_created_at | ISO 8601 timestamp when the invitation was created |
assigned_assessments | Assessment progress records (array of { id, created_at, progress_saved_at, started_at, completed_at, is_used_for_scoring, language, assessment }). language is the locale id the assessment was taken in (for example "en" or "es"); it is null until the assessment has been started or completed. |
invited_by_user | JOFI user who sent the invitation ({ id, first_name, last_name, email }) |
team | Team the test taker belongs to ({ id, display_name }) |
account | Account the test taker belongs to ({ id, display_name }) |
assessment_url | Assessment link, or null |
career_navigation_url | Career Navigation URL, or null |
scorecard_url | JOFI scorecard URL |
job_fit_summary_url | Job Fit Summary report URL, or null |
career_options_spotlight_url | Career Options Spotlight report URL, or null |
invitation_id | Invitation ID |
custom_id | Your grouping identifier, or null |
person_id | Your system's participant identifier, or null |
career_navigation_profile_id | Career Navigation profile ID, or null |