List API
View DocumentationThe List API allows users to access and modify the lists within a customer's Platform.
Get full set of lists for a Platform
This endpoint retrieves a full set of available lists within a Platform.
URL: https://api.icims.com/customers/{customerID}/v2/lists
| Action | Definition |
|---|---|
| Get: |
Example Request Payload:
Example Response Payload:
|
Get a specific standard list
This endpoint retrieves nodes within a specified list.
To facilitate larger lists, one level of a list is returned at a time, and each individual level is paged. Only the immediate children of a particular node are returned for a single request. The number of children returned in a single request can be controlled via the size parameter, up to the default maximum of 1000.
Any children nodes returned will not have their children embedded in the response. Subsequent calls would need to be made to retrieve additional levels in the list. To aid in this navigation, links are included in the json under the key '_links'.
URL: https://api.icims.com/customers/{customerID}/v2/lists/{listID}
| Action | Definition |
|---|---|
| Get: |
Example Request Payload:
Example Response Payload (truncated):
|
Get a specific custom list
This endpoint retrieves nodes within a specified custom list.
Note: Custom lists do not have specific list IDs. To get a specific custom list, the node ID for the list itself must be used. To retrieve details for all custom lists within a system, use GET /lists/lists.customfields_lists/
To facilitate larger lists, one level of a list is returned at a time, and each individual level is paged. Only the immediate children of a particular node are returned for a single request. The number of children returned in a single request can be controlled via the size parameter, up to the default maximum of 1000.
Any children nodes returned will not have their children embedded in the response. Subsequent calls would need to be made to retrieve additional levels in the list. To aid in this navigation, links are included in the json under the key '_links'.
URL: https://api.icims.com/customers/{customerID}/lists/lists.customfields_lists/node/{listNodeId}
ListNodeId
"C" + value of "listnodeid", e.g. "C12345"
| Action | Definition |
|---|---|
| Get: |
Example Request Payload:
Example Response Payload (truncated):
|
Get a specific node within a list
This endpoint is used to retrieve information about a specific node within a list and its first level of children nodes, if applicable. The number of children nodes returned in a single request can be set using the "size" parameter.
When requesting a specific node within a multi-level list, the full path must be included in the URL. For example, to retrieve information about a second level node, the URL would be https://api.icims.com/customers/{customerID}/v2/lists/{listID}/{firstNodeId}/{secondNodeId}, where the firstNodeID corresponds to a parent node in the first level of the requested list, and the secondNodeID is a second level node that is a child of the first node. This pattern is dynamic, so any depth of a list can be requested with this format. URLs without a full path are not valid and will return an error.
The children nodes being returned will not have their children embedded in the response. Instead, the API user would need to make subsequent calls to retrieve additional levels in the list. To aid in this navigation, there are links included in the JSON under the key '_links'.
The top-level node will always have a 'self' link. If the node has at least one child, it will also have 'first' and 'last' page links. If the current page being requested is greater than 1, a 'prev' link will be provided. If there are any remaining pages for the current level, a 'next' link will be provided
URL: https://api.icims.com/customers/{customerID}/v2/lists/{listID}/{firstNodeID}
ListNodeID
"C" + value of "listnodeid", e.g. "C12345"
| Action | Definition |
|---|---|
| Get: |
Example Request Payload:
Example Response Payload:
Note: The node’s System ID can be used instead of the List Node ID; the System ID value must begin with "D". The example above would use /node/D51002 for the same node using the System ID. Custom list values will not have a System ID, so using the List Node ID is more reliable. |
| Errors: |
The entire path listed in the URL must be valid. If this path is not valid for any reason, a 404 will be returned. Some possible causes of the error could be:
|
Get a specific list or list node for a specific user group
Users can retrieve a specific list for a specific user group, meaning that they will view attributes as they affect that user group. For example, if a node is hidden for the specified user group, its hidden attribute will be returned as true. Note that the user group ID must be the Integration Name for that user group.
Similarly, users can use the endpoint /{firstNodeID} (e.g. the example displayed above in "Get a specific node within a list") with the user group parameter to retrieve information about a specific list node item for that specific user group. The path rules for the /{firstNodeID} endpoint as seen above apply.
URL: https://api.icims.com/customers/{customerID}/v2/lists/{listID}?usergroup={groupId}
| Action | Definition |
|---|---|
| Get: |
Example Request Payload:
Example Response Payload:
|
Update one or more list nodes
A user can execute a PATCH request on an entire list (this example) or a single node within a list (the "Update a specific list node" example below). Executing a PATCH request for the entire list is preferable if you would want to execute certain changes for every object in the list.
Note that the payload for a PATCH request on an entire list must be the entire list as a JSON object, meaning that it must include both values which are NOT being altered as well as those that ARE being altered.
A PATCH request may also be executed for a specific user group. The URL for this specific request is formed in the same manner as the URL for GET requests; see the "Get a specific list or list node for a specific user group" example (above).
URL: https://api.icims.com/customers/{customerID}/lists/{listID}
| Action | Definition |
|---|---|
| Patch: |
Example Request Payload: Note: In the example below, the hidden attribute for both nodes is set to true.
The Response Payload for a successful patch will include both an HTTP 200 response as well as the entire updated list. |
Update a specific list node
A user can execute a PATCH request on an entire list (the "Update one or more list nodes" example above) or a single node within a list (this example). PATCH Requests for specific list node items do not require the entire node item to be returned. The payload can be only a single attribute, more multiple attributes for a list node item.
Note: It is also possible to pass a null value for an attribute (e.g., {"hidden":null}); doing do will reset that attribute to its default value.
URL: https://api.icims.com/customers/{customerID}/lists/{listID}/node/{listNodeId}
| Action | Definition |
|---|---|
| Patch: |
Example Request Payload: Note: In the example below, the node C14044 is set to hidden and its label is changed to "newName." Note that only the affected node attributes are passed along in the request.
Example Response: No payload will be returned if post is successful. HTTP 204 response will be provided. |
Add a new node to a list
POST requests allow users to add items to a list. The payload is a JSON object that must contain a value for each attribute in the list; a blank value may be provided for any non-required attribute, but the attribute must be present in the object. Attributes for a list item can be retrieved via the UI, or from attempting to pass a blank JSON object via the POST request.
Note:
- Note that for options within dropdown attributes in a list item, the user must know the value to be passed in.
- List Node ID’s will be assigned automatically after the node is successfully created. The node ID is returned in the location header that is returned as a response to the POST call.
- List node items cannot be deleted. They can only be marked as hidden.
URL: https://api.icims.com/customers/{customerID}/lists/{listID}/node
| Action | Definition |
|---|---|
| Post: |
Example Request Payload:
Example Response Payload: No payload will be returned in response if post is successful. HTTP 201 and location header whose value is a self URL link with the newly-created ListNodeID will be provided (e.g., Location: https://api.icims.com/customers/{customerID}/lists/{listID)/node/{listNodeID} if successful. |
Add a new child node to an existing list node
POST requests can also be done to create “child” nodes of members of a list. This is done by adding the path parameter “parentNodeId” to the basic POST URL (shown for the "Add a new node to a list" example above).
URL: https://api.icims.com/customers/{customerID}/lists/{listID}/node?parentNodeId={listNodeId}
| Action | Definition |
|---|---|
| Post: |
Example Request Payload:
Example Response Payload: No payload will be returned in response if post is successful. HTTP 201 and location header whose value is a self URL link with the newly-created ListNodeID will be provided (e.g., Location: https://api.icims.com/customers/{customerID}/lists/{listID)/node/{listNodeID} if successful. |