Job Distributor
The Job Distributor API allows job distributers to communicate the following information with iCIMS:
- Job boards the job has been posted to
- Status of the job board posting
- View and click statistics
Notes:
- The security for this API is the same as all other iCIMS APIs: all requests must be made over SSL and IP restrictions prevent unwanted traffic.
- This API supports GET, POST, and PATCH requests.
When a recruiter posts a job to a job distributor from the iCIMS Platform, the Platform sends a POST request to the Job Distributor API. After retrieving all data required for the Job Posting through GET Requests, the Job Distributor responds back 303 with a redirect URL for its remote site, which the recruiter logs in to to complete the posting, anytime in the future.
If there is any update or change in the status of a job in the Job Distributor's system, the Job Distributor sends a notification to the iCIMS Platform with a PATCH Request, outlined below. The change could be in status, start date, end date, adding a job board, or removing a job board.
Notes:
- The following statuses are supported by the iCIMS Platform. (Statuses are case-insensitive. There is a single space between words in a status; more than one space is invalid.)
- Expired
- Live
- Posting in Progress
- Deletion in Progress
- Unposted
- It is required to send the parameters and their value (value, externalid, status, startdate, and enddate) for all job boards, even if only one gets updated/changed.
- The following date & time format is supported by the iCIMS Platform: YYYY-MM-DDhh:mmAM/PM. (Example: 2014-12-04 11:31 AM )
https://api.icims.com/customers/{custId}/jobboardposts/
{
"jobid":"1234",
"jobdistributor":{
"id":"D90005"
},
"jobboards":[
{
"jobboard":{
"value":"CareerBuilder.com",
"externalid":"764"
},
"status":"live",
"startdate":"2014-08-04 11:31 AM",
"enddate":"2014-12-04 11:31 AM"
},
{
"jobboard":{
"value":"Monster.com",
"externalid":"763"
},
"status":"Posting in Process",
"startdate":"2014-08-04 11:31 AM",
"enddate":"2014-12-04 11:31 AM"
}
]
}
HTTP Response: 5xx, 4xx
Payload:
{
"message": "",
"code":
}
HTTP Response: 204
The iCIMS Platform gets live data on number of Views and number of click-throughs per Job Board (for given job systemId which is optional), sending GET Request to Job Distributor API.
Note: Job System Id is optional (if not specified, means all jobs for the given Customer Id).
https://{JobDistributorHostname}/analytics/chart/views?customerId={custId}&systemId={jobId}&startdate={startDate}&enddate={endDate}&topmost={x}
Example: https://icims.api.jobtarget.com/analytics/chart/views?customerId=456678&systemid=346&startdate=2014-03-01&enddate=2014-04-01&topmost=4
[Get number of views for customer with Id: 456678, from date: 2014-03-01 to 2014-04-01, of 4 top most boards ]
}
HTTP Response: 200
Payload:
Note that a JSON response like the example below is required for iCIMS to generate a chart of job information.
{
"status": "success",
"data": {
"series": [
{
"data": [
[
"Monster.com",
28
],
[
"CareerBuilder.com",
10
],
[
"CraigList",
40
],
[
"USAToday.com",
30
]
]
}
]
}
}
The iCIMS Platform gets live data on number of Views and number of click-throughs per Job Board (for given job systemId which is optional), sending GET Request to Job Distributor API.
Note: Job System Id is optional (if not specified, means all jobs for the given Customer Id).
https://{JobDistributorHostname}/analytics/chart/ clickthroughs?customerid={custId}&systemid={jobId}&startdate={startDate}&enddate={endDate}&topmost={x}
https://icims.api.jobtarget.com/analytics/chart/ clickthroughs?customerId=456678&systemid=346&startdate=2014-03-01&enddate=2014-04-01&topmost=4
[Get number of click-throughs for customer with Id: 456678, from date: 2014-03-01 to 2014-04-01, of 4 top most boards]
}