Getting Started

Welcome to the JOFI API! You are reading the v1 docs, stable as of April 2021.

warning

Heads up! The v2 API is ready for you to use and the v1 API is now in maintenance mode. Check out the v2 documentation here.

Authentication

To use the JOFI API, you must authenticate using an Account SID and an Auth Token. You must provide both as query parameters with each API call. Please reach out to your JOFI contact so they can issue you your API credentials.

Every API request must include query parameters:

auth = YOUR_AUTH_TOKEN
sid = YOUR_ACCOUNT_SID

Example API Request:

https://www.jofiscore.com/api/v1/account?auth=TOkm-ABcdEF123456-123abC456dEf&sid=ACab12cdEFhi45jk9lmNopQr

Testing and Production

Production: https://www.jofiscore.com/api/v1

Sandbox: https://sandbox-qlurhxliv.jofiscore.com/api/v1

Testing

For your development and testing, please use the "sandbox" site. Note that the Sandbox site is updated less frequently and is a smaller instance than the production site, please reach out if you have any issues using Sandbox.

All API Routes

Here are all of the API routes you will need to work with JOFI programmatically:

Name	Method	Path
Get Account	GET	/account
Create Invitation	POST	/invitations/create
List Invitations	GET	/invitations
Get Invitation by ID	GET	/invitations/:invitationId
List Test Takers	GET	/test-takers
Get Test Taker by ID	GET	/test-takers/:testTakerId
List Assessments	GET	/tests

They will be explained in more detail as you continue.

Making API Requests

Here is the structure of the URL you would use to make a GET request to fetch all invitations for your account:

List Invitations by Account

// base_url could be production or sandbox, i.e. https://www.jofiscore.com/api/v1
// auth_token is a secret string provided by JOFI
// account_sid is a public account identifier provided by JOFI

GET {base_url}/invitations?auth={auth_token}&sid={account_sid}

Step-By-Step Example

An overview of the steps you might take as you use the JOFI API:

1. Get your account and teams. First, make an API request to /account and you will see the list of teams in your account (your account is identified by your account_sid). You will need to use one of those team IDs when you create an invitation, because invitations are associated with a team.
2. Create an invitation. Make a POST request to /invitations/create with the required data in the body (see Invitations for more info). This will create an invitation in the JOFI system, and will return important data such as the invitation ID and the assessment link.
3. Send the invitation. If you choose, JOFI will send the invitation via email or text message. Or you may choose to turn off the email and SMS option, and share the assessment link with the Test Taker using your system. Either way, the invitation will include a unique assessment link that the Test Taker will use to access JOFI and take their assessments.
4. Test taker accepts invitation. The invitations you create are nothing more than placeholders for Test Takers. You can imagine creating and sending 1,000 invitations, and only 750 ever turn into actual Test Takers. You are not billed for creating invitations; you only pay for Test Takers.
   1. Invitations include an assessment link that allows the individual to access JOFI without needing a username or password. When the individual uses their assessment link, that's when a Test Taker record is created in the JOFI system for that individual, and from that point forward they are considered a Test Taker.
   2. When you make a GET request to /invitations/:invitationId, you will see a test_taker_seats property in the response. That property will be an empty array before the Test Taker accesses their assessment link, and it will include their Test Taker ID after they have accessed their assessment link.
   3. You should store both the Invitation ID and the Test Taker ID in your system.
5. Get Test Taker scores. You have three options for how to retreive scores for a Test Taker:
   1. Webhook (preffered): You can include a statusCallbackUrl when you create an invitation. If you do so, then each time a Test Taker completes an assessment, JOFI will call the statusCallbackUrl and will include the updated Test Taker scores in the body. Your system will be able to match the Test Taker to their record in your system, and update their scores.
   2. Polling: You can have your system call the /test-takers/:testTakerId endpoint to check for completed tests and scores. You can poll the endpoint to check for updates regularly until all tests are completed and you no longer need to continue polling. Please limit polling frequency to > 1 minute.
   3. On-Demand: You can call the /test-takers/:testTakerId endpoint when your user loads the record in your system.

Now that you know the basic workflow, the next step is to Create an Invitation.