ChangeJob Method - Berke Assessment API

Changes the job assigned to a participant’s assessment to a different job. If the different job requires additional assessment data and the assessment is already complete, then the assessment will be re-opened. If the assessment status changes from complete to open, you must follow up this method by communicating the start link to the assessment user either via your UI, email, or text.

A detailed description of this operation is available here. Before implementing this API method, we recommend that you carefully review this material.

See the UpdateAssessment method to update other assessment properties, such as name and title.

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).
sourceCandidateId	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 status of 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.
newSourceJobId	Required. 1-50 characters. NewSourceJobId is not case-sensitive. Must be previously assigned to a job via the Settings link's API \| Job Assignments (Berke login required) option. You can also retrieve your Source Job ID values with the GetJobs method.
previewJobChange	Required, true or false. If true, then the job change will be evaluated, but not performed. This is useful for determining the impact of changing a job before the change is made. If false, then the job change will be performed and the assessment's status may change from open to closed or closed to open. Please review this document to see how Berke uses this feature to explain changes to users.
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]" newSourceJobId="[newSourceJobId]" newJob="[name of job related to newSourceJobId]" previewJobChange="false" statusChangeId="202" statusChangeSummary="Job changed, assessment status changed to open" nextSteps="Inform participant to resume the assessment by visiting the link in [assessmentUrl]" remainingSecondsToComplete="600" statusChanged="true" statusOpenAfterJobChange="true" assessmentUrl="https://example.assessment.url/[invitationCode]">
    <remainingSectionsToComplete>[additional section 1]</remainingSectionsToComplete>
    <remainingSectionsToComplete>[additional section 2]</remainingSectionsToComplete>
    <remainingSectionsToComplete>[additional section 3]</remainingSectionsToComplete>
  </assessment>
</berkeResponse>

{
  "assessment": {
    "sourceCandidateId": "[sourceCandidateId]",
    "newSourceJobId": "[newSourceJobId]",
    "newJob": "[name of job related to newSourceJobId]",
    "previewJobChange": false,
    "statusChangeId": 202,
    "statusChangeSummary": "Job changed, assessment status changed to open",
    "nextSteps": "Inform participant to resume the assessment by visiting the link in [assessmentUrl]",
    "remainingSecondsToComplete": 600,
    "remainingSectionsToComplete": [
      "[additional section 1]",
      "[additional section 2]",
      "[additional section 3]"
    ],
    "statusChanged": true,
    "statusOpenAfterJobChange": true,
    "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]

sourceCandidateId is the value you passed in that identifies the assessment you want to preview or change.
newSourceJobId is the value you passed in that identifies the job to assign to the assessment.
newJob is the name of the the job to assign to the assessment.
previewJobChange will be true if the job was not changed. Use the previewJobChange feature to determine the impact of changing a job before actually changing assessment. Please review this document to see how Berke uses this feature to explain changes to users.
statusChangeId is the numeric identifier for the outcome of calling the ChangeJob method. Responses include:
- 101 = PreviewModeStatusWillNotChange
- 102 = PreviewModeStatusWillChangeToOpen
- 103 = PreviewModeStatusWillChangeToComplete
- 201 = JobChangeModeNoStatusChange
- 202 = JobChangeModeStatusChangedToOpen
- 203 = JobChangeModeStatusChangedToComplete
statusChangeSummary describes the operation performed. Do not match on statusChangeSummary; use statusChangeId instead. Responses include:
- statusChangeId=101: If primary job changes, assessment status will not change
- statusChangeId=102: If primary job changes, assessment status will change to open
- statusChangeId=103: If primary job changes, assessment status will change to complete
- statusChangeId=201: Job changed, assessment status did not change
- statusChangeId=202: Job changed, assessment status changed to open
- statusChangeId=203: Job changed, assessment status changed to complete
nextSteps describes the next steps your application must perform to complete the ChangeJob process. Do not match on nextSteps; use statusChangeId instead. Responses include:
- statusChangeId=101: Call ChangeJob with PreviewJobChange=false to change the job
- statusChangeId=102: Call ChangeJob with PreviewJobChange=false to change the job, then inform participant to resume the assessment
- statusChangeId=103: Call ChangeJob with PreviewJobChange=false to change the job, then optionally inform participant that assessment is now complete
- statusChangeId=201: No further action is necessary
- statusChangeId=202: Inform participant to resume the assessment by visiting the link in [assessmentUrl]
- statusChangeId=203: Optionally inform participant that assessment is now complete
remainingSecondsToComplete is the total number of seconds to complete the assessment after changing the job. Note that this value is based on historical averages, so your participant's exact time may vary.
remainingSectionsToComplete is an array of assessment sections that must be completed after changing the job. Please review this document to see how Berke uses this feature to explain changes to users.
statusChanged is true if the status is changing from open to complete or complete to open.
statusOpenAfterJobChange is true if the assessment is open (not complete) after changing the job. If true, assessmentUrl needs to be presented to the participant.
assessmentUrl is the link to which your participant must return if the assessment is not complete after changing the assessment's job. Your application must communicate this link to the participant either via your user interface, email, or text. You can also send a nicely formatted invitation to the participant using our SendInvitation method.

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 source candidate id
Assessment's SourceJobId and NewSourceJobId are identical [403.1038])	HTTP error code 403.1038 You cannot use the ChangeJob method with the assessment's current job.
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-22T09:43:15.5600118Z] to [2024-11-22T09:43:16.1600118Z]." responseCode="429" callDeniedDateTime="2024-11-22T09:43:16.2600118Z" callExpiresOnCompletion="true" countCallsExceeded="3" estimatedMillisecondsToNextAllowedCall="423" firstCallDeniedDateTime="2024-11-22T09:43:15.9600118Z" isDailyLimit="false" maximumCallsPerTimeFrame="120" timeFrameMilliseconds="60000" /> { "callDeniedDateTime": "2024-11-22T09:43:16.2600118Z", "callExpiresOnCompletion": true, "countCallsExceeded": 3, "estimatedMillisecondsToNextAllowedCall": 423, "firstCallDeniedDateTime": "2024-11-22T09:43:15.9600118Z", "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:43:15.5600118Z] to [2024-11-22T09:43:16.1600118Z].", "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.