Retrieves a participant's assessment status using the assessment's Source Candidate ID or Invitation Code.

If the assessment's status is complete (StatusId=2), you can follow up with a call to the GetCompletedAssessment method to retrieve the assessment's job fit scores.

If you do not have the participant's SourceCandidateId, you can use this method to lookup the SourceCandidateId if you have the InvitationCode. Once you have the SourceCandidateId, you can perform additional calls to other API methods to retrieve reports and scores.

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).
Null or 1-50 characters. Not case-sensitive. Source ID of the assessment participant in the customer's ATS/HRIS/EPM/etc. This value is assigned when an assessment is created. Existing SourceCandidateId values can be seen and/or modified in the Berke Assessment site by clicking the Optional Settings button on the Update Assessment User page. If is null, then you must supply the field. If is not null, then will be ignored , even if you supply a value.
Null or 1-50 characters. Not case-sensitive. The code assigned by Berke to start an assessment. These unique codes are found in the start URL and never repeat. If null, you must supply the field. If is not null, will be ignored, even if you supply a value.
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">
  <assessmentStatus sourceCandidateId="[sourceCandidateId]" status="[status]" statusId="0" jobFitScoresAvailable="true" firstName="[firstName]" lastName="[lastName]" formalTitle="[formalTitle]" invitationCode="[invitationCode]" assessmentUrl="https://example.assessment.url/[invitationCode]" percentComplete="0" createdOnUtc="1732267676.568" startedOnUtc="1732267676.568" completedOnUtc="1732267676.568" startCount="0" phoneNumber="[phoneNumber]" emailAddress="[endReminder@Here.com]" remindUntilUtc="1733477276.568" onAssessmentCompleteRedirectToUrl="[https://yourDomainHere.com]?code=[invitationCode]&amp;id=[sha512Hash]" />
</berkeResponse>
{
  "assessmentStatus": {
    "sourceCandidateId": "[sourceCandidateId]",
    "status": "[status]",
    "statusId": 0,
    "jobFitScoresAvailable": true,
    "firstName": "[firstName]",
    "lastName": "[lastName]",
    "formalTitle": "[formalTitle]",
    "invitationCode": "[invitationCode]",
    "assessmentUrl": "https://example.assessment.url/[invitationCode]",
    "percentComplete": 0,
    "createdOnUtc": 1732267676.584,
    "startedOnUtc": 1732267676.584,
    "completedOnUtc": 1732267676.584,
    "startCount": 0,
    "phoneNumber": "[phoneNumber]",
    "emailAddress": "[endReminder@Here.com]",
    "remindUntilUtc": 1733477276.584,
    "onAssessmentCompleteRedirectToUrl": "[https://yourDomainHere.com]?code=[invitationCode]&id=[sha512Hash]"
  },
  "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 assessmentStatus node includes the following attributes:
                
      
                        
    • 
                            The sourceCandidateId attribute is either the value you passed in or a unique value
                            created by Berke if the value was omitted. This value is required in subsequent
                            API calls to update or cancel assessments.
                        
      • 
                    
    • 
                        The status attribute is a label that describes whether an assessment is not started,
                        in progress (but not necessarily in progress in real time), or complete.
                    
      • 
                    
    • 
                        The status Id attribute is the value you should use to determine whether an assessment
                        is complete. Do not use percent complete or the status label. statusId will be one of
                        the following values:
                        
        
                            
      • 
                                5
                                = Not Started
                            
        • 
                            
      • 
                                1
                                = In Progress
                            
        • 
                            
      • 
                                2
                                = Complete
                            
        • 
                        
      
                    
      • 
                    
    • 
                        The jobFitScoresAvailable attribute is a boolean value that indicates whether
                        the candidate's assessment is complete and the scores/report links are ready.
                    
      • 
                    
    • 
                        The firstName and lastName attributes are the values set by the candidate when
                        taking the assessment.
                    
      • 
                    
    • 
                        The invitationCode attribute is the unique serial number that starts the assessment
                        for a participant. You will note that it is also found at the end of the assessmentUrl
                        invitationCode. The value is separated in the event you want participants to manually
                        start the assessment. To manually start, participants go to the assessment
                        site and manually key the invitation code. To avoid transcription errors, we recommend
                        using the assessmentUrl instead. Manual starts are typically used when a participant
                        does not have an email address, if the assessment invitation is being printed instead
                        of mailed, or if the assessment is delivered in a proctored environment.
                    
      • 
                    
    • 
                        The assesmentUrl is a direct deep link to the assessment site that will automatically
                        launch the assessment when presented to a participant. This is the recommended method
                        for starting the assessment. You will note that the url ends with the invitationCode
                        attribute. This attribute will be empty after the assessment is completed.
                    
      • 
                    
    • 
                        The percentComplete attribute is a value between 0 and 100 that describes how far along
                        the participant is in the assessment process. Completion percentage is measured by
                        average time to complete the sections in the assessment, rather than simply by dividing
                        the number of sections in the assessment.
                    
      • 
                    
    • 
                        The createdOnUtc attribute describes the UTC date and time when the assessment was
                        created. The value is expressed in
                        
                            Unix time
                        .
                    
      • 
                    
    • 
                        The startedOnUtc attribute describes the UTC date and time when the assessment was
                        started. This value will be empty if the assessment has not been started. The value
                        is expressed in Unix time.
                    
      • 
                    
    • 
                        The completedOnUtc attribute describes the UTC date and time when the assessment
                        was completed. This value will be empty if the assessment has not been started or
                        is in progress. The value is expressed in
                        
                            Unix time
                        .
                    
      • 
                    
    • 
                        The startCount attribute shows the number of times the participant has started the
                        assessment. This value can indicate a technical problem or a participant who is
                        deliberately restarting to attempt to improve his or her results. We recommend asking
                        users whether they need technical assistance if the start count is above 3.
                    
      • 
                    
    • 
                        If populated, the emailAddress attribute will be used to occasionally remind the participant
                        to complete the assessment until the reminder expires (see remindUntilUtc attribute). If emailAddress
                        is null, reminders will not be sent.
                    
      • 
                    
    • 
                        The remindUntilUtc attribute describes the UTC date and time through which
                        the participant will receive occasional reminders to complete the assessment. The value is expressed
                        in Unix time. If the value is 0,
                        the value is in the past, or emailAddress is empty/invalid, then reminders will not be sent. If reminders
                        have expired, you can restart the reminder by calling the UpdateAssessment method and setting
                        the newCompleteWithinDays value.
                    
      • 
                    
    • 
                        The onAssessmentCompleteRedirectToUrl attribute shows the URL to which the candidate will be directed
                        when the assessment is complete. If null, the standard Berke completion page will be shown.
                    
      • 
                
    
            
    • 
        

    


        		
    

    


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 
    • 
                
  • Unknown source candidate id
    • 
        

    


        		
    

    

        
            )
    
    
        
        

            
        

    		
    

    

        
            )
        
        
            
            

                
            

        		
    

    

        
            )
        
        
            
            

                
            

        		
    

    

        
            )
        
        
            
            

                Department (sourceDepartmentId) to which this assessment is assigned is not enabled. Assessments in disabled departments cannot be created, modified, or accessed via the API.
            

        		
    



    
        
    
    

            

            

                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 [2024-11-22T09:27:55.8839559Z] to [2024-11-22T09:27:56.4839559Z]." responseCode="429" callDeniedDateTime="2024-11-22T09:27:56.5839559Z" callExpiresOnCompletion="true" countCallsExceeded="3" estimatedMillisecondsToNextAllowedCall="423" firstCallDeniedDateTime="2024-11-22T09:27:56.2839559Z" isDailyLimit="false" maximumCallsPerTimeFrame="120" timeFrameMilliseconds="60000" />

            
{
  "callDeniedDateTime": "2024-11-22T09:27:56.5839559Z",
  "callExpiresOnCompletion": true,
  "countCallsExceeded": 3,
  "estimatedMillisecondsToNextAllowedCall": 423,
  "firstCallDeniedDateTime": "2024-11-22T09:27:56.2839559Z",
  "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 [2024-11-22T09:27:55.8839559Z] to [2024-11-22T09:27:56.4839559Z].",
  "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.
        
    •