Skip to main content

Invitations

Create Invitation​

Make a POST request to the following endpoint:

Create Invitation
// POST
/invitations/create

The body should contain the following properties:

teamId: number; // get your teamIds by calling /account
firstName: string;
lastName: string;
customId: string; // optional
sentToEmail: string;
sentToPhone: string; // optional
sendViaSms: boolean; // optional
sendViaEmail: boolean;
statusCallbackUrl: string; // optional
assignPrescreen: boolean; // at least one must be true
assignPersonality: boolean; // at least one must be true
assignInterests: boolean; // at least one must be true
assignThinking: boolean; // at least one must be true
Webhooks

If you want JOFI to call your API when a Test Taker completes a test, include a statusCallbackUrl when you create an invitation (recommended).

Example POST and response​

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

// Example post body
{
  "teamId": 123,
  "firstName": "Gary",
  "lastName": "DocsTest",
  "customId": "AID123",
  "sentToEmail": "gary.docstest@example-email.com",
  "sendViaEmail": true,
  "statusCallbackUrl": "https://www.{your-domain}.com/api/users/{your-user-id}/jofi-status",
  "assignPersonality": true,
  "assignInterests": true
}

If successful, you will receive a 200 response similar to this example response:

{
  "id": 112233,
  "invite_key": "b0cb81b2-a9c4-42a8-87dd-123abcdef456",
  "first_name": "Gary",
  "last_name": "DocsTest",
  "created_at": "2024-01-16T15:17:23.782834+00:00",
  "team_id": 123,
  "custom_id": "AID123",
  "ref_text": null,
  "send_via_email": true,
  "send_via_sms": false,
  "sent_to_email": "gary.docstest@example-email.com",
  "sent_to_phone": "",
  "status_callback_url": "https://www.{your-domain}.com/api/users/{your-user-id}/jofi-status",
  "assessment_link": "https://www.jofiscore.com/welcome/1764ba5d-ebdb-4593-a279-abcdef123456"
}
What To Save

In the response, note the id and assessment_link.

Save the id as the Invitation ID, you will use it to fetch the Invitation later to see if the individual has accessed it using Get Invitation by ID.

Save the assessment_link. It is the link you can share with the individual who wants to take the assessments. Or you can embed it in your application if you prefer to have the test taker click a button or link in your application.

Get Invitation by ID​

Make a GET request to the following endpoint:

/invitations/:invitationId

Example request

Get Invitation by ID
{base_url}/invitations/112233?auth={auth_token}&sid={account_sid}

Example response:

{
  "id": 112233,
  "accepted_at": null,
  "created_at": "2024-01-16T15:17:23.782834+00:00",
  "updated_at": "2024-01-16T15:17:23.782834+00:00",
  "status_callback_url": "https://www.{your-domain}.com/api/users/{your-user-id}/jofi-status",
  "custom_id": "AID123",
  "first_name": "Gary",
  "last_name": "DocsTest",
  "sent_to_email": "gary.docstest@example-email.com",
  "send_via_email": true,
  "sent_to_phone": "",
  "send_via_sms": false,
  "test_taker_seats": [],
  "team": {
    "id": 4242,
    "display_name": "Recruiting Team",
    "account": {
      "id": 8080,
      "display_name": "Example Company, Inc."
    }
  },
  "test_taker_magic_links": [
    {
      "id": "1764ba5d-ebdb-4593-a279-112233445566",
      "created_at": "2024-01-16T15:17:23.896946+00:00",
      "is_revoked": false,
      "magic_link": "https://www.jofiscore.com/welcome/1764ba5d-ebdb-4593-a279-abcdef123456"
    }
  ]
}

In the response, note the test_taker_seats array. This will be empty before the individual accesses the assessment link.

Invitation to Test Taker

Currently, JOFI does not notify your system when an individual has accessed their assessment link and has become a Test Taker. However, if you provide a statusCallbackUrl when you create the Invitation, that would be the mechanism JOFI would use to notify your system when an individual becomes a Test Taker. This functionality is not yet implemented, but if you would like it, please let us know!

Until then, your system will need to call the Get Invitation by ID endpoint to check the test_taker_seats array.

After the individual accesses the assessment link, the test_taker_seats array will include their test taker information. It will look like this:

"test_taker_seats": [
    {
        "id": 45678,
        "created_at": "2024-01-16T15:22:57.411622+00:00"
    }
],
What To Save

Save the id as the Test Taker ID. You will use this to get the test taker data and scores using the Get Test Taker by ID.

When the individual has used their assessment link and has become a Test Taker, you will no longer need to use the invitation.

Next, learn how to work with Test Takers.