NAV Navbar
shell

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 to.

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

{
    "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"
      }
    },
    "profiles": [{
      "languageCode": "en-US",
      "profileId": {
        "value": "string",
        "schemeId": "JazzHR Job Application",
        "schemeAgencyId": "JazzHR"
      },
      "associatedPositionOpenings": [{
        "positionOpeningId": {
          "value": "string",
          "schemeId": "JazzHR Job",
          "schemeAgencyId": "JazzHR"
        },
        "positionTitle": "string",
        "positionUri": "string",
        "candidateStatus": {
          "name": "string",
          "category": "string",
          "transitionDateTime": "datetime"
        }
      }],
      "education": [{
        "educationLevelCodes": [{
          "name": "string"
        }]
      }],
      "attachments": [{
        "id": {
          "value": "string",
          "schemeId": "JazzHR Document to Candidate",
          "schemeAgencyId": "JazzHR"
        },
        "descriptions": [
          "string"
        ],
        "url": "string"
      }]
    }]
  }
}

person.id.value

Used to key into AdditionalPersonInformation & PersonDocuments

person.gender

Prospect's gender

Possible Values:

person.citizenship

Prospect work authorization

Possible Values:

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:

profiles.education.educationLevelCodes.name

Education level

Possible Values:

JazzHR Document Object

Sample JazzHR Document JSON Object

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

Types of Documents

There are two main types of documents. One, documents that are associated to the candidate’s application / application process. These can be found in the HROpen Candidate Object profile’s attachments property. Two, additional documents associated directly with the candidate (and not necessarily with the candidate’s application). These will be found in the JazzHR PersonDocuments Object.

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.

Verification Event

Verification Event JSON Body

{
    "data": "JazzHR Verify Event"
}

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:

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

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