CreateAssessment Method - Berke Assessment API

Creates a new assessment and returns an XML or JSON document with a unique URL to start the assessment.

Use the SendInvitation method after creating an assessment to invite the participant via email to complete the assessment.

Parameter	Value
apiToken	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.
username	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).
	The user controls the following: Manager Name on all reports comes from user. If OnAssessmentCompleteAction = 2, then the user will automatically receive the participant's assessment report via email. If departments are defined, the user's department will be affiliated with the assessment if sourceDepartmentId is null. All operations and logging are done in the context of the user.
firstName	Required. 1-100 characters.
lastName	Required. 1-100 characters.
sourceCandidateId	Optional. Null or 1-50 characters. SourceCandidateId is not case-sensitive. Identifies the participant in the customer's ATS/HRIS/EPM/etc. Used to assign job fit results back to a participant. This value must be unique. If null, then Berke Assessment will generate a unique id and return it in the XML result. This value can be seen and/or modified in the Berke Assessment site by clicking the Optional Settings button on the Update Assessment User page. Do not use Social Security Numbers, bank IDs or other highly sensitive personally-identifiable information here. Berke recommends a badge ID or HRIS ID.
sourceJobId	Optional. Null or 1-50 characters. SourceJobId is not case-sensitive. If provided, must be previously assigned to a job via the Settings link's API \| Job Assignments (Berke login required) option. Null will use the default company-level job (Berke login required). The most important outcome of this value is the data captured by the assessment. For example, a job that only captures personality data cannot be used to generate match scores for jobs that require talent measures. You can retrieve your sourceJobId values with the GetJobs method.
sourceDepartmentId	Optional. Null or 1-50 characters. SourceDepartmentId is not case-sensitive. Assigns the assessment to a specific department. If provided, value must be previously assigned to a department the Departments (Berke login required) page or via the API. Null defaults to the department assigned to the current API user. The department must be enabled to receive a new assessment.
onAssessmentCompleteAction	Optional. Null, 1 [do nothing], 2 [email Hiring Manager Reports to hiring manager], 4 [email Participant Report to participant], 5 [email report to comma-separated list of addresses]. Defaults to 1 [do nothing]. This value controls what happens after an assessment is complete. If 1, then no further action occurs. If 2, the assessment's default report is emailed to the hiring manager (set by the username parameter). If 4, the Participant Report is emailed to the participant. If the participant does not have an email associated with his/her assessment, the mail operation will be cancelled. If 5 [email report to comma-separated list of addresses], emailReportToList field must also be populated with at least one address. Operations cannot be combined -passing in 6 will not perform 2 and 4.
emailReportToList	Optional. Null or 1-500 characters. If provided, must contain a comma-separated list of one or more well-formed email addresses. The list is required if onAssessmentCompleteAction = 5. If AssessmentCompleteAction is not 5, then the list will be ignored.
onAssessmentCompleteRedirectToUrl	Optional. Null or up to 150 characters. If provided, the candidate will be GET/302 redirected to the URL immediately when his/her assessment is complete. The URL must be absolute, well-formed, and be prefixed with HTTP or HTTPS. If the candidate re-opens his or her assessment after completion, the assessment will continue to redirect to the URL, so you must account for the possibility of multiple visits to the target URL. Tell Me More To identify the candidate returning to your system, the assessment appends two querystring values to the URL: [code], and [id]. [code] is the candidate's [invitationCode] value and [id] is a SHA-512 hash of (sourceCandidateId.trim()+invitationCode.trim()).toLower(). For example, https://eastpointllc.co/assessment/complete will become https://eastpointllc.co/assessment/complete?code=z123456789&id=3af28e12811b5d6eb043f414a95acf4c95edb2a0b7784a4ab8b5 7f5d715f36188948d3a32045b2284885636e61156780abc0cc441d23a1c447e28f9de6df2643 if the candidate's [invitationCode] is "Z12345678" and [sourceCandidateId] is "MySystemId54321". Your system can use the [code] value to lookup the candidate in your system and [id] hash to verify that the inbound URL was sent from Berke Assessment. [id] is the SHA-512 hash of mysystemid54321z12345678. To disable adding the [code] and [id] querystring pairs to your URL, add #nokey to the end of your URL. For example, HTTPS://eastpointllc.co/assessment/complete#nokey will will suppress the [code] and [id] querystring pairs.
phoneNumber	Optional. Null or 1-50 characters. If recorded, Phone Number can be displayed on report covers.
emailAddress	Optional. Null or 1-100 characters. If provided, must be a well-formed email address. If you do not provide this value, automated reminder emails will not be sent to your participant. The completeWithinDays value controls the reminder schedule. Review the Personalization \| Assessment settings page (Berke login required) for more details.
completeWithinDays	Optional. Null, 0, or 2 to 21. This value controls the reminder schedule for emailing participants who have not completed the assessment. If null, the default value specified in the Personalization \| Assessment settings page (Berke login required) will be used. If 0, then reminders will not be sent. This value is only used if the assessment includes a valid email address. Once the CompleteWithinDays period has elapsed, the assessment will remain active, but no further reminders will be sent.
emailMessage	Optional. Null/empty or 1-1000 characters. This value will be included in assessment reminder messages sent to the participant. If null/empty, the default invitation message specified in the Personalization \| Assessment settings page (Berke login required) will be used. Submit a single non-whitespace character to disable the default invitation message (any single character, such as "." or "-" will disable the default message). HTML markup is prohibited. To avoid spam blockers, do not use exclamation points or PHRASES IN CAPS.
formatOutput	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">
  <assessment sourceCandidateId="[sourceCandidateId]" invitationCode="[invitationCode]" assessmentUrl="https://example.assessment.url/[invitationCode]" />
</berkeResponse>

{
  "assessment": {
    "sourceCandidateId": "[sourceCandidateId]",
    "invitationCode": "[invitationCode]",
    "assessmentUrl": "https://example.assessment.url/[invitationCode]"
  },
  "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

Success [200]

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 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.

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
Failure [!=200]	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
Department Not Found [403.1034])	HTTP error code 403.1034 sourceDepartmentId was not found.
Department Not Enabled [403.1035])	HTTP error code 400.1035 Department (sourceDepartmentId) to which this assessment is assigned is not enabled. Assessments in disabled departments cannot be created, modified, or accessed via the API.
API Request Limit Exceeded [429.1046]	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-22T20:47:13.8469037Z] to [2024-11-22T20:47:14.4469037Z]." responseCode="429" callDeniedDateTime="2024-11-22T20:47:14.5469037Z" callExpiresOnCompletion="true" countCallsExceeded="3" estimatedMillisecondsToNextAllowedCall="423" firstCallDeniedDateTime="2024-11-22T20:47:14.2469037Z" isDailyLimit="false" maximumCallsPerTimeFrame="120" timeFrameMilliseconds="60000" /> { "callDeniedDateTime": "2024-11-22T20:47:14.5469037Z", "callExpiresOnCompletion": true, "countCallsExceeded": 3, "estimatedMillisecondsToNextAllowedCall": 423, "firstCallDeniedDateTime": "2024-11-22T20:47:14.2469037Z", "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-22T20:47:13.8469037Z] to [2024-11-22T20:47:14.4469037Z].", "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.