Skip to main content

Invitations

Create Invitation​

Make a POST request to /invitations with required fields in the request body to create a new Invitation.

info

The only required fields are first_name, last_name, email, and created_by_user_email. However, this relies on the user default settings described below.

By default, the invitation will be associated with the default team for the created_by_user_email. The user must set their default team in their user settings. You can override this by providing team_id in the body. Use the Teams API route to get the list of available teams.

By default, the invitation will assign the default assessments for the created_by_user_email. The user must set their default assessments in their user settings. You can override this by providing assessments_to_assign in the body. Use the Assessments API Route to get the list of available assessments.

POST /invitations body
// required fields
{
    "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", // recommended, your system's ID for this participant
}

// or choose to include optional fields
{
    "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", // recommended, your system's ID for this participant
    // everything below is optional
    "phone": "5551234567", // if you want JOFI to send the invitation via text message
    "custom_id": "ABC123", // useful for grouping by Job Req # or Career Coaching Group #
    "team_id": 1234513245, // the team to associate this invitation with, defaults to the created_by_user_email default team
    "assessments_to_assign": [
        { "test_id": 6 }, // JOFI Personality Traits assessment
        { "test_id": 7 }, // JOFI Thinking Skills assessment
        { "test_id": 8 }, // JOFI Career Interests assessment
    ],
    "send_via_email": true, // set to false if you want to provide the assessment link to the participant
    "send_via_sms": true, // set to false if you want to provide the assessment link to the participant
    "email_template_id": 1234512345, // if your account uses a custom email template
    "ref_text": "Contact Jennifer White with Questions", // some email templates allow for reference text
}
POST /invitations response
{
    "mode": "live",
    "object": "invitation",
    "id": 1234512345,
    "invited_by_user": {
        "id": 1234612346,
        "first_name": "Jane",
        "last_name": "Recruiter",
        "email": "jane.recruiter@jofiscore.com"
    },
    "created_at": "2024-12-11T22:23:05.312696+00:00",
    "accepted_at": null,
    "first_name": "Linda",
    "last_name": "Sample",
    "email": "linda.sample@jofiscore.com",
    "send_via_email": true,
    "phone": "+15551234567",
    "send_via_sms": false,
    "custom_id": "ABC123",
    "person_id": "1bb2141c-4100-4b21-9cd2-a998b76cf736",
    "invitation_email_template": {
        "id": 353,
        "display_name": "Invitation v2"
    },
    "ref_text": null,
    "congrats_email_template": {
        "id": 354,
        "display_name": "Congrats v2"
    },
    "send_congrats_notification": true,
    "target_score_profile": null,
    "invitation_assessments": [
        {
            "id": 6,
            "display_name": "JOFI Personality Traits",
            "short_name": "Personality"
        },
        {
            "id": 8,
            "display_name": "JOFI Career Interests",
            "short_name": "Interests"
        }
    ],
    "assessment_url": "https://www.jofiscore.com/welcome/69608c33-1425-4123-9c49-22c5d9d7838c",
    "career_navigation_url": null,
    "scorecard_url": null,
    "job_fit_summary_url": null,
    "career_options_spotlight_url": null,
    "team": {
        "id": 123123,
        "display_name": "Recruiting"
    },
    "account": {
        "id": 9999,
        "display_name": "Example Account"
    },
    "test_taker_id": null,
    "career_navigation_profile_id": null
}

List Invitations​

Make a GET request to /invitations to retrieve a list of the most recent Invitations created in your account.

note

Pagination and the ability to request the next set of items is coming soon. You can use the has_more property to determine if there are more for you to fetch. For now, only the most recent 30 items are returned.

GET /invitations
{
    "mode": "live",
    "object": "list",
    "total_count": 162,
    "has_more": true,
    "data": [
        {
            "object": "invitation_list_item",
            "id": 1234512345,
            "first_name": "Liam",
            "last_name": "Sample",
            "email": "liam.sample@jofiscore.com",
            "created_at": "2024-12-11T22:23:05.312696+00:00",
            "accepted_at": "2024-12-11T22:23:27.816+00:00",
            "assessment_url": "https://www.jofiscore.com/welcome/5e19b39c-053f-4b95-9e00-12c1280709cb",
            "test_taker_id": 2345623456,
            "custom_id": "example_Group4115",
            "person_id": "example_nb5IHJjlHe5N7CNJ2afTC"
        },
        {
            "object": "invitation_list_item",
            "id": 1234612346,
            "first_name": "Olivia",
            "last_name": "Sample",
            "email": "olivia.sample@jofiscore.com",
            "created_at": "2024-12-11T22:21:44.960799+00:00",
            "accepted_at": null,
            "assessment_url": "https://www.jofiscore.com/welcome/056590cb-655c-45bf-ac02-928148456445",
            "test_taker_id": null,
            "custom_id": "example_Group4115",
            "person_id": "example_18i7PCV_FlhJ_6NdzgwRo"
        },
        // truncated for brevity
        {
            "object": "invitation_list_item",
            "id": 1234712347,
            "first_name": "Noah",
            "last_name": "Sample",
            "email": "noah.sample@jofiscore.com",
            "created_at": "2024-06-19T11:53:36.048918+00:00",
            "accepted_at": null,
            "assessment_url": "https://www.jofiscore.com/welcome/e174b92e-20aa-450e-9a8d-1f8232430ad6",
            "test_taker_id": null,
            "custom_id": "example_Group2281",
            "person_id": "example_iRPHHcvLlmCHmFnrkCs_y"
        },
        {
            "object": "invitation_list_item",
            "id": 1234812348,
            "first_name": "Emma",
            "last_name": "Sample",
            "email": "emma.sample@jofiscore.com",
            "created_at": "2024-06-19T11:51:01.87555+00:00",
            "accepted_at": null,
            "assessment_url": "https://www.jofiscore.com/welcome/674cf088-bbca-46e5-a1c4-48ada07c19e5",
            "test_taker_id": null,
            "custom_id": "example_Group2281",
            "person_id": "example_jPbNA6YSA-z-Q4uyvvFE_"
        }
    ]
}

Get Invitation by ID​

Make a GET request to /invitations/:invitationId to retrieve a complete invitation object for one participant.

GET /invitations/:invitationId
{
    "mode": "live",
    "object": "invitation",
    "id": 1234512345,
    "invited_by_user": {
        "id": 1234612346,
        "first_name": "Jane",
        "last_name": "Recruiter",
        "email": "jane.recruiter@jofiscore.com"
    },
    "created_at": "2024-12-11T22:23:05.312696+00:00",
    "accepted_at": "2024-12-11T22:23:27.816+00:00",
    "first_name": "Linda",
    "last_name": "Sample",
    "email": "linda.sample@jofiscore.com",
    "send_via_email": true,
    "phone": "+15551234567",
    "send_via_sms": false,
    "custom_id": "ABC123",
    "person_id": null,
    "invitation_email_template": {
        "id": 1234,
        "display_name": "Invitation v2"
    },
    "ref_text": null,
    "congrats_email_template": {
        "id": 1234,
        "display_name": "Congrats v2"
    },
    "send_congrats_notification": true,
    "target_score_profile": null,
    "invitation_assessments": [
        {
            "id": 6,
            "display_name": "JOFI Personality Traits",
            "short_name": "Personality"
        },
        {
            "id": 8,
            "display_name": "JOFI Career Interests",
            "short_name": "Interests"
        }
    ],
    "assessment_url": "https://www.jofiscore.com/welcome/69608c33-1425-4123-9c49-22c5d9d7838c",
    "career_navigation_url": "https://www.careernavigation.org?c=CP8ABC123HIJ",
    "scorecard_url": "https://www.jofiscore.com/team/328/test-takers/42558/scorecard",
    "job_fit_summary_url": "https://www.jofiscore.com/test-takers/CP8ABC123HIJ/job-fit?r=jfs&zones=1_5",
    "career_options_spotlight_url": "https://www.jofiscore.com/test-takers/CP8ABC123HIJ/job-fit?r=cor&zones=1_5",
    "team": {
        "id": 1234,
        "display_name": "Recruiting"
    },
    "account": {
        "id": 9999,
        "display_name": "CoffeeBean Inc"
    },
    "test_taker_id": 1234612346,
    "career_navigation_profile_id": "CP8ABC123HIJ"
}

Update Invitation by ID​

Make a PUT request to /invitations/:invitationId with the fields to update in the request body to update an Invitation.

PUT /invitations/55506
// body
{
    "first_name": "Lindsay",
    "email": "lindsay.sample@jofiscore.com"
}

// response
{
    "mode": "live",
    "object": "invitation",
    "id": 1234512345,
    "invited_by_user": {
        "id": 1234612346,
        "first_name": "Jane",
        "last_name": "Recruiter",
        "email": "jane.recruiter@jofiscore.com"
    },
    "created_at": "2024-12-11T22:23:05.312696+00:00",
    "accepted_at": null,
    "first_name": "Lindsay",
    "last_name": "Sample",
    "email": "lindsay.sample@jofiscore.com",
    "send_via_email": true,
    "phone": "+15551234567",
    "send_via_sms": false,
    "custom_id": "ABC123",
    "person_id": null,
    "invitation_email_template": {
        "id": 1234,
        "display_name": "Invitation v2"
    },
    "ref_text": null,
    "congrats_email_template": {
        "id": 1234,
        "display_name": "Congrats v2"
    },
    "send_congrats_notification": true,
    "target_score_profile": null,
    "invitation_assessments": [
        {
            "id": 6,
            "display_name": "JOFI Personality Traits",
            "short_name": "Personality"
        },
        {
            "id": 8,
            "display_name": "JOFI Career Interests",
            "short_name": "Interests"
        }
    ],
    "assessment_url": "https://www.jofiscore.com/welcome/69608c33-1425-4123-9c49-22c5d9d7838c",
    "career_navigation_url": null,
    "scorecard_url": null,
    "job_fit_summary_url": null,
    "career_options_spotlight_url": null,
    "team": {
        "id": 1234,
        "display_name": "Recruiting"
    },
    "account": {
        "id": 9999,
        "display_name": "CoffeeBean Inc"
    },
    "test_taker_id": null,
    "career_navigation_profile_id": null
}