Candidate Export Event

Overview

This is the official documentation for the JazzHR Candidate Export Webhook.

The Candidate Export Webhook allows partners to build custom endpoints and subscribe to export events that happen via manual or automatic user actions within the JazzHR platform. When a candidate export is triggered, we will send an HTTP POST payload to the configured URL. The Candidate Export Event payload will be sent via HTTP POST to the configured URL endpoint.

To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code.

All response codes outside of this range (including 3xx codes) will indicate that you did not receive the webhook and display an error to the user. Webhook data is sent as JSON in the POST request body.

HTTP POST payloads that are delivered to your webhook’s configured URL endpoint will contain specific headers:

Header	Description
Link	This header will contain the URL for the candidate’s profile within JazzHR.
User-Agent	This header will identify JazzHR as the requesting application user agent. Header value will be `JazzHR`.
X-JazzHR-Event	Event type indicator. Header value will be `CANDIDATE-EXPORT`
X-JazzHR-Export-Context	Optional header indicating the job associated with the exported candidate. Will not be present if candidate exported is not attached to a job.
X-JazzHR-Signature	The HMAC hex digest of the response body used to verify the source of the webhook payload. The HMAC hex digest is generated using the `sha256` hash function and the `secret` provided to JazzHR as the HMAC key.
X-JazzHR-UUID	This header will provide a unique string identifier for the request.

URL Requirements

Example URL suggestions


https://example.service/webhook/{{clientId}}

https://example.service/webhook?id={{clientId}}

In situations where the service receiving a webhook from JazzHR is serving multiple clients, we are requiring the URL provided to include a unique identifier.

In the examples provided, the {{clientId}} placehold is for an identifier originating from your system. This identifier will be how the receiving system can differentiate to whom the incoming data belongs.

Export Payload

Sample JSON Payload

{
    "candidate": {
        //<HROpen Candidate>
    }
}

This is a sample of the JazzHR Candidate Export Webhook JSON payload. Listed here are all properties linked to their corresponding objects.

Property	Type
candidate	HROpen Candidate

Sample JSON File

A full JSON example can be downloaded here.

Field Types

Types	Description	Example
string	Arbitrary string of characters/digits/etc.	"Foo bar 123!"
number	Integers & floats (no commas or letters)	50000 or 3.14
boolean	true or false	true or false
date	YYYY-MM-DD	"1982-09-30"
datetime	YYYY-MM-DD HH:mm:ss	“1982-09-30 14:15:16”
template	HTML Template string	"<p>Job Description</p>"

HROpen Candidate Object

Sample HROpen Candidate JSON Object

{
    "alternateIds": [
      {
        "value": "string",
        "schemeId": "JazzHR Legacy Candidate",
        "schemeAgencyId": "JazzHR"
      }
    ],
    "person": {
      "id": {
        "value": "string",
        "schemeId": "JazzHR Candidate",
        "schemeAgencyId": "JazzHR"
      },
      "name": {
        "formattedName": "string",
        "given": "string",
        "family": "string"
      },
      "gender": "string",
      "citizenShip": [
        "string"
      ],
      "applyDate": "date",
      "communication": {
        "address": [{
          "countrySubdivisions": [{
            "type": "state",
            "value": "string"
          }],
          "city": "string",
          "postalCode": "string",
          "line": "string",
          "formattedAddress": "string"
        }],
        "phone": [{
          "formattedNumber": "string"
        }],
        "email": [{
          "address": "string"
        }],
        "web": "template"
      },
      "customFields": [{
        "id": {
          "value": "string",
          "schemeId": "JazzHR Custom Field",
          "schemeAgencyId": "JazzHR"
        },
        "name": "string",
        "type": "string",
        "value": "string"
      }]
    },
    "profiles": [{
      "alternateIds": [
        {
          "value": "string",
          "schemeId": "JazzHR Legacy Job Application",
          "schemeAgencyId": "JazzHR"
        }
      ],
      "languageCode": "en-US",
      "profileId": {
        "value": "string",
        "schemeId": "JazzHR Job Application",
        "schemeAgencyId": "JazzHR"
      },
      "associatedPositionOpenings": [{
        "alternateIds": [
          {
            "value": "string",
            "schemeId": "JazzHR Legacy Job",
            "schemeAgencyId": "JazzHR"
          }
        ],
        "positionOpeningId": {
          "value": "string",
          "schemeId": "JazzHR Job",
          "schemeAgencyId": "JazzHR"
        },
        "positionTitle": "string",
        "positionUri": "string",
        "candidateStatus": {
          "name": "string",
          "category": "string",
          "transitionDateTime": "datetime"
        },
        "customFields": [{
          "id": {
            "value": "string",
            "schemeId": "JazzHR Custom Field",
            "schemeAgencyId": "JazzHR"
          },
          "name": "string",
          "type": "string",
          "value": "string"
        }, 
        {
          "id": {
            "value": "string",
            "schemeId": "JazzHR Start Date",
            "schemeAgencyId": "JazzHR"
          },
          "name": "startDate",
          "type": "date",
          "value": "string"
        }]
      }],
      "education": [{
        "educationLevelCodes": [{
          "name": "string"
        }]
      }],
      "attachments": [{
        "id": {
          "value": "string",
          "schemeId": "JazzHR Document to Candidate",
          "schemeAgencyId": "JazzHR"
        },
        "descriptions": [
          "string"
        ],
        "url": "string"
      }]
    }]
  }

alternateIds

Contains an array with an HROpen Identifier object for mapping to legacy JazzHR Candidate id used with the JazzHR API.

The legacy id for JazzHR Candidate maps to applicant_id within the JazzHR API.

person.id.value

Unque key for identifying the candidate

person.gender

Candidate's gender

Possible Values:

"Male"
"Female"

person.citizenship

Candidate work authorization

Possible Values:

"No Answer"
"U.S. Citizen/Permanent Resident"
"Non-citizen allowed to work for any employer"
"Non-citizen allowed to work for current employer"
"Non-citizen seeking work authorization"
"Canadian Citizen/Permanent Resident"
"Other"

person.customFields

Refer to the JazzHR Custom Field Object section for further details.

profiles

Contains a collection of profile objects relating to each JazzHR Job Application associated with the candidate. Often times this will be an array with just a single object.

profiles.alternateIds

Contains an array with an HROpen Identifier object for mapping to legacy JazzHR Job Application id used with the JazzHR API.

The legacy id for JazzHR Job Application maps to appjob_id within the JazzHR API.

profiles.associatedPositionOpenings.alternateIds

Contains an array with an HROpen Identifier object for mapping to legacy JazzHR Job id used with the JazzHR API.

The legacy id for JazzHR Job maps to job_id within the JazzHR API.

profiles.associatedPositionOpenings.positionOpeningId.value

Used to key into PositionOpenings

profiles.associatedPositionOpenings.candidateStatus

The candidate's status in the hiring workflow. Possible values for category include:

New
Active
Hired
Not Hired

profiles.associatedPositionOpenings.customFields

An optional custom field may be included in the export for Start Date. If it is set upon export, the name property for the custom field will be startDate following the date type formatting of YYYY-MM-DD; if this value is not set, it will not be included in the export.

Refer to the JazzHR Custom Field Object section for further details.

profiles.education.educationLevelCodes.name

Education level

Possible Values:

"No Answer"
"GED or Equivalent"
"High School"
"Some College"
"College - Associates"
"College - Bachelor of Arts"
"College - Bachelor of Fine Arts"
"College - Bachelor of Science"
"College - Master of Arts"
"College - Master of Science"
"College - Master of Fine Arts"
"College - Master of Business Administration"
"College - Doctorate"
"Medical Doctor"
"Other"

JazzHR Document Object

Sample JazzHR Document JSON Object

{
   "content": "...base64encoded...",
   "mimeType": "application/pdf",
   "fileName": "TestDoc.pdf"
}

Documents that are associated to the candidate’s application / application process can be found in the HROpen Candidate Object profile’s attachments property.

Document URLs

Any documents in the Candidate Export Webhook payload will be included as a public URL available for 2 hours and 30 minutes after the initial candidate export event occurs.

Documents will be returned as base64 encoded content with a mime type and a file name.

JazzHR Custom Field Object

Sample JazzHR Custom Field JSON Object

{
   "id": {
      "value": "string",
      "schemeId": "JazzHR Custom Field",
      "schemeAgencyId": "JazzHR"
   },
   "name": "string",
   "type": "string",
   "value": "string"
}

Types of Custom Fields

Custom Field objects come in two varieties: they can have a relationship with a Candidate or they can have a relationship with a Job. Custom fields can be configured by users to each represent one of several different data types. These types are as follows:

"string"
"number"
"date"

In the case of a Custom Field associated with a candidate the data can be found in the relationship with the person Object.

In the case of a Custom Field associated with a job the data can be found in the relationship with the profiles.associatedPositionOpenings Object.

Verification Event

Verification Event JSON Body

{
    "data": "JazzHR Verify Event"
}

Use This to Verify the Endpoint Handles the Event Properly:

curl --location --request POST 'CONFIGURED_URL'
--header 'X-JazzHR-Event: VERIFY' 
--header 'X-JazzHR-Signature: SHA256-REQUEST-SECRET' 
--header 'Content-Type: application/json' 
--data-raw '{
    "data": “JazzHR Verify Event"
}'

PHP Example of JazzHR Signature

$secret = 'secret-key';
$rawRequestBody = '{"data":"JazzHR Verify Event"}';
$jazzHrSignature = hash_hmac('sha256', $rawRequestBody, $secret);

// Output Hash
// 4fdc7dcdcb02bca16c7ec4a15b9d6436de1f186e11ff155d0ab178b5aca4f30e

During setup, the JazzHR platform will send an HTTP POST to the configured URL to determine if it has been set up correctly.

The given endpoint must respond with a status code of 200 to be considered configured correctly to receive any other webhook events from JazzHR.

HTTP POST payloads that are delivered to your webhook’s configured URL endpoint will contain two special headers:

Header	Description
X-JazzHR-Event	Event type indicator. Header value will be `VERIFY`.
X-JazzHR-Signature	The HMAC hex digest of the response body used to verify the source of the webhook payload. The HMAC hex digest is generated using the `sha256` hash function and the `secret` provided to JazzHR as the HMAC key.

User Flows

Adding a Custom Integration

From Settings > Integrations

Select the Add Custom Integration button to open the connection modal.

Add Integration

Required for connecting a Custom Integration

Information required to setup a custom integration:

Integration Name - Unique name for this integration
Integration [Webhook] URL - URL to which JazzHR will POST
Secret Key - Used in hashing the JazzHR Signature header, optional value depending on the partner.

Connect a Custom Integration

When the Save button is clicked, the Verification Event will be sent to the provided endpoint before it is finalized.

Connected Custom Integration

Once the saving has completed, the Custom Integration will be displayed in the setup state. Options are available to edit information or remove the integration.

Connected Custom Integration

Manual Candidate Export

From any Candidate Profile, choose "Export Candidate"

Export Candidate

Export Candidate Modal

Optional information to set on export:

Start Date - Start Date of the candidate, exported as a date in the format of YYYY-MM-DD as a custom field with the name property of startDate.

Automatic Candidate Export

1. Setup a Workflow Helper on a Workflow step

Workflow Trigger Setup

2. Automatically trigger a Workflow Helper when a candidate enters the Workflow step

Workflow Trigger Export Candidate