We provide the API access keys and Account IDs for each standard environment. We suggest using our TEST (harver-test.com) environment during the development phase.

Available Harver environments for clients:

• Test: https://api.harver-test.com
• Production: https://api.harver.com

Harver Public API uses Oauth2 authentication, once you obtained an access token (valid for 1 hour) you can use it in the Authentication Header as a “Bearer” token for all following requests.

Endpoint:
POST https://api.harver.com/oauth/token

Note:
in TEST env, POST https://api.harver-test.com/oauth/token

Content-Type:
application/x-www-form-urlencoded

Body:

• grant_type → client_credentials
• client_id → Provided by Harver
• client_secret → Provided by Harver

After a successful request, the response will contain the “access-token“.

Example

curl --location --request POST 'https://api.harver-test.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id={your_client_id}' \
--data-urlencode 'client_secret={your_client_secret}'

detailed documentation

Harver API is guarded by rate-limiting. When the allocated rate-limit is exceeded, the API returns HTTP status code 429. (Too many requests).

In the Production and Testing environments, the default limits will be 450 and 300 requests per minute, respectively. There are two new rate-limiting headers added to the responses as bellow.

• Ratelimit-Limit – The request limit for the time period
• Ratelimit-Reset - The time remaining in the current window, specified in seconds

The responses now include a new header called X-Correlation-Id. When submitting a support request, please include this ID.

Submit candidates to Harver in order to invite them to complete the Harver Journey.

Harver can invite the candidate by sending an email to the candidate with a magic link to start the Harver journey

You can also redirect candidates directly to the magic link from the endpoint’s response. The candidate is then immediately logged into Harver.

The attributes allow you to pass your custom list of key-value pairs. You can use this to place for example your IDs like “candidate_id“, “requisition_id”, “source” etc to help you link and sync Harver to your system.

Endpoint:
POST https://api.harver.com/api/v1.0/vacancies/:vacancyId/applications

Header:
Authorization: Bearer {access_token}

Body:

{
  "data": {
    "type": "applications",
    "attributes": {
      "key1": "value1", //Optional key-value pairs
      "key2": "value2", //You can retrieve them with the "ats" include
      "key3": "value3", //with the GET Application request
    },
    "relationships": {
      "candidate": {
        "data": {
          "type": "candidates",
          "attributes": {
            "emailAddress": "candidate@gmail.com", //Mandatory
            "firstName": "CandidateFirstName",  //Mandatory
            "lastName": "CandidateLastName" //Mandatory
          }
        }
      }
    }
  }
}

Response: The response includes the unique Application ID and a Magic-link for the Candidate. payload here

{
    "data": {
        "magicLink": "https://my.harver.com/app/landing/{harver_vacancy_id}/magic-link/{unique_code}",
        "applicationId": "{harver_application_id}"
    }
}

Repeating this request with the same email address will return the same Application ID with renewed Magic-Link.

If your account is set to “Magic-link” based authentication for candidates, you can send this link to your candidates or use it to redirect your candidate to Harver. The Magic-link is valid for 1 hour. A ”Magic Link” is kind of an authenticated URL, which you send to the candidate. This helps them to log in to Harver with just one click of the link without entering username & password. It removes all the friction points that might cause the user to drop out of the application process.

detailed documentation

Return_url parameter

A special attribute can be used when creating a candidate: return_url. That url will be use to redirect the candidate back to, when completed the Harver assessment. This way it is possible to add dynamic attributes to that url.

Example:

{
  "data": {
    "type": "applications",
    "attributes": {
      "return_url": "https:/my-ats.com/welcomeback?candidate_id=12345"
    },
  ...
}

To retrieve an application's relationship data (such as a PDF report, scores etc.), you can make a basic GET applications/{applicationId}, while also providing the include parameter. This include parameter represents a list of comma-separated includes.

Endpoint:
GET https://api.harver.com/api/v1.0/applications/{applicationId}

Header:
Authorization: Bearer {access_token}

Basic response

This part is always available, the rest depends on included modules

"type": "applications",
"id": "{harver_application_id}",
"attributes": {
    "appliedAt": 1630335533,    // timestamp registration
    "completedAt": 1630336749,  // timestamp completed (when completed)
    "status": "new",            // status "new" means completed Harver assessment, and "new" for recruitement
    "progress": {               // Number of modules (incl video & content pages)
        "all": 19,
        "completed": 19
    },
    "matchingScore": 69,        // Overall Matching Score
    "language": "ENG",
    "matchingProfile": {        // Filled when Matching Profile are used in the account
        "bracketId": "great",
        "label": "Green"
    }
},
"relationships": {
    "candidate": {
        "data": {
            "type": "candidates",
            "id": "{harver_application_id}",
            "email": "{email}",
            "attributes": {
                "firstName": "{firstname}",
                "lastName": "{lastname}",
                "email": "{email}"
            }
        }
    },

Get Application ‘include’ modules

• personal-info & additional-info → Candidate personal info and additional questions

• ats → ATS Parameters. These can be your id’s, source parameters, eg like a candidate_id, reqId, utm_source

  -- When the candidate is registered using the API: these are the ones that are sent as key-value attributes in creating the candidates -- When the candidate registers directly in Harver: these are the url parameters

Example:

"included": [
    {
        "type": "ats-parameters",
        "attributes": {
            "candidate_id": "{ats_candidate_id}",
            "job_code": "{ats_job_id}",
            "request_id": "{ats_request_id}",
            "return_url": "https://...",   // url to return the candidate to when completed Harver
        }
    }
]

• report → A link to:
  • Harver PDF report. Generated link that will expire in 15 minutes.
  • Fact Sheet (1 page report). Generated link that will expire in 15 minutes.
  • Candidate Detail Page. You’ll need to have a Harver account, or SSO enabled, to access the Candidate Detail Page. Will not expire.
• matching-results → detailed scores on the modules
• matching-indicators → detailed info on matching indicators (KMI’s) when configured in the account

Example url: https://api.harver.com/api/v1.0/applications/{application_id}?include=report,cover-letter,resume,matching-results,personal-info,additional-info,ats,matching-indicators

Scoring & report information

• Overall Matching score:
  • Module: always available
  • Field: matchingScore
  • This is a numerical 0 - 100 score
• Score label or Band
  • Module: always available if Matching Profiles are configured in Harver Platform.
  • Field: "matchingProfile" → label.
  • This is a label or band that can be configured in the Harver Platform based on the score. Typical examples: “Great Fit” / “Good Fit” / “Bad Fit”, “Passed” / “Failed”, “Red” / “Green”
• Module scores
  • Module: matching-indicators
  • There is a "Included" → "type": "matching-indicators" for each matching indicator
• PDF Report, Factsheet and Candidate result page
  • Module: report
  • A direct link to the Candidate’s PDF report and Factsheet.
  • Note: these links are only available for 15 minutes after requested!
  • The link to the Candidate detail page is a link to Harver. For this an account at Harver is necessary or SSO needs to be enabled. This link does not expire.

detailed documentation

To retrieve a list of the candidates and their applications in a vacancy.

Each candidate has a status. Main statuses:

• in-progress: Registered, but hasn't completed the application process yet.
• new: Application process completed. It is recommended Recommended to filter for this status)
• hired: candidate is hired
• rejected: candidate is rejected

Endpoint:
GET https://api.harver.com/api/v1.0/vacancies/{vacancyId}/candidates

Header:
Authorization: Bearer {access_token}

Useful filter params:

• filter[status]=new
• filter[status-updated-at][since]={epoch_timestamp}

You can combine params like this: ?filter[status]=new**&**filter[status-updated-at][since]=1582211393

After a successful request, the response body will contain the list of (new) Candidates in the Vacancy. Each candidate has an application listed in the “relationships”, this can be used to request the Application Results.

If you need to periodically query newly finished candidates, we suggest using the “[status-updated-at][since]” filter with the Epoch timestamp of the previous query.

List of possible filters:

• filter[status]
• filter[status-updated-at][since]
• filter[status-updated-at][until]
• filter[locations]
• filter[region]
• filter[external_location_id]
• filter[job_function]
• filter[skip_aggregration]

detailed documentation

Webhooks allow you to build or set up integrations which subscribe to certain events in Harver. When one of those events is triggered, we’ll send an HTTP POST payload to the webhook’s configured endpoint. The Harver integrations team can configure the webhooks for you.

Available events:

• ApplicationStarted - A candidate registered at Harver. (Candidate Status: in-progress)
• PersonalInfoWasCreated - A candidate filled in the “Personal information” module. (Candidate Status: in-progress)
• AdditionalInfoWasUpdated - A candidate filled in the “Additional information” module. (Candidate Status: in-progress)
• CandidateStatusNew - A candidate completed the Harver Journey. (Candidate Status = new)

We support NoAuth and Basic Auth (username & password) authentication.

Use the Harver Application Id to get all the details of the application

detailed documentation

• Account - An Account is what holds all of the company specific information within the platform where users of the account can manage settings, Vacancies and Flows.
• Vacancy - Vacancy represents an open position within an company. The Vacancy is where specific information is collected which includes the candidates who wish to apply to that position and their personal information. a Vacancy contains specific information regarding the position for example the location and hours per week the candidate will be expected to work. A vacancy always must have a flow connected to it.
• Flow - A flow is set of assessments modules and content (videos, static texts), created by an Admin in the system. A Flows must be connected to one or multiplee Vacancies.
• Modules or Flow modules - Modules are the separate components used to build a Flow. For instance form for the candidate fill in his/her personal information, a personality questionnaire, multitasking test, etc.
• Matching score - The matching score indicates the extent to which the assessment results of a candidate fit the Vacancy requirements/benchmark. The matching score is calculated based on the combination of results of the different modules that are part of the Flow.
• Candidate - A Candidate represents a person who applied to one or multiple Vacancies.
• Application - A Candidate can apply to multiple Vacancies within an Account. Once a candidate applies to a Vacancy the Application is created.
• Webhooks - Webhooks allow you to build or set up integrations which subscribe to events in Harver. When one of those events is triggered, we’ll send an HTTP POST payload to the webhook’s configured URL.