Returns an XML or JSON document describing all completed assessments and job fit results for a given datespan. Use the GetCompletedAssessment method to retrieve results for a single assessment.

Parameter Value
Required. 1-50 characters. Case-sensitive. Visit Settings | API:Security to change your API token (Berke login required). Your API token is a server-side authentication value. Do not embed it in client-side Javascript or submit it to Berke via an insecure connection.
Optional. Null or 1-50 characters. Your API Token is mapped to a default user. Use this field to change from the default API user to a specific user. The user must exist in your Berke account and is active. Null defaults to default API user. Visit Settings | API:Security to change your default API user (Berke login required).

Optional. Null or decimal-numeric. Defaults to 1/1/1970. Must be formatted in Unix time offset to UTC. Visit EpochConverter.com for a demonstration and code samples for converting to/from UTC Unix time.

  • Current Time: 12/19/2018 8:56:37 AM Eastern Standard Time
  • Current Time UTC: 12/19/2018 1:56:37 PM UTC
  • Current Time Unix UTC: 1545227797.8785

Optional. Null or decimal-numeric. Defaults to the current date and time. Must be formatted in Unix time offset to UTC. Visit EpochConverter.com for a demonstration and code samples for converting to/from UTC Unix time.
Optional. Null or numeric. Defaults to 1.
Optional. Defaults to first value in list if not supplied. This value sets format in which to return the results of the method. All formats return the same data and hierarchical layout.
<?xml version="1.0" encoding="utf-16"?>
<berkeResponse status="ok" responseCode="200">
  <assessments dateFromUtc="1545227797.8785" dateToUtc="1545227797.8785" totalAssessments="2" currentPageAssessments="2" currentPage="1" totalPages="1" maxAssessmentsPerPage="50">
    <assessment sourceCandidateId="[sourceemployeeid_1]" firstName="First1" lastName="Last1" formalTitle="Unspecified" completedOnUtc="1545227797.8785">
      <jobFit job="[jobName_1]" fitPct="0.99" fitId="3" fit="High" isPrimaryJob="true" sourceJobId="[sourceJobId_1]" reportUrl="https://example.assessment.url/rpt/K82GE6AZYE63XVRSG6BRJDFUHH" fitComputedOnUtc="1545227797.8784962" />
      <jobFit job="[jobName_2]" fitPct="0.65" fitId="2" fit="Medium" isPrimaryJob="false" sourceJobId="[sourceJobId_2]" reportUrl="https://example.assessment.url/rpt/SS9CANXGD32BDPG5NM2PEG3HW5" fitComputedOnUtc="1545227797.8784962" />
      <jobFit job="[jobName_3]" fitPct="0.32" fitId="1" fit="Low" isPrimaryJob="false" sourceJobId="[sourceJobId_3]" reportUrl="https://example.assessment.url/rpt/54K8JB64CCWPJ6XJC2QTDS9FPW" fitComputedOnUtc="1545227797.8784962" />
      <jobFit job="[jobName_4]" fitPct="-1" fitId="4" fit="Match Disabled In Job" isPrimaryJob="false" sourceJobId="[sourceJobId_4]" reportUrl="https://example.assessment.url/rpt/63HTU8SF655RF7YXULWB3S7YWW" fitComputedOnUtc="1545227797.8784962" />
      <jobFit job="[jobName_5]" fitPct="-1" fitId="5" fit="Not Enough Assessment Data" isPrimaryJob="false" sourceJobId="[sourceJobId_5]" reportUrl="" fitComputedOnUtc="1545227797.8784962" />
    </assessment>
    <assessment sourceCandidateId="[sourceemployeeid_2]" firstName="First2" lastName="Last2" formalTitle="Unspecified" completedOnUtc="1545227797.8785">
      <jobFit job="[jobName_1]" fitPct="0.99" fitId="3" fit="High" isPrimaryJob="true" sourceJobId="[sourceJobId_1]" reportUrl="https://example.assessment.url/rpt/K82GE6AZYE63XVRSG6BRJDFUHH" fitComputedOnUtc="1545227797.8784962" />
      <jobFit job="[jobName_2]" fitPct="0.65" fitId="2" fit="Medium" isPrimaryJob="false" sourceJobId="[sourceJobId_2]" reportUrl="https://example.assessment.url/rpt/SS9CANXGD32BDPG5NM2PEG3HW5" fitComputedOnUtc="1545227797.8784962" />
      <jobFit job="[jobName_3]" fitPct="0.32" fitId="1" fit="Low" isPrimaryJob="false" sourceJobId="[sourceJobId_3]" reportUrl="https://example.assessment.url/rpt/54K8JB64CCWPJ6XJC2QTDS9FPW" fitComputedOnUtc="1545227797.8784962" />
      <jobFit job="[jobName_4]" fitPct="-1" fitId="4" fit="Match Disabled In Job" isPrimaryJob="false" sourceJobId="[sourceJobId_4]" reportUrl="https://example.assessment.url/rpt/63HTU8SF655RF7YXULWB3S7YWW" fitComputedOnUtc="1545227797.8784962" />
      <jobFit job="[jobName_5]" fitPct="-1" fitId="5" fit="Not Enough Assessment Data" isPrimaryJob="false" sourceJobId="[sourceJobId_5]" reportUrl="" fitComputedOnUtc="1545227797.8784962" />
    </assessment>
  </assessments>
</berkeResponse>
{
  "assessments": {
    "dateFromUtc": "1545227797.92537",
    "dateToUtc": "1545227797.92537",
    "totalAssessments": 2,
    "currentPageAssessments": 2,
    "currentPage": 1,
    "totalPages": 1,
    "maxAssessmentsPerPage": 50,
    "assessment": [
      {
        "sourceCandidateId": "[sourceemployeeid_1]",
        "firstName": "First1",
        "lastName": "Last1",
        "formalTitle": "Unspecified",
        "completedOnUtc": "1545227797.92537",
        "jobFit": [
          {
            "job": "[jobName_1]",
            "fitPct": 0.99,
            "fitId": 3,
            "fit": "High",
            "isPrimaryJob": true,
            "sourceJobId": "[sourceJobId_1]",
            "reportUrl": "https://example.assessment.url/rpt/K82GE6AZYE63XVRSG6BRJDFUHH",
            "fitComputedOnUtc": 1545227797.9253712
          },
          {
            "job": "[jobName_2]",
            "fitPct": 0.65,
            "fitId": 2,
            "fit": "Medium",
            "isPrimaryJob": false,
            "sourceJobId": "[sourceJobId_2]",
            "reportUrl": "https://example.assessment.url/rpt/SS9CANXGD32BDPG5NM2PEG3HW5",
            "fitComputedOnUtc": 1545227797.9253712
          },
          {
            "job": "[jobName_3]",
            "fitPct": 0.32,
            "fitId": 1,
            "fit": "Low",
            "isPrimaryJob": false,
            "sourceJobId": "[sourceJobId_3]",
            "reportUrl": "https://example.assessment.url/rpt/54K8JB64CCWPJ6XJC2QTDS9FPW",
            "fitComputedOnUtc": 1545227797.9253712
          },
          {
            "job": "[jobName_4]",
            "fitPct": -1.0,
            "fitId": 4,
            "fit": "Match Disabled In Job",
            "isPrimaryJob": false,
            "sourceJobId": "[sourceJobId_4]",
            "reportUrl": "https://example.assessment.url/rpt/63HTU8SF655RF7YXULWB3S7YWW",
            "fitComputedOnUtc": 1545227797.9253712
          },
          {
            "job": "[jobName_5]",
            "fitPct": -1.0,
            "fitId": 5,
            "fit": "Not Enough Assessment Data",
            "isPrimaryJob": false,
            "sourceJobId": "[sourceJobId_5]",
            "reportUrl": "",
            "fitComputedOnUtc": 1545227797.9253712
          }
        ]
      },
      {
        "sourceCandidateId": "[sourceemployeeid_2]",
        "firstName": "First2",
        "lastName": "Last2",
        "formalTitle": "Unspecified",
        "completedOnUtc": "1545227797.92537",
        "jobFit": [
          {
            "job": "[jobName_1]",
            "fitPct": 0.99,
            "fitId": 3,
            "fit": "High",
            "isPrimaryJob": true,
            "sourceJobId": "[sourceJobId_1]",
            "reportUrl": "https://example.assessment.url/rpt/K82GE6AZYE63XVRSG6BRJDFUHH",
            "fitComputedOnUtc": 1545227797.9253712
          },
          {
            "job": "[jobName_2]",
            "fitPct": 0.65,
            "fitId": 2,
            "fit": "Medium",
            "isPrimaryJob": false,
            "sourceJobId": "[sourceJobId_2]",
            "reportUrl": "https://example.assessment.url/rpt/SS9CANXGD32BDPG5NM2PEG3HW5",
            "fitComputedOnUtc": 1545227797.9253712
          },
          {
            "job": "[jobName_3]",
            "fitPct": 0.32,
            "fitId": 1,
            "fit": "Low",
            "isPrimaryJob": false,
            "sourceJobId": "[sourceJobId_3]",
            "reportUrl": "https://example.assessment.url/rpt/54K8JB64CCWPJ6XJC2QTDS9FPW",
            "fitComputedOnUtc": 1545227797.9253712
          },
          {
            "job": "[jobName_4]",
            "fitPct": -1.0,
            "fitId": 4,
            "fit": "Match Disabled In Job",
            "isPrimaryJob": false,
            "sourceJobId": "[sourceJobId_4]",
            "reportUrl": "https://example.assessment.url/rpt/63HTU8SF655RF7YXULWB3S7YWW",
            "fitComputedOnUtc": 1545227797.9253712
          },
          {
            "job": "[jobName_5]",
            "fitPct": -1.0,
            "fitId": 5,
            "fit": "Not Enough Assessment Data",
            "isPrimaryJob": false,
            "sourceJobId": "[sourceJobId_5]",
            "reportUrl": "",
            "fitComputedOnUtc": 1545227797.9253712
          }
        ]
      }
    ]
  },
  "status": "ok",
  "response": null,
  "responseCode": "200"
}
<?xml version="1.0" encoding="utf-16"?>
<berkeResponse status="[!=ok]" response="[Error Message], [Parameter]=[[ParameterValue]]" responseCode="[!=200]" />
{
  "status": "[!=ok]",
  "response": "[Error Message], [Parameter]=[[ParameterValue]]",
  "responseCode": "[!=200]"
}
Successful Example Response

            
  • The assessments node includes the following attributes:
    • dateFromUtc and dateToUtc are UTC Unix datetime values. All active, completed assessments in your account will be included in this datespan. dateFromUtc defaults to 0 (1/1/1970) and dateToUtc defaults to current server time.
    • totalAssessments is the total number of completed assessments between the dateFromUtc and dateToUtc values.
    • currentPageAssessments is the number of assessment nodes on the current page.
    • currentPage is the page number you requested. currentPage defaults to 1.
    • totalPages is the number of pages of completed assessments between the dateFromUtc and dateToUtc values. If totalPages is greater than 1, then you need to query for each page to retrieve all completed assessments in the requested datespan.
    • maxAssessmentsPerPage is the maximum number of completed assessments returned per page.
  • The assessments node contains 0 to n assessment nodes. Each assessment node represents an assessment that was completed during the requested datespan.
  • assessment nodes include the following attributes:
    • sourceCandidateId is the ID you optionally set when creating the assessment. Values beginning with berke_ were set by Berke Assessment because sourceCandidateId was blank when created. sourceCandidateId is always unique.
    • firstName, lastName, and formalTitle form the name the participant set while taking the assessment.
    • completedOnUtc is the UTC Unix datetime when the participant completed the assessment.
  • assessment nodes contain one jobFit node for each active job in your account.
  • jobFit nodes include the following attributes:
    • job is the name of a job.
    • fitPct describes numerically how highly the participant matches the job. This value will be -1 for jobs where matching is disabled, unavailable due to a lack of necessary data to perform a job fit, or because the assessment is not complete.
    • fitId describes how well the participant matches the job. Values include:
      • 0 = Not calculated yet, assessment is incomplete
      • 3 = High fit (67-100)
      • 2 = Medium fit (34-66)
      • 1 = Low fit (0-33)
      • 5 = Not enough data, more assessment sections are required
      • 4 = Job is not configured for fit scoring
    • fit is a label describing how well the participant matches the job. If the job is not configured for matching or the participant did not take enough assessment sections to compute a match, that information will be noted here as well.
    • isPrimaryJob is a boolean value that indicates whether the job is assigned to the assessment or if this is a score for another job in your account. Berke scores both the primary job and all additional jobs in your account for all candidates. If you only need the candidate's primary job, ignore all scores where isPrimaryJob=false.
    • sourceJobId maps the Berke Job to a job in your ATS/HRIS/EPM/etc. system. Use the job assignment feature (Berke login required) in the Berke Assessment site to set the value. sourceJobId values are either empty or unique.
    • reportUrl is URL an unauthenticated, non-Berke user can use to download a report for an assessment/job fit combination. This URL requires no authentication beyond the encrypted hash at the end. The purpose is to enable simple email distribution of the report to users without a Berke Assessment management account. You can disable unauthenticated report access via your API Settings (Berke login required). If disabled, all report retrieval must be done via the authenticated GetReportForJob method API method call or from the Berke Assessment site. You do not need to immediately retrieve the job reports. Job reports can be requested any time. 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.
    • fitComputedOn describes the UTC date and time when the match value was computed. If you are recording scores in your system, you can use this value to determine whether to update your score data. The value is expressed in Unix time .

Handing Errors

All API requests include two extended HTTP headers in the response:

  • X-Response-Code
    Contains the HTTP status code (400, 200, etc.) and a Berke status code.
    The format is [Http Status Code].[Berke Status Code].
  • X-Response-Message
    Contains a message describing the X-Response-Code header.

If your request was successful, X-Response-Code will be 200.0. If the Berke response code is 1000 or greater, then an error occurred. For example, 403.1003 tells you that there was a HTTP 403 error (Forbidden). The 1003 Berke status code tells you the API key is invalid.

When an error occurs, further information can be found in the X-Response-Message header. For example, X-Response-Message will return API key '[API.Key.Sent.To.Berke]' is invalid or inactive if the API key was not authenticated.

The most common errors returned for this method are listed below.

Status Code Failed Example Responses

                
Most API exceptions are due to invalid parameters. Review the notes below each parameter as well as the output and HTTP response code from the error message. If all values are appropriate, the failure is likely authentication-related. Authentication failure types include, but are not limited to,:
  • Too many failed calls
  • Maximum per minute or per day API calls reached
  • API call made via insecure connection
  • Invalid API key
  • API is not enabled for target company
  • API is disabled for all companies (typically during maintenance)
  • Company is inactive or expired
  • Invalid username
  • User is inactive or expired
  • Invalid date value. All dates must be expressed in UNIX time offset to UTC.
  • Requested page exceeds the number of pages returned by the date span.
Most API exceptions are due to invalid parameters. Review the notes below each parameter as well as the output and HTTP response code from the error message. If all values are appropriate, the failure is likely authentication-related. Authentication failure types include, but are not limited to,:
  • Too many failed calls
  • Maximum per minute or per day API calls reached
  • API call made via insecure connection
  • Invalid API key
  • API is not enabled for target company
  • API is disabled for all companies (typically during maintenance)
  • Company is inactive or expired
  • Invalid username
  • User is inactive or expired
  • Unknown sourceJobId - check your API job assignments in the primary Berke customer site
  • Invalid assessment complete action

        
<?xml version="1.0" encoding="utf-16"?>
<berkeResponse status="[!=ok]" response="[API Method] API method requests exceeded burst limit of 120 occurrences within 60000 milliseconds. Excess requests occurred 3 times from [2018-12-19T13:56:37.2409962Z] to [2018-12-19T13:56:37.8409962Z]." responseCode="429" callDeniedDateTime="2018-12-19T13:56:37.9409962Z" callExpiresOnCompletion="true" countCallsExceeded="3" estimatedMillisecondsToNextAllowedCall="423" firstCallDeniedDateTime="2018-12-19T13:56:37.6409962Z" isDailyLimit="false" maximumCallsPerTimeFrame="120" timeFrameMilliseconds="60000" />
{
  "callDeniedDateTime": "2018-12-19T13:56:37.9409962Z",
  "callExpiresOnCompletion": true,
  "countCallsExceeded": 3,
  "estimatedMillisecondsToNextAllowedCall": 423,
  "firstCallDeniedDateTime": "2018-12-19T13:56:37.6409962Z",
  "isDailyLimit": false,
  "maximumCallsPerTimeFrame": 120,
  "timeFrameMilliseconds": 60000,
  "status": "[!=ok]",
  "response": "[API Method] API method requests exceeded burst limit of 120 occurrences within 60000 milliseconds. Excess requests occurred 3 times from [2018-12-19T13:56:37.2409962Z] to [2018-12-19T13:56:37.8409962Z].",
  "responseCode": "429"
}
API requests exceeded the maximum allowed per time-frame or the maximum allowed at any point in time.

API throttle limits are set per-company. Please login and return to this area to see your company's specific 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.