Stores optional custom data for an assessment. Assessment custom data consists of one or more keys where each key has an associated data type, one or more values and an optional label. See the customData parameter below for additional details.

Each time you call SetAssessmentCustomData for an assessment:
  • keys in the payload that do not already exist for the assessment will have their values added to the assessment's custom data.
  • keys in the payload that already exist for the assessment will have their values updated.
  • keys not in the payload that already exist for the assessment will not have their values changed.
  • keys in the payload that have a zero-length array value will be removed from the assessment's custom data.

Use the GetAssessmentCustomData method to retrieve an assessment's custom data that was set by the SetAssessmentCustomData method. Use the DeleteAssessmentCustomData method to delete an assessment's custom data that was set by the SetAssessmentCustomData method.

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).
Required. 1-50 characters. Not case-sensitive. Source identifier of the participant in the customer's ATS/HRIS/EPM/etc. Used to look up the scores for an assessment. 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.
Required. Contains the assessment's custom values as either a JSON array or a series of XML nodes depending on the post type. For posting JSON, array members are JSON objects each with the following properties. For posting XML, use a series of one or more <CustomData> nodes each containing nodes named and described below.
  • Key: a string value that identifies the value. Key is mandatory, must not be null, must not be the empty string and must not consist of only whitespace.
  • Type: a type identifier that defines the value's data type. Type is optional. If Type is not supplied or is null, empty or whitespace then Type defaults to Text.
  • Value: the custom data item's value(s). Value is mandatory.
    When posting JSON:
    • Value may be null, a single value or an array of zero or more values.
    • To remove value(s) use a zero length array, i.e. Value: []
    When posting XML:
    • A <Value> node contains a single value. When posting an array of values, the <Value> nodes are siblings.
    • A <Values> node can be used to contain zero or more <Value> nodes. The <Values> node is only required if you are removing value(s). To remove value(s) use <Values />
    • At least one of nodes <Values> or <Value> must be present.
    • Use <Value xsi:nil="true" /> or <Value nil="true" /> to supply a null value.
    • The request payload's root XML node, <request>, must not include the namespace attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" or any namespace attribute or an error will occur.
    A non-null value must be convertible to its Type, otherwise a default value will be used.
  • Label: a string value that can be used to label or identify the value in output.
Type indicates the value's data type. Type is optional. If Type is supplied then it must be one of the following:
  • Boolean: Value is a boolean represented as true, false, "true" or "false". Other values evaluate to false.
  • DateTime: Value is a date and time represented by a string parseable by Microsoft .NET DateTimeOffset.TryParse method according to en-US culture, or a decimal value containing a Unix time offset to UTC. Visit DateTimeOffset.TryParse for additional information regarding date and time string representation. Visit EpochConverter.com for a demonstration and code samples for converting to/from UTC Unix time. Other values evaluate to 1/1/0001 12:00:00 AM +00:00.
  • Number: Value is a numeric value represented by a number or string parseable as a number. Value must be in the range ±5.0 × 10−324 to ±1.7 × 10308. Other values evaluate to zero (0).
  • PhoneNumber: Value is a phone number represented by a string or number. A phone number may take any form and contain 0 to 1000 characters. A null phone number or one longer than 1000 characters evaluates to an empty string.
  • PostalCode: Value is a postal code represented by a string or number parseable as a postal code for the United States, Canada or Mexico. Other values will still be stored, but a warning will be indicated in the response.
  • Text: Value is a single line of text not containing line break information. If value is an object, array, boolean or number then it is converted to its string representatation when used. Text may contain 0 to 1000 characters. A null value or text longer than 1000 characters evaluates to an empty string.
  • TextBlock: Value is text that may contain line break information. If value is an object, array, boolean or number then it is converted to its string representatation when used. A TextBlock may contain 0 to 1000 characters. A null value or text longer than 1000 characters evaluates to an empty string.

If Type is not supplied or is null, empty or whitespace then Type defaults to Text.

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">
  <assessmentCustomData changeSummary="Custom data set for sourceCandidateId '[sourceCandidateId]'." sourceCandidateId="[sourceCandidateId]" />
</berkeResponse>
{
  "assessmentCustomData": {
    "changeSummary": "Custom data set for sourceCandidateId '[sourceCandidateId]'.",
    "sourceCandidateId": "[sourceCandidateId]"
  },
  "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 

        		
    

    


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:17:18.4119667Z] to [2024-11-22T09:17:19.0119667Z]." responseCode="429" callDeniedDateTime="2024-11-22T09:17:19.1119667Z" callExpiresOnCompletion="true" countCallsExceeded="3" estimatedMillisecondsToNextAllowedCall="423" firstCallDeniedDateTime="2024-11-22T09:17:18.8119667Z" isDailyLimit="false" maximumCallsPerTimeFrame="120" timeFrameMilliseconds="60000" />

            
{
  "callDeniedDateTime": "2024-11-22T09:17:19.1119667Z",
  "callExpiresOnCompletion": true,
  "countCallsExceeded": 3,
  "estimatedMillisecondsToNextAllowedCall": 423,
  "firstCallDeniedDateTime": "2024-11-22T09:17:18.8119667Z",
  "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:17:18.4119667Z] to [2024-11-22T09:17:19.0119667Z].",
  "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.
        
    •