PerformAssessment Method

Optional. Null or 1-50 characters. If recorded, Phone Number can be displayed on report covers.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

• The assessmentStatus node includes the following attributes:
  • The sourceCandidateId attribute is the unique ID you supplied when creating the candidate's assessment.
  • 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.

• There are jobFit nodes for each active Berke job in your account. If the candidate's assessment is complete, it will include fit scores and report links.
  Attributes of each jobFit node include:
  • 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 .

• 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

sourceDepartmentId was not found.

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

• 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-07-27T06:37:50.2170052Z] to [2024-07-27T06:37:50.8170052Z]." responseCode="429" callDeniedDateTime="2024-07-27T06:37:50.9170052Z" callExpiresOnCompletion="true" countCallsExceeded="3" estimatedMillisecondsToNextAllowedCall="423" firstCallDeniedDateTime="2024-07-27T06:37:50.6170052Z" isDailyLimit="false" maximumCallsPerTimeFrame="120" timeFrameMilliseconds="60000" />

{
  "callDeniedDateTime": "2024-07-27T06:37:50.9170052Z",
  "callExpiresOnCompletion": true,
  "countCallsExceeded": 3,
  "estimatedMillisecondsToNextAllowedCall": 423,
  "firstCallDeniedDateTime": "2024-07-27T06:37:50.6170052Z",
  "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-07-27T06:37:50.2170052Z] to [2024-07-27T06:37:50.8170052Z].",
  "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.