NAV
shell

Apply API

Overview

This is the official documentation for the JazzHR Apply API.

The Apply API allows partners to send applications to JazzHR through a RESTful interface.

Authenticating Requests

Authorization: Bearer <token>

The bearer token associated with the verified JazzHR user will be included in the Authorization header of all requests, except for the initial request to /authenticate which will return that token.

This bearer token should uniquely identify the user within the Apply API.

POST authentication

Endpoint

POST https://applyapi.jazz.co/v2/authentication

Request Headers

Accept: application/json
Authorization: Token <token>
Content-Type: application/json

Request Body

{
    "userName": "[email protected]",
    "password": "<password>"
}

Response Headers

Content-Type: application/json

Response Body

{
    "token": "<token>"
}

Generates an authentication token for the specified username and password.

The token included in the response should be included in the header of subsequent requests

The lifetime for this generated token is 48 hours. Ideally, it should be cached and regenerated when it expires (subsequent requests respond with a 401 HTTP status code).

GET questions

Endpoint

GET https://applyapi.jazz.co/v2/job/<jobBoardCode>/question

Request Headers

Accept: application/json
Authorization: Token <token>
Content-Type: application/json

200 Response Headers

Content-Type: application/json

200 Response Body Example

[
    {
        "id": "firstName",
        "format": "Text",
        "isRequired": true,
        "label": "First Name",
        "options": null,
        "maxLength": 50,
        "group": null
    },
    {
        "id": "1",
        "format": "Select",
        "isRequired": false,
        "label": "What is your favorite fruit?",
        "options": [
            "Apple",
            "Orange",
            "Banana"
        ],
        "maxLength": null,
        "group": null
    },
    {
        "id": "eeocDisability",
        "format": "Select",
        "isRequired": true,
        "label": "Disability",
        "options": [
            "Yes, I have a disability, or have had one in the past",
            "No, I do not have a disability and have not had one in the past",
            "I do not want to answer"
        ],
        "maxLength": null,
        "group": "complianceOfccp"
    },
    {
        "id": "eeocDisabilitySignature",
        "format": "Text",
        "isRequired": true,
        "label": "Name",
        "options": null,
        "maxLength": 255,
        "group": "complianceOfccp"
    },
    {
        "id": "eeocDisabilitySignatureDate",
        "format": "Date",
        "isRequired": false,
        "label": "Date",
        "options": null,
        "maxLength": null,
        "group": "complianceOfccp"
    }
]

400 Response Headers

Content-Type: application/json

400 Response Body Example

{
    "code": 400,
    "message": "<message>"
}

Returns the questions for the specified job ID.

A question will have one of the following formats:

Questions of format Checkbox and Select will include an array of string options.

Some questions include a maxLength property that should ideally be enforced on the rendered HTML input element.

Parameters

JSON Feed

JazzHR has a global JSON based feed containing a list of jobs and job details that all JazzHR customers have chosen to syndicate. jobBoardCode can be found at node positionProfiles.positionId.value.

You can find example JSON here.

Compliance Groups

Some jobs will include required compliance-related questions with a defined group property that corresponds to one of the groups noted below. Each compliance group contains one or more questions that should be rendered together and prefixed with their respective legal text.

complianceEeo

Two EEO-1 question for gender and race should be prefixed with the following text:

complianceOfccp

Three OFCCP Form CC-305 questions request voluntary self-identification of disability and should be prefixed with the following text:

complianceVevraa

The voluntary self-identification of protected veteran status question should be prefixed with the following text:

POST application

Endpoint

POST https://applyapi.jazz.co/v2/application

Request Headers

Accept: application/json
Authorization: Token <token>
Content-Type: application/json

Request Body Example

{
    "jobBoardCode": "BvGJvE",
    "source": "Example Source",
    "answers": [
        {
            "questionId": "firstName",
            "value": "John"
        },
        {
            "questionId": "lastName",
            "value": "Smith"
        },
        {
            "questionId": "startDate",
            "value": "2016-12-01"
        },
        {
            "questionId": "email",
            "value": "[email protected]"
        },
        {
            "questionId": "file",
            "value": "Sm9obiBTbWl0aApTb2Z0d2FyZSBFbmdpbmVlcgpKYXp6SFI="
        },
        {
            "questionId": "1",
            "value": "100"
        },
        {
            "questionId": "phone",
            "value": "(888) 885-5299"
        },
        {
            "questionId": "citizenWorkStatus",
            "value": "U.S. Citizen/Permanent Resident"
        }
    ]
}

204 Response Headers

Content-Type: application/json

400 Response Headers

Content-Type: application/json

400 Response Body Example

{
    "code": 400,
    "message": "<message>",
    "errors": null
}

400 Response Body Example

When there are failed validation constraints for specific answer values, an "errors" property will be included.

[
    {
        "questionId": "11",
        "messages": [
            "This answer is required"
        ]
    },
    {
        "questionId": "email",
        "messages": [
            "This value is not a valid email address."
        ]
    }
]

Creates an application.

All answer values are of type string with specific validation constraints enforced for each format.

Checkbox

Value is one or more of the related question options, delimited by a pipe character (|). Options that contain a pipe should be escaped by a backslash character ().

Date

Value is of the format "YYYY-MM-DD".

Email

Value is a valid email address.

File

Value is the base64-encoded file contents for a file under 10MB with one of the following accepted MIME types:

Valid Values:

Resume

The question with an ID "resume" (and format "File") must be under 2MB with one of the following accepted MIME types:

Valid Values:

Number

Value is a numeric string.

Phone

Value contains at least seven numeric characters.

Select

Value is one of the related question options.

Text & Textarea

Value length is less than or equal to the question's "maxLength" property, if defined.

Changelog

v2 (August 2020)

Improves behavior of compliance-related questions: