• iCIMS Corporate Site
  • iCIMS Partners
  • Additional Resources
  • Recent Updates
  • FAQ
  • Login
  • GETTING STARTED
    • Getting Started
    • Integration Approval Process
    • How-To Videos
    • Acceptable Use Policy
    • Terms of Use
    • Release Notes
  • API
    • Licenses
    • Connecting, Authenticating, and Identity
    • Authenticating API Calls with OAuth 2.0
    • HMAC
    • Error Handling
    • Error Reporting Standard for Vendors
    • Field Types
  • Standard Integrations
    • Assessments
    • Candidate Matching
    • Candidate Ranking
    • Document Management
    • Data Analytics and Reporting
    • Human Capital Management
    • I-9 & E-Verify
    • Job Advertising
    • Job Posting
    • Partner Screening
    • Reference Checks
    • Tax Credits
    • Video Interviewing
  • Prime Integrations
    • Prime Assessments
    • Prime Background Screen
      • Implementation
  • Endpoints
    • Binary Collection Fields
    • Binary Files
    • Collection Fields
    • Customers
    • Direct Linking
    • iForms
    • Job Distributor
    • Job Portal API
    • List API
    • Offer API
    • Onboard API
    • Profiles
    • Schema API
    • Search API
    • Workflows
  • Streaming Endpoints
  • Data Models
    • iForms
    • Job
    • Location
    • New Hire Category
    • Onboarding Workflow
    • Person
    • Recruiting Workflow
    • Room
    • Sourcing Workflow
    • Talent Pool
    • Event
    • Validation
  • Integration Events
    • Best Practices
    • Application Complete
    • Job Edit
    • Job Posting
    • Job Unposting
    • Onboard Portal Task
    • Status Flow Update
  • OTHER TECH
    • File-Based Transfers
      • Scheduled Import/Export Licenses
      • Imports
      • Exports
      • File Formatting
      • Import File Examples
    • SAML
    • Standard XML Feed for Job Boards
  • Forum

Search form

Developer Resources
  • Getting Started
  • API
  • Standard Integrations
  • Prime Integrations
  • Endpoints
  • Streaming Endpoints
  • Data Models
  • Integration Events
    • Best Practices
    • Application Complete
    • Job Edit
    • Job Posting
    • Job Unposting
    • Onboard Portal Task
    • Status Flow Update
  • OTHER TECHNOLOGY
  • FAQ

Status Flow Update

The Status Flow 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, Video Interview, or Tax Credit provider, but can be used for other integrations as well.

Partner Screening
Do you have any questions or feedback regarding iCIMS' API documentation? Email the team
See Recent Site Updates

© 2023 iCIMS, Inc. All rights reserved.
Privacy Notice | Terms of Use