Skip to main content

Integration Flow

This is the typical flow from invitation through review and next steps. Use webhooks or GET requests to keep your system in sync. See Webhooks and API Routes.

Base URL for all examples below:

https://www.jofiscore.com/api/v2

Include your API key on every request:

Authorization: Bearer sk_live_...

1. Send the invitation​

Your system creates invitations via POST /invitations. JOFI returns an assessment_url for each participant. See Invitations for required fields and delivery options.

Request

POST https://www.jofiscore.com/api/v2/invitations
Authorization: Bearer sk_live_...
Content-Type: application/json
Request body (showing required fields only)
{
    "created_by_user_email": "jane.recruiter@jofiscore.com",
    "first_name": "Linda",
    "last_name": "Sample",
    "email": "linda.sample@jofiscore.com",
    "person_id": "1bb2141c-4100-4b21-9cd2-a998b76cf736" // optional, but recommended — your system's identifier for this participant
}

Response — 201 Created

POST /invitations response
{
    "mode": "live",
    "object": "invitation",
    "id": 12345,
    "first_name": "Linda",
    "last_name": "Sample",
    "email": "linda.sample@jofiscore.com",
    "person_id": "1bb2141c-4100-4b21-9cd2-a998b76cf736",
    "assessment_url": "https://www.jofiscore.com/welcome/69608c33-1425-4123-9c49-22c5d9d7838c",
    "accepted_at": null,
    "test_taker_id": null,
    "career_navigation_profile_id": null
}

Store JOFI's id and assessment_url.

2. Participant takes assessments on JOFIscore.com​

By default, JOFI emails the participant an invitation that includes their assessment_url. If you set send_via_sms to true on the invitation (and provide a phone number), JOFI also sends the link by text message. If you set send_via_email and send_via_sms to false, you deliver the link yourself using the assessment_url from step 1.

The participant opens the link and completes each assigned assessment on JOFIscore.com. No API call is required for this step.

When the participant accepts the invitation, JOFI creates a test taker record. You can listen for invitation.accepted and test_taker.created webhook events, or poll GET /test-takers later. To fetch every test taker in a group (for example, the same job requisition), use GET /test-takers?custom_id=....

When the participant has completed every assigned assessment and JOFI has finished processing the final scores, JOFI emails the invitation inviter (the user matching created_by_user_email on API-created invitations) if that user has turned on Email me when test takers complete all assigned tests in their JOFI notification settings. The email includes a link to the test taker's scorecard in JOFI.

3. Your team reviews the participant's scores and reports​

Use webhooks, GET routes, or the JOFI Admin UI to access scores and reports as assessments are completed. See Test Takers and Job Fit Reports.

JOFI POSTs to your webhook URL when milestones occur. Example when a test taker is created:

POST https://www.example.com/webhooks/jofi
test_taker.created webhook body
{
    "id": "evt_1a2b3c4d5e6f",
    "type": "test_taker.created",
    "object": "event",
    "created_at": "2026-02-03T12:43:36.744Z",
    "api_version": "2.3.0",
    "data": {
        "object": {
            "object": "test_taker",
            "id": 12345,
            "person_id": "1bb2141c-4100-4b21-9cd2-a998b76cf736",
            "invitation_id": 12345,
            "scorecard_url": "https://www.jofiscore.com/team/100/test-takers/12345/scorecard",
            "job_fit_summary_url": null,
            "career_navigation_url": null
        }
    }
}

See Events for all event types.

Option B: GET test taker by ID​

After you have a test_taker_id (from the invitation response, a webhook, or GET /test-takers), fetch the full record:

GET https://www.jofiscore.com/api/v2/test-takers/12345
GET /test-takers/:testTakerId response
{
    "mode": "live",
    "object": "test_taker",
    "id": 12345,
    "person_id": "1bb2141c-4100-4b21-9cd2-a998b76cf736",
    "invitation_id": 12345,
    "assigned_assessments": [
        {
            "id": 11111,
            "completed_at": "2026-12-11T22:24:53.996+00:00",
            "assessment": {
                "id": 8,
                "display_name": "JOFI Career Interests",
                "short_name": "Interests"
            }
        },
        {
            "id": 22222,
            "completed_at": "2026-12-11T22:24:20.518+00:00",
            "assessment": {
                "id": 6,
                "display_name": "JOFI Personality Traits",
                "short_name": "Personality"
            }
        }
    ],
    "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_navigation_url": "https://www.careernavigation.org?c=CNP1234567890",
    "career_navigation_profile_id": "CNP1234567890"
}

Scorecard and job fit report​

Fetch structured score data for a score profile:

GET https://www.jofiscore.com/api/v2/test-takers/12345/scorecard?sp=JOFI-295-AS

Retrieve the list of available score profiles using GET /score-profiles. Use a Score Profile short_name as the sp query parameter. The sp query parameter is required.

Fetch the job fit report after Personality and Career Interests are complete:

GET https://www.jofiscore.com/api/v2/test-takers/12345/job-fit-report
GET /test-takers/:testTakerId/job-fit-report response (truncated)
{
    "mode": "live",
    "object": "job_fit_report",
    "test_taker_id": 12345,
    "person_id": "1bb2141c-4100-4b21-9cd2-a998b76cf736",
    "riasec_profile": "RCI",
    "career_interests_profile": [
        {
            "display_name": "Realistic",
            "rank": 1
        }
    ],
    "top_fit_occupations": [
        {
            "job_family_name": "Healthcare Practitioners and Technical Zone 5",
            "job_fit_percentage": 87,
            "rank": 1
        }
    ]
}

See Scorecards and Job Fit Reports for full response shapes.

4. For hiring, decide if candidate will proceed​

Review job fit reports, scorecards, and comparison tools to determine whether the candidate moves forward in your hiring process.

Your integration typically uses the job_fit_summary_url or GET /test-takers/:testTakerId/job-fit-report response from step 3 to surface fit rankings and trait profiles in your ATS or internal tools. Use the person_id you supplied when creating the invitation (or custom_id) to match participants back to your system.

5. For career coaching, participant proceeds to CareerNavigation.org​

After the Career Interests assessment, the participant can use their career_navigation_url to explore personalized career recommendations on CareerNavigation.org.

You receive career_navigation_url and career_navigation_profile_id on the test taker object once the profile exists. You can also fetch the profile directly:

GET https://www.jofiscore.com/api/v2/career-navigation-profiles/CNP1234567890
GET /career-navigation-profiles/:careerNavigationProfileId response (truncated)
{
    "mode": "live",
    "object": "career_navigation_profile",
    "id": "CNP1234567890",
    "person_id": "1bb2141c-4100-4b21-9cd2-a998b76cf736",
    "test_taker_id": 12345,
    "career_navigation_url": "https://www.careernavigation.org?c=CNP1234567890",
    "exercises": {
        "strengthsCareerInterests": "…",
        "targetJobName": "…"
    },
    "plan_job_1": {
        "jobName": "Sample Job Name",
        "onetCode": "29-1124.00"
    }
}

See Career Navigation Profiles for the full response.

6. For team building, facilitators can review group reports​

Facilitators can review group-level insights and reports to support team development conversations. Group reports are typically accessed in the JOFI Admin UI rather than through the public API.

For individual participants in a group exercise, use the same test taker, scorecard, and job fit routes from step 3, grouped in your system by custom_id or team.