Workflow Status Update
View DocumentationThe Applicant Workflow Status update event is used by iCIMS to send person and job data to a third party vendor when an internal Platform user modifies a candidate’s status in the iCIMS platform. This event is most commonly used by clients who use a third party Background Check provider, but can be used for other integrations as well.
The Workflow Status Update Event is used to initiate a connection from iCIMS to a Partner. This event is triggered by a Platform user who wishes to send candidate or new hire and job information to a Partner.
What does the event do?:
The Status Flow Update event was designed to provide recruiters and other Platform users with a way to initiate a connection to an iCIMS Partner. A Platform user must select a Workflow profile and take action on a candidate/new hire that is attached to a Job or New Hire Category. A specific status can be set as the trigger; once the candidate/new hire is placed into the trigger status, the connection will begin. The payload will be a JSON message containing the following parameters used to describe the request:
| Parameter | iCIMS Field Mapping | Purpose |
| newStatus | New status | Specifies the ID of the new status of the candidate |
| oldStatus | Old status | Specifies the ID of the prior status of the candidate |
| customerId | Customer ID | Specifies the ID of the customer |
| jobId | Job System ID | Specifies the ID of the job the candidate is attached to |
| userId | Platform User (Recruiter) System ID | Specifies the ID of the person who initiated the event |
| personId | Candidate/ New Hire System ID | Specifies the ID of the candidate/new hire |
| links | GET Links | Specifies the exact GET request necessary to return additional information for an entity. |
| eventType | Event Type | Specifies event type, which will be WorkFlowStatusChangeEvent. |
| systemId | Workflow System ID | Specifies the person/ new hire & job/ new hire category relationship |
The partner replies to the original request in Step 1 with any of the following HTTP Status Codes and the criteria for these responses:
- HTTP 200 OK: The request was valid and was processed successfully; no further action is required. The partner should send a confirmation message to be displayed to the user in the JSON payload - {"userMessage":"Your message goes here.","code":200}
- HTTP 303 See Other: The request was valid and was processed successfully; the redirect link is provided in the response header.
- HTTP 400 Bad Request: The partner received an incorrect or malformed request, or is otherwise unable to service the request due to its contents.
In iCIMS, each Workflow Status change event has a ‘Show Confirmation’ option that must be configured in the platform. If this is ‘on’ for a successful transaction either a default message will be shown to the user that states 'Follow the link to confirm the action' or the partner can code a successful usermessage with the 200 OK response code. The default message will only apply to the integration if the partner is redirecting the iCIMS user with a 303 See Other return code to the partner platform to complete the request. If this is not the case, the partner will need to code a successful message or have the ‘Show Confirmation’ option turned 'off', in the sandbox as well as for each client. It provides a better user experience when the user sees a confirmation message however, it is not required. The partner will need to request to have the 'Show Confirmation' option set based on how they will be handling a successful transaction. All error messages returned with the 400 Bad Request response code will be displayed to the user.
Example:
iCIMS -> Partner:
POST /rest/rest/echo HTTP/1.1
Connection: close
Link: https://api.icims.com/customers/1234/applicantworkflows/2203;rel="applicantWorkflow";title="Applicant Workflow",https://api.icims.com/customers/1234/jobs/1242;rel="job";title="Job Profile",https://api.icims.com/customers/1234/people/1364;rel="person";title="Person Profile",https://api.icims.com/customers/1234/people/3;rel="user";title="Posting User",
Content-Length: 280
Content-Type: application/json
Content-Encoding: gzip
Host: dummyserver.icims.com
User-Agent: Apache-HttpClient/4.2.1 (java 1.5)
Accept-Encoding: gzip,deflate
{
"newStatus": "9782",
"oldStatus": "1752",
"customerId": "1234",
"jobId": "1242",
"userId": "3",
"personId": "1364",
"links": [
{
"title": "Applicant Workflow",
"rel": "applicantWorkflow",
"url": "https://api.icims.com/customers/1234/applicantworkflows/2203"
},
{
"title": "Job Profile",
"rel": "job",
"url": "https://api.icims.com/customers/1234/jobs/1242"
},
{
"title": "Person Profile",
"rel": "person",
"url": "https://api.icims.com/customers/1234/people/1364"
},
{
"title": "Posting User",
"rel": "user",
"url": "https://api.icims.com/customers/1234/people/3"
}
],
"eventType": "WorkFlowStatusChangeEvent",
"systemId": "2203"
}
Use Cases:
Status Flow Update:
The Status Flow Update event is used by iCIMS to send person and job data to a third party vendor when an internal Platform user modifies a candidate’s status in the iCIMS Talent Platform. This event is most commonly used by clients who use a third party Background Check, Assessment, Video Interview, or Tax Credit provider, but can be used for other integrations as well.