Job Portal API
The Job Portal API is now available for vendors to use.
To retrieve detailed information about a job, utilize the Profiles API.
This endpoint allows a 3rd party to mimic the job posting behavior as observed within iCIMS Career Portals; it will return jobs matching the provided search filter(s). Please refer to the Search API documentation for additional information about the search endpoint’s behavior. Pagination behavior and staleness (result caching) are also documented in the Search API documentation.
https://api.icims.com/customers/{customerId}/search/portals/{portalIdOrName}
Example Request:
GET /customers/1769/search/portals/jobs/ HTTP/1.1
Host: api.icims.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Cache-Control: no-cache
Example Response Payload:
{
"searchResults": [
{
"portalUrl": "https://jobs-preview2test.icims.com/jobs/1709/customer-service-representative/job",
"self": "https://api.dev.icims.com/customers/1769/portals/jobs/1709",
"id": 1709,
"updatedDate": "2015-09-30 02:07 PM"
},
{
"portalUrl": "https://jobs-preview2test.icims.com/jobs/1708/administrative-assistant/job",
"self": "https://api.dev.icims.com/customers/1769/portals/jobs/1708",
"id": 1708,
"updatedDate": "2015-09-30 02:06 PM"
},
{
"portalUrl": "https://jobs-preview2test.icims.com/jobs/1707/technical-writer/job",
"self": "https://api.dev.icims.com/customers/1769/portals/jobs/1707",
"id": 1707,
"updatedDate": "2015-09-30 01:41 PM"
}
]
}
This get request allows you to get information about the supported portal search filters. It will return the information displayed to the user, as well as the information you can feed back to the Portal job listings endpoint to filter down the results.
The "name" attribute will be the Portal filter name.
The "options" are for dropdowns; the "id" represents the filter value.
This follows the same format as the Search API endpoint; see http://developer.icims.com/REST-API/Object-Types-Commands/Search-API for more information.
https://api.icims.com/customers/{customerId}/search/portals/{portalIdOrName}/filters
Example Request:
GET /customers/1769/search/portals/jobs/filters HTTP/1.1
Host: api.icims.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Cache-Control: no-cache
Example Response Payload:
{
"filters": [
{
"name": "job.positioncategory",
"options": [
{
"id": "8713",
"value": "Accounting/Finance"
},
{
"id": "8718",
"value": "Administrative/Clerical"
},
{
"id": "17429",
"value": "Architecture and Engineering"
},
{
"id": "17450",
"value": "Arts, Design, Entertainment, Sports and Media"
},
{
"id": "17473",
"value": "Building and Grounds Cleaning and Maintenance"
},
{
"id": "17422",
"value": "Business and Financial Operations"
},
{
"id": "17438",
"value": "Community and Social Services"
},
{
"id": "17425",
"value": "Computer and Mathematics"
},
{
"id": "17505",
"value": "Construction and Extraction"
},
{
"id": "8721",
"value": "Customer Service/Support"
},
{
"id": "17444",
"value": "Education, Training, and Library Occupations"
},
{
"id": "8723",
"value": "Engineering"
},
{
"id": "17455",
"value": "Healthcare Practitioners and Technicians"
},
{
"id": "8725",
"value": "Human Resources"
},
{
"id": "8730",
"value": "Information Technology"
},
{
"id": "17511",
"value": "Installation, Maintenance, and Repair"
},
{
"id": "8737",
"value": "Legal"
},
{
"id": "17433",
"value": "Life, Physical and Social Science"
},
{
"id": "8739",
"value": "Management"
},
{
"id": "8741",
"value": "Marketing"
}
],
"label": "Category",
"type": {
"display": "multiselect",
"id": 3
}
},
{
"name": "job.joblocation.companyid",
"options": [
{
"id": "269",
"value": "iCIMS"
}
],
"label": "Company",
"type": {
"display": "freetext",
"id": 0
}
},
{
"name": "job.positiontype",
"options": [
{
"id": "2049",
"value": "Regular Full-Time"
},
{
"id": "2050",
"value": "Regular Part-Time"
},
{
"id": "2051",
"value": "Temporary Full-Time"
},
{
"id": "8709",
"value": "Temporary Part-Time"
},
{
"id": "2052",
"value": "Contract"
},
{
"id": "8710",
"value": "Intern"
},
{
"id": "17991",
"value": "Seasonal"
},
{
"id": "19768",
"value": "Intern (Full Time)"
}
],
"label": "Position Type",
"type": {
"display": "multiselect",
"id": 3
}
},
{
"name": "job.jobpost.postdate",
"options": [
{
"id": "09/30/2015 00:00:00.000",
"value": "Today"
},
{
"id": "09/23/2015 00:00:00.000",
"value": "Past 7 Days"
},
{
"id": "09/16/2015 00:00:00.000",
"value": "Past 14 Days"
},
{
"id": "08/31/2015 00:00:00.000",
"value": "Past 30 Days"
},
{
"id": "08/01/2015 00:00:00.000",
"value": "Past 60 Days"
},
{
"id": "07/02/2015 00:00:00.000",
"value": "Past 90 Days"
},
{
"id": "03/30/2015 00:00:00.000",
"value": "Past 6 Months"
},
{
"id": "09/30/2014 00:00:00.000",
"value": "Past Year"
}
],
"label": "Posted Date",
"type": {
"display": "datetime",
"id": 15
}
},
{
"name": "job.portaljoblocation",
"options": [
{
"id": "--Matawan",
"value": "Matawan"
}
],
"label": "Location",
"type": {
"display": "freetext",
"id": 0
}
},
{
"name": "job.portalkeywordsearch",
"label": "Keywords",
"type": {
"display": "freetext",
"id": 0
}
},
{
"name": "job.joblocation.zipradius",
"secondaryValue": {
"options": [
{
"id": "5",
"value": "5"
},
{
"id": "10",
"value": "10"
},
{
"id": "15",
"value": "15"
},
{
"id": "20",
"value": "20"
},
{
"id": "25",
"value": "25"
},
{
"id": "35",
"value": "35"
},
{
"id": "50",
"value": "50"
},
{
"id": "75",
"value": "75"
},
{
"id": "100",
"value": "100"
},
{
"id": "150",
"value": "150"
},
{
"id": "200",
"value": "200"
}
],
"id": "radius",
"label": "Find jobs within",
"units": "miles"
},
"label": "Zip Code",
"type": {
"display": "freetext",
"id": 0
}
},
{
"name": "job.updateddate",
"label": "Updated Date",
"type": {
"display": "datetime",
"id": 15
}
}
]
}
Use "Get information about the supported Portal search filters" to return a list of supported filters, and review the Search API (http://developer.icims.com/REST-API/Object-Types-Commands/Search-API) for assistance formatting filters.
GET: https://api.icims.com/customers/{customerId}/search/portals/{portalNameOrId}?searchJson={encodedSearchParameters}
OR
POST: https://api.icims.com/customers/{customerId}/search/portals/{portalNameOrId}
Example Request with Job Category Filter:
Note: Search parameters before encoding: {"filters":[{"name":"job.positioncategory","value":["2140"],"operator":"="}],"operator":"&"}
GET /customers/1771/search/portals/jobs?searchJson=%7B%22filters%22%3A%5B%7B%22name%22%3A%22job.positioncategory%22%2C%22value%22%3A%5B%222140%22%5D%2C%22operator%22%3A%22%3D%22%7D%5D%2C%22operator%22%3A%22%26%22%7D HTTP/1.1
Host: api.icims.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
Cache-Control: no-cache
Example Response:
{
"searchResults": [
{
"portalUrl": "https://jobs-preview4test.icims.com/jobs/1019/proposal-writer/job",
"self": "https://api.icims.com/customers/1771/portals/jobs/1019",
"id": 1019,
"updatedDate": "2016-03-04 07:30 PM"
}
]
}
Example Request with Zip Radius Filter:
POST /customers/1769/search/portals/jobs HTTP/1.1
Host: api.icims.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
Cache-Control: no-cache
{
"filters": [
{
"secondaryValue": [
"15"
],
"name": "job.joblocation.zipradius",
"value": [
"07747"
],
"operator": "="
}
],
"operator": "&"
}
Example Response Payload:
{
"searchResults": [
{
"portalUrl": "https://jobs-preview2test.icims.com/jobs/1709/customer-service-representative/job",
"self": "https://api.dev.icims.com/customers/1769/portals/jobs/1709",
"id": 1709,
"updatedDate": "2015-09-30 02:07 PM"
},
{
"portalUrl": "https://jobs-preview2test.icims.com/jobs/1708/administrative-assistant/job",
"self": "https://api.dev.icims.com/customers/1769/portals/jobs/1708",
"id": 1708,
"updatedDate": "2015-09-30 02:06 PM"
},
{
"portalUrl": "https://jobs-preview2test.icims.com/jobs/1707/technical-writer/job",
"self": "https://api.dev.icims.com/customers/1769/portals/jobs/1707",
"id": 1707,
"updatedDate": "2015-09-30 01:41 PM"
}
]
}
-----
Example Request with Date Filter:
POST /customers/1769/search/portals/jobs HTTP/1.1
Host: api.icims.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
Cache-Control: no-cache
{
"filters":[
{
"secondaryValue":[
"2015-10-30 12:00 PM"
],
"name":"job.jobpost.postdate",
"value":[
"2015-09-30 01:00 AM"
],
"operator":"="
}],
"operator":"&"
}
Example Response Payload:
{
"searchResults": [
{
"portalUrl": "https://jobs-preview2test.icims.com/jobs/1709/customer-service-representative/job",
"self": "https://api.dev.icims.com/customers/1769/portals/jobs/1709",
"id": 1709,
"updatedDate": "2015-09-30 02:07 PM"
},
{
"portalUrl": "https://jobs-preview2test.icims.com/jobs/1708/administrative-assistant/job",
"self": "https://api.dev.icims.com/customers/1769/portals/jobs/1708",
"id": 1708,
"updatedDate": "2015-09-30 02:06 PM"
},
{
"portalUrl": "https://jobs-preview2test.icims.com/jobs/1707/technical-writer/job",
"self": "https://api.dev.icims.com/customers/1769/portals/jobs/1707",
"id": 1707,
"updatedDate": "2015-09-30 01:41 PM"
}
]
}
https://api.icims.com/customers/{custId}/portalposts/job/{jobId}
Example Request:
GET /customers/1769/portalposts/job/1707 HTTP/1.1
Host: api.icims.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
Cache-Control: no-cache
Example Response Payload:
{
"jobposts": [
{
"jobpostid": 325,
"portalurl": "jobs-preview2test.icims.com",
"startdate": "2015-09-30 01:41 PM",
"status": "Posted"
},
{
"jobpostid": 328,
"portalurl": "employees-preview2test.icims.com",
"startdate": "2015-09-30 05:28 PM",
"status": "Posted"
}
]
}
https://api.icims.com/customers/{custId}/portalposts/{jobPostId}
Example Request:
GET /customers/1769/portalposts/325 HTTP/1.1
Host: api.icims.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
Cache-Control: no-cache
Example Response Payload:
{
"jobpostid": 325,
"portalurl": "jobs-preview2test.icims.com",
"links": [
{
"rel": "self",
"title": "The current jobpost being viewed.",
"url": "https://api.dev.icims.com/customers/1769/portalposts/325"
}
],
"startdate": "2015-09-30 01:41 PM",
"status": "Posted"
}
HTTP Response: 5XX
Payload Format:
{
"message": "<Error message>",
"code": <HTTP response code>
}
https://api.icims.com/customers/{custId}/portalposts/
Example Request:
POST /customers/1769/portalposts/ HTTP/1.1
Host: api.icims.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
Cache-Control: no-cache
{
"jobid": 1709,
"userid": 387,
"startdate": "2015-09-30 9:31 AM",
"enddate": "2015-12-04 11:31 AM",
"portalurl": "employees-preview2test.icims.com"
}
Example Response:
No payload will be provided in response if post is successful.
HTTP 201 and location header whose value is a self URL link with the new JobPostID will be provided (e.g., Location: https://api.icims.com/customers/{custId}/portalposts/{jobPostId}) if successful.
Errors will occur for the following reasons:
-
The job is not in the Approved folder
-
The Portal cannot be posted to
-
The job is already posted to the specified Portal
HTTP Response: 5XX, 4XX
Payload Format:
{
"message": "<Error message>",
"code": <HTTP response code>
}
https://api.icims.com/customers/{custId}/portalposts/unpost
Example Request Payload:
PATCH /customers/1769/portalposts/unpost HTTP/1.1
Host: api.icims.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
Cache-Control: no-cache
{
"jobid": 1709,
"userid": 387,
"portalurl": "employees-preview2test.icims.com"
}
Example Response:
No payload provided with successful unposting.
HTTP 200 response provided if successful.
Errors will occur for the following reasons:
- The job is not an the Approved status
- The job post is not in the Posted status
HTTP Response: 5XX, 4XX
Payload Format:
{
"message": "<Error message>",
"code": <HTTP response code>
}