Skip to main content

Getting Started

Welcome to the JOFI API v2 documentation! Please see the changelog below for the latest updates.

The API is available at https://www.jofiscore.com/api/v2. A few example requests:

GET https://www.jofiscore.com/api/v2/accounts
GET https://www.jofiscore.com/api/v2/invitations
GET https://www.jofiscore.com/api/v2/invitations/12345
GET https://www.jofiscore.com/api/v2/test-takers
GET https://www.jofiscore.com/api/v2/test-takers/12345
GET https://www.jofiscore.com/api/v2/test-takers/12345/scorecard?sp=JOFI-295-AS
GET https://www.jofiscore.com/api/v2/career-navigation-profiles
GET https://www.jofiscore.com/api/v2/career-navigation-profiles/CP1ABC234DEF

You will need to include your API key in the headers, like so:

Authorization: Bearer sk_live_ELABcdEFghIJkl

Your API key is linked to your JOFI Account. You can call /accounts to retrieve information about the account linked to your API key. All requests you make using that API key will read and write records associated with that account.

You will have 2 API keys, prefixed with sk_live or sk_test. Use sk_test for development. Please be careful to keep your API keys secret.

Contact your JOFI representative to get your API keys.

tip

Looking for the v1 documentation? You can still find it here, but we recommend moving to the v2 API as soon as you can.

Before you start​

  • Obtain your JOFI API keys from your JOFI representative. Your account will 1 "live" API key and 1 "test" API key. See API Keys
  • Configure your webhook endpoints. Your account can have 1 "live" webhook endpoint and 1 "test" webhook endpoint. See Webhooks and Events.
  • Add teams and users to your JOFI account, and configure each users' default settings. These include assessments to assign by default, communication preferences, notifications to send by default, and more. Work with your JOFI representative to add users.
  • (recommended) Try the JOFI Assessment experience yourself. Ask your JOFI representative to send you an invitation. You'll be able to click the assessment link in the email, take all three assessments on jofiscore.com, view your Job Fit report, and complete exercises on careernavigation.org using your personalized career recommendations.

Quick summary​

  • Send the invitation
    • Your team members will add participants to your system.
    • Your system will make a request to the JOFI API to create an invitation, JOFI will respond with the newly created invitation object including the assessment_url.
    • JOFI will send the invitation to the participant via email and text message (optional).
    • The participant will click the unique link in the invitation, called the assessment_url, which will take them to jofiscore.com.
    • The participant will accept the terms and be taken to their assessment dashboard. When they accept the invitation, their test_taker record is created. JOFI will send the events invitation.accepted and test_taker.created to your webhook endpoint.
  • Participant takes the assessments on JOFIscore.com
    • The participant can proceed to take each assessment that has been assigned to them.
    • As they complete assessments, JOFI will send events to your webhook endpoint like test_taker.assessment_completed.
    • Your system can listen to those events, and update your record for the participant.
    • When the participant has completed the Career Interests assessment, their career_navigation_profile record is created. JOFI will send the event career_navigation_profile.created to your webhook endpoint. It will include the navigation_url.
  • Participant completes exercises on CareerNavigation.org
    • The participant can use their navigation_url to access CareerNavigation.org with their personalized career recommendations.
    • Alternatively, you can always call any of the GET routes to fetch current information about any participant.

API Routes​

A complete list of all routes available in the v2 API.

Fetch data about your account, users, teams
GET /accounts
GET /users
GET /teams
Create, list, and update invitations
POST /invitations
GET /invitations
GET /invitations/:invitationId
PUT /invitations/:invitationId
Fetch test takers, report links, and retrieve scorecard scores
GET /test-takers
GET /test-takers/:testTakerId
GET /test-takers/:testTakerId/scorecard?sp={scoreProfileShortName}
Fetch career navigation participants and exercise responses
GET /career-navigation-profiles
GET /career-navigation-profiles/:careerNavigationProfileId
Fetch data about JOFI objects
GET /assessments
GET /score-profiles

Postman Collection​

Want to quickly get up-and-running in Postman? Download the Postman collection.

Changelog​

v2.1.0 — Released December 19, 2024​

Added the fields custom_id and person_id to several API route responses: List Invitations, List Test Takers, List Career Navigation Profiles, Get Test Taker Scorecard. These fields already existed in the routes to Get Invitation or Get Test Taker, but they were not included in the List items routes.

The custom_id field is useful for grouping together Invitations by things like Job Requisition # or Career Coaching Participant Group #. The person_id field is a field for you to include the ID for this participant from your system. Then you can use the person_id field to match the participant with their record in your system.

v2.0.0 — Released December 12, 2024​

The new version of the JOFI API. 14 new API routes. A more logical flow from Invitation to Test Taker to Career Navigation. More standardized API responses and object shapes. Better error handling and validation error messages. And a number of other internal improvements!