How do I add the Berke API to my account?

Please contact the HighMatch Customer Success Team to add the Berke API to your account.

What types of payloads can I post?

You can post JSON or form-multipart payloads. We recommend JSON. Each method call has a Try section below the form to demonstrate the various ways to post data to the API.

What is the format of responses from the API?

With one exception, all methods respond with JSON or XML. We recommend JSON. The default is XML (our original format). You can set the response format specifically with the formatOutput paramer. Each method call has a Try section below the form to demonstrate the various ways to use the API. The single exception mentioned earlier is for binary file report retrieval, whose response type is application/pdf.

I don't know my participant's permanent employee ID before the assessment. What should I do?

You can remap a participant's SourceCandidateId to a different value at any time using the UpdateAssessment API method. Once you decide to hire a participant, call UpdateAssessment with the original SourceCandidateId along with the employee's permanent ID in the NewSourceCandidateId field. Do not use Social Security Numbers, bank IDs or other highly sensitive personally-identifiable information here. Berke recommends a badge ID or HRIS ID.

Can I remove assessments from my account?

Call the DeleteAssessment API method to remove incomplete or complete assessments from your account. Delete is permanent and cannot be reversed.

How can I get all of the assessment data in my account?

Call the GetCompletedAssessments API method to page through all of the completed assessments in your account. This method is also suitable for polling for completed results.

Berke added a job to my account or updated an existing job. How do I get the new job fit information for my account?

Anytime Berke adds or updates a job in your account, we automatically recompute all of the job fit data for every assessment in your account. Changes to jobs can have a big impact on job fit data. To retrieve the latest scores, use the GetCompletedAssessments API method to page through all of the completed assessments in your account. Use the SourceJobId value in each job fit record to locate the new or updated job nodes and record the scores in your system.

I want my users to be able to read Berke job fit reports for my participants. Do they need a Berke user account?

No. The anonymous report links returned in the GetCompletedAssessment and GetCompletedAssessments API methods contain a secure, encrypted key that enable anonymous access to a single job fit report. You can distribute the report links to your users for some or all of the job fit results for each assessment. Your users simply click the links and the report will be automatically downloaded to their system. You can also programatically download the reports you want via the GetReportForJob API method.

Note! If your API key changes, all anonymous report links generated with that API key will become invalid. Therefore, do not store these links for long periods of time. They are only appropriate for emailing report links to a non-Berke user. For long-term report integration, use the GetReportForJob method to programatically downloads the reports you request.

Anonymous report links are encrypted and extrememly difficult to guess, but I am uncomfortable with anonymous report access. Can I disable it?

Visit your API Settings (Berke login required) to disable anonymous access to your account's assessment reports. Once disabled, report access must be done via an authenticated GetReportByJob API call or through the Berke Assessment site with a Berke user account. Existing anonymous report links, if previously distributed, will immediately begin requiring a Berke login.

How often can my applications call the Berke API?

API methods, as a whole, can be called a certain number of times per day before HTTP status code 429 is returned. The day-based API method call count is reset at midnight Eastern Standard Time, United States.

Each particular API method can be called a certain number of times within a short-term time frame (e.g. one second) before HTTP status code 429 is returned. For short-term time frames, each API method's calls are counted distinctly from other API methods.

Certain API methods, as a group, have a limit to the number of calls that can be active simultaneously. If the limit is exceeded then HTTP status code 429 is returned.

Thus, API method execution may be denied due to:

  • exceeding overall daily call limits,
  • exceeding short-term calls limits for a time frame for each particular API method,
  • exceeding the number of simultaneous calls allowed simultaneously for a group of particular API methods

Login to see your company's specific API throttle configuration.

Your application can use the following API method response information to determine its course of action when HTTP status code 429 is returned by an API method call:

  • callDeniedDateTime: The date and time that the API method call was denied execution.
  • callExpiresUponCompletion: If this value is true then too many simultaneous calls occurred to a particular group of API methods. If this value is false then too many requests occurred for a particular time frame (daily or short-term).
  • countCallsExceeded: The count of calls that exceeded the maximum number of allowed API calls for the time frame.
  • estimatedMillisecondsToNextAllowedCall: The estimated number of milliseconds, from the callDeniedDateTime, before an API call will be allowed to execute. If callExpiresUponCompletion is true then this value will be zero as the time is dependent on numerous factors. If callExpiresUponCompletion is false then this value indicates the amount of time your application(s) should wait before attempting to make the same API method call. If a daily API call limit has been exceeded the this value indicates the amount of time your application(s) should wait before calling any API method.
  • firstCallDeniedDateTime: The date and time that the first call, of potentially many calls, was denied for the time frame. For example, if an application was denied ten calls within a time frame then firstCallDeniedDateTime indicates date and time that the first of the ten calls was denied.
  • isDailyLimit: If this value is true then the response indicates that the maximum number of API methods calls for the current day has been exceeded. If this value is false then the response indicates that the maximum number of API method calls for a time frame, other than daily, has been exceeded.
  • maximumCallsPerTimeFrame: Indicates the maximum number of times an API method can be called for daily, short-term or simultaneous call limits.
  • timeFrameMilliseconds: Indicates the number of milliseconds in which maximumCallsPerTimeFrame API method calls is allowed.