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.
sourceCandidateId
Required, 1-50 characters. SourceCandidateId is not case-sensitive.
Identifies the participant in the customer's
ATS/HRIS/EPM/etc. This value must be unique for each candidate. Once set, use the
UpdateAssessment method to change SourceCandidateId.
This value can be seen 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
in the SourceCandidateId field. Berke recommends a badge ID, HRIS ID, ATS ID, etc.
emailAddress
Required. Must be a well-formed email address. The participant will receive assessment
invitations and reminders at this address. Note that email address is not used
as an ID of any sort and does not have to be unique.
phoneNumber
Optional. Null or 1-50 characters. If recorded, Phone Number can be displayed on report covers.
firstName
Required the first time you call PerformAssessment for a given SourceCandidateId, optional thereafter. 1-100 characters. If passed on subsequent calls
for a given SourceCandidateId, the First Name will be updated.
lastName
Required the first time you call PerformAssessment for a given SourceCandidateId, optional thereafter. 1-100 characters. If passed on subsequent calls
for a given SourceCandidateId, the Last Name will be updated.
sourceJobId
Optional. Null or 1-50 characters. SourceJobId is not case-sensitive. This value is
only
recorded the first time you call PerformAssessment for a given SourceCandidateId; changing SourceJobId on
subsequent calls will create an error response. If SourceJobId is provided, it 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. If passed on subsequent calls
for a given SourceCandidateId, the SourceDepartmentId will be updated.
fromFullName
Optional. Null or 1-100 characters. Used when sending assessment invitations. If null, the full name of the participant's hiring manager will be used.
replyToAddress
Optional. Null or 1-100 characters. Used when sending assessment invitations. If provided, must be a well-formed email address.
If null, the email address of the participant's hiring manager will be used.
emailMessage
Optional. Null/empty or 1-1000 characters. This value will be included in email invitations and 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
if a previous invitation message is not already recorded on the assessment.
Submit a single non-whitespace character to disable the default invitation message (any single character, such as "." or "-" will disable the default message).
Submit "default" to force the message to use latest default message configuration (which overrides all previous invitation messages).
HTML markup is prohibited. To avoid spam blockers, do not use exclamation points or PHRASES IN CAPS.
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.
If passed on subsequent calls for a given SourceCandidateId, the OnAssessmentCompleteRedirectToUrl will be updated.
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, if the candidate's [invitationCode] is "Z12345678" and [sourceCandidateId] is "MySystemId54321", the on-complete URL target
https://eastpointllc.co/assessment/complete will become
https://eastpointllc.co/assessment/complete?code=Z12345678
&id=a93be9cb4f8f84133fb4457aeeca93f1be339bfb33c555574b792db55
8b20f24ff2712ade45633e36ec625df1401aaf23ce0246402af91809272e3953dfa4ac1
.
Your system can use the [code] querystring 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 If you do not have the [code] value stored in your system, you can pass [code]
as the invitationCode parameter to the GetAssessmentStatus method to retrieve the [sourceCandidateId].
To disable adding the [code] and [id] querystring pairs to your on-complete URL, append #nokey to the URL.
For example, https://eastpointllc.co/assessment/complete#nokey will
will suppress the [code] and [id] querystring pairs.
You can optionally include the sourceCandidateId value in your URL by explicitly adding it to your URL with the {{sourceCandidateId}} tag.
For example, https://eastpointllc.co/assessment/complete?sourceId={{sourceCandidateId}}#nokey will become
https://eastpointllc.co/assessment/complete?sourceId=MySystemId54321 . Note that the [id] querystring hash is built using a combination
of the invitationCode and the sourceCandidateId, so the hash will be less secure if you include sourceCandidateId. Using an HTTPS (secure) URL
target is recommended when including the {{sourceCandidateId}} tag in your URL.
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. If passed on subsequent calls
for a given SourceCandidateId, the OnAssessmentCompleteAction will be updated.
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. If passed on subsequent calls for a given SourceCandidateId, the EmailReportToList will be updated.
formatOutput
xml
json
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="1733074624.701" startedOnUtc="1733074624.701" completedOnUtc="1733074624.701" startCount="0" phoneNumber="[phoneNumber]" emailAddress="[endReminder@Here.com]" remindUntilUtc="1734284224.701" onAssessmentCompleteRedirectToUrl="[https://yourDomainHere.com]?code=[invitationCode]&id=[sha512Hash]" />
<jobFitList>
<jobFit job="[jobName_1]" fitPct="0.99" fitId="3" fit="High" isPrimaryJob="true" sourceJobId="[sourceJobId_1]" reportUrl="https://example.assessment.url/rpt/K82GE6AZYE63XVRSG6BRJDFUHH?end" fitComputedOnUtc="1733074624.7013476" />
<jobFit job="[jobName_2]" fitPct="0.65" fitId="2" fit="Medium" isPrimaryJob="false" sourceJobId="[sourceJobId_2]" reportUrl="https://example.assessment.url/rpt/SS9CANXGD32BDPG5NM2PEG3HW5?end" fitComputedOnUtc="1733074624.7013476" />
<jobFit job="[jobName_3]" fitPct="0.32" fitId="1" fit="Low" isPrimaryJob="false" sourceJobId="[sourceJobId_3]" reportUrl="https://example.assessment.url/rpt/54K8JB64CCWPJ6XJC2QTDS9FPW?end" fitComputedOnUtc="1733074624.7013476" />
<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?end" fitComputedOnUtc="1733074624.7013476" />
<jobFit job="[jobName_5]" fitPct="-1" fitId="5" fit="Not Enough Assessment Data" isPrimaryJob="false" sourceJobId="[sourceJobId_5]" reportUrl="" fitComputedOnUtc="1733074624.7013476" />
</jobFitList>
</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": 1733074624.748,
"startedOnUtc": 1733074624.748,
"completedOnUtc": 1733074624.748,
"startCount": 0,
"phoneNumber": "[phoneNumber]",
"emailAddress": "[endReminder@Here.com]",
"remindUntilUtc": 1734284224.748,
"onAssessmentCompleteRedirectToUrl": "[https://yourDomainHere.com]?code=[invitationCode]&id=[sha512Hash]"
},
"jobFit": [
{
"job": "[jobName_1]",
"fitPct": 0.99,
"fitId": 3,
"fit": "High",
"isPrimaryJob": true,
"sourceJobId": "[sourceJobId_1]",
"reportUrl": "https://example.assessment.url/rpt/K82GE6AZYE63XVRSG6BRJDFUHH?end",
"fitComputedOnUtc": 1733074624.7482252
},
{
"job": "[jobName_2]",
"fitPct": 0.65,
"fitId": 2,
"fit": "Medium",
"isPrimaryJob": false,
"sourceJobId": "[sourceJobId_2]",
"reportUrl": "https://example.assessment.url/rpt/SS9CANXGD32BDPG5NM2PEG3HW5?end",
"fitComputedOnUtc": 1733074624.7482252
},
{
"job": "[jobName_3]",
"fitPct": 0.32,
"fitId": 1,
"fit": "Low",
"isPrimaryJob": false,
"sourceJobId": "[sourceJobId_3]",
"reportUrl": "https://example.assessment.url/rpt/54K8JB64CCWPJ6XJC2QTDS9FPW?end",
"fitComputedOnUtc": 1733074624.7482252
},
{
"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?end",
"fitComputedOnUtc": 1733074624.7482252
},
{
"job": "[jobName_5]",
"fitPct": -1.0,
"fitId": 5,
"fit": "Not Enough Assessment Data",
"isPrimaryJob": false,
"sourceJobId": "[sourceJobId_5]",
"reportUrl": "",
"fitComputedOnUtc": 1733074624.7482252
}
],
"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]"
}
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] )
sourceDepartmentId was not found.
Department Not Enabled [403.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-12-01T17:37:04.0482254Z] to [2024-12-01T17:37:04.6482254Z]." responseCode="429" callDeniedDateTime="2024-12-01T17:37:04.7482254Z" callExpiresOnCompletion="true" countCallsExceeded="3" estimatedMillisecondsToNextAllowedCall="423" firstCallDeniedDateTime="2024-12-01T17:37:04.4482254Z" isDailyLimit="false" maximumCallsPerTimeFrame="120" timeFrameMilliseconds="60000" />
{
"callDeniedDateTime": "2024-12-01T17:37:04.7482254Z",
"callExpiresOnCompletion": true,
"countCallsExceeded": 3,
"estimatedMillisecondsToNextAllowedCall": 423,
"firstCallDeniedDateTime": "2024-12-01T17:37:04.4482254Z",
"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-12-01T17:37:04.0482254Z] to [2024-12-01T17:37:04.6482254Z].",
"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.