The Profiles Endpoint allows a user to access various profile types within the iCIMS Talent Platform and interact with the information housed within fields on those profiles.
Profile Types
The list below contains all current profile types supported by the iCIMS Talent Platform, as well as each profile's profileType, which is necessary to access the profile via the API. (Refer to Add new Profile of specified type, below, for more information.)
Note that not all clients have all profile types enabled.
- Person Profile: people
- Job Profile: jobs
- Location/Company Profile: companies
- New Hire Category Profile: newhirecategories
- Talent Pool Profile: talentpools
- Room Profile: rooms
- Event Profile: connectevents
Permissions
The interaction of Profiles through the Profiles API will generally follow the same conventions as if a user were to access the information through the iCIMS Talent Platform. That is, if a user would be able to access a field or profile in the iCIMS Talent Platform, that field or profile should be present in the returned JSON when the same user accesses it via iCIMS Profiles API. (Conversely, if a user does not have access to a field in the Platform, they will not be able to return that field via iCIMS Profiles API.) These permissions are based on the credentials provided in the Authorization header.
GET
In order to be returned in the JSON, the field (or entire Profile) must:
- Have a value.
- Not be hidden by attribute configuration settings.
- Not be hidden by Security Rules.
- Not be hidden by Search Locks.
- Not be hidden by Profile layout configuration (i.e., the tab that the field is on in the Platform cannot be hidden).
POST & PATCH
The same conventions apply for users attempting to save or update information through the Profiles API; if a user could save or update information in the Platform, they should be able to do so via the Profiles API. In addition, in order to save or update a field, that field must:
- Pass field-specific validation.
- Not be hidden by attribute configuration settings.
- Not be locked by attribute configuration settings.
- Not be hidden by Security Rules.
- Not be hidden by Search Locks.
- Not be hidden by Profile layout configuration (i.e., the tab that the field is on in the profile cannot be hidden).
Note:
-
If the Profile is locked in attribute configuration settings, the user can create Profiles (POST) but cannot update them (PATCH). This mimics the behavior in the Platform.
-
Both POST and PATCH will validate that the Profile the user is trying to create or update has all of the required fields filled out. If a user sends a PATCH to update a Profile and the Profile is missing required fields, the PATCH will fail unless the required fields are filled in.
- For Person Profiles, Roles affect validation when POST is used to create a new Person. If the folder used is a Role-specific folder, the required fields on the Role-restricted tabs are validated along with the general Person tab required fields. If using a PATCH, all of the Roles the Person Profile includes will be validated in the same fashion.
- Example: When creating a candidate (Person Profile with the candidate folder), the required field checks will apply to all of the fields that are viewable to a person in general and the tabs restricted to candidate roles. When creating a Person Profile with a non-Role specific folder, the required field checks will apply to all of the fields that are viewable to a person in general with no Role-specific tabs.
- For Person Profiles, Roles can also be assigned using the roles parameter. When using this parameter, required fields are not validated for the assigned role(s). To assign a role, set the specific role (candidate, employee or hiringmanager) to true. If a role should not assigned, set it to false or omit it entirely from the call. Once a role is assigned, it cannot be removed.
- Example: "roles": { "candidate": true, "employee": true, "hiringmanager": false }
- Note: Roles can only be PATCHED via this parameter if at least one other field is included the payload. Roles cannot be PATCHED independently.
Add new Profile of specified type
Expects a Profile JSON object. The JSON object is in the same form as when updating a Profile. The formats of each field when creating/updating vs. retrieving can be slightly different as well (see field types section for details on differences).
Examples below are shown for Job, Person, and New Hire Category Profiles.
Note: Certain fields should be given as IDs, including joblocation, hiringmanager, and jobowner.
URL: https://api.icims.com/customers/{customerId}/{profileType}
{profiletype}
The identifier for people, jobs, companies, new hire categories, or any future custom Profiles. Note that this is case-sensitive.
| Action | Definition |
|---|---|
| Get: |
Not Supported |
| Post: |
Creating a Job Profile https://api.icims.com/customers/1234/jobs POST /customers/1234/jobs HTTP/1.1 Host: api.icims.com
{ "folder": { "id": "C17881", "value": "Approved Q3" }, "jobtitle": "Data Support Analyst", "joblocation": 1049, "hiringmanager": 19981, "field17236": "This Field", "jobowner": 19831 }
Response: Creating a Person Profile https://api.icims.com/customers/1234/people POST /customers/1234/people HTTP/1.1 Host: api.icims.com
{ "folder": { "id": "D32006", "value": "Cand:Unreviewed" }, "email": "someguy@gmail.com", "lastname": "some", "firstname": "guy", "addresses": [ { "addresstype": { "id": "D84002", "value": "Home" }, "addresscountry": { "id": "D41001", "value": "United States" }, "addressstreet1": "123 Streert", "entry": 1351, "addressstate": { "id": "D41001046", "value": "Texas" }, "addresscity": "Austin" } ], "phones": [ { "phonetype": { "id": "D83002", "value": "Home" }, "phonenumber": "5121234567", "entry": 2104 } ] }
Response: Creating a New Hire Category Profile POST/newhirecategories { Response: HTTP/1.1 201 Created |
| Patch: | Not Supported |
| Delete: | Not Supported |
Retrieve and/or update basic Profile information
Retrieve basic information of a specific Profile
When retrieving information from a specific Profile, a JSON object of the Profile is returned. All Profiles have their own set of standard fields that are available (see the separate sections for each Profile type for their fields) along with the read-only fields id, createddate, createdby, updateddate, and updatedby.
Custom fields are included with the attribute name field along with a numeric internal identifier for the field. For example, a custom field could look like field1234. See the field types page for details on how each field type differs in its representation.
When the fields parameter is not specified, the following fields are returned per workflow:
- Person:
- firstname
- lastname
- folder
- phones
- addresses
- Job:
- jobid
- folder
- jobtitle
- hiringmanager
- joblocation
- recruiter
- Company:
- name
- folder
- addresses
- Talent Pool:
- title
- externalid
- owner
- folder
- New Hire Category:
- title
- externaltitle
- folder
Update a specific Profile
When updating a specific Profile, the API expects a JSON object of the Profile in the same form as when creating a Profile, with only the fields to be updated. An id is not necessary, because the URL indicates the Profile the PATCH is based on. The formats of each field when creating/updating vs. retrieving can be slightly different as well (see the field types page for details on differences).
URL: https://api.icims.com/customers/{customerId}/{profileType}/{profileId}
{profileID}
Identifier of the Profile, such as PersonID, JobID, CompanyID. Note that this is case-sensitive.
Note: You can also use the format below to GET basic Person profile information:
https://api.icims.com/customers/{customerId}/people/by-email?email={emailaddress}
{emailaddress}
The Person profile’s Email Address
| Action | Definition |
|---|---|
| Get: |
Retrieving a Person Profile https://api.icims.com/customers/1234/people/5 HTTP/1.1 200 OK { "firstname": "John", "lastname": "Smith", "folder": { "id": D1234, "value": "Cand: Active" }, "email: "john.smith@cool.com", "phones": [ { "phonenumber": "212-555-5555", "phoneextension": "233" } ], "addresses": [ { "addressstreet1”: "123MainStreet", "addressscity": "Hazlet", "addresscountry": { "id": D456, "value": "UnitedStates" } "entry": 12 } ] }
Retrieving a New Hire Category Profile GET /newhirecategories/{profileID} { |
| Post: | Not Supported |
| Patch: |
Updating a Person Profile https://api.icims.com/customers/1234/people/7 { "folder": { "id": "D123" }, "middlename": "Edward" }
Response: Updating a New Hire Category Profile PATCH /newhirecategories/{profileID} { RETURN HTTP/1.1 204 No Content |
| Delete: | Not Supported |
Get and/or update only the specific fields on the specified Profile
See below for an example updating specific fields on the Person profile.
URL: https://api.icims.com/customers/{customerId}/{profileType}/{profileId}?fields={fieldId1,fieldId2,fieldId3}
{fieldId1,fieldId2,fieldId3}
Comma delimited list of fields to include from the requested Profile.
Note: You can also use the format below to GET specific fields on the specified Person profile:
https://api.icims.com/customers/{customerId}/people/by-email?email={emailaddress}?fields={fieldId1,fieldId2,fieldId3}
{emailaddress}
The Person profile’s Email Address
| Action | Definition |
|---|---|
| Get: |
Get only the specific fields on the specified Profile https://api.icims.com/customers/1234/people/5?fields=folder,field1579,createdby HTTP/1.1 200 OK
{ "id": 5, "folder": { "id": 1234, "value": "Cand:Active" }, "createdby": { "id": 3, "value": "Bob Smith", "profile": "https://api.icims.com/customers/1234/people/3/" }, "field1579": "Advanced" } |
| Post: | Not Supported |
| Patch: | The fields query parameter is ignored in this case, and all fields sent in the JSON are updated. |
| Delete: | Not Supported |
Get the System ID of a Job, Person, or Company Profile using the External ID
This endpoint allows a vendor to exact-match search based on a Job, Person, or Company's External ID. If found, the profile's System ID will be returned.
Note that this endpoint can only be used to search for Job, Person, and Company Profiles at this time.
URL: https://api.icims.com/customers/{customerId}/{profileType}/lookup?type=externalid&value={externalId_value}
{externalId_value}
The external ID of the Job, Person, or Company
| Action | Definition |
|---|---|
| Get: |
Example request:
GET /customers/1771/jobs/lookup?type=externalid&value=12345 HTTP/1.1 Host: api.icims.com Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= Content-Type: application/json Cache-Control: no-cache
Example Response Payload:
{ "id": 1013 } |
| Errors: |
The following errors may be returned. If no profiles match the provided external ID: { "errors": [ { "errorMessage": "No profile found matching external ID", "errorCode": 33 } ] }
If more than one profile matches the provided external ID:
{ "errors": [ { "errorMessage": "More than one profile matches external ID", "errorCode": 33 } ] }
If attempting to look up a profile that does not support this endpoint:
{ "errors": [ { "errorMessage": "For input string: \"lookup\"", "errorCode": 2 } ] } |