ClearCompany REST API Specifications.v1.02

REST API Specifications
Version 1.02
Introduction
ClearCompany has developed the following specifications to make it easy for you to closely integrate your existing
systems with ClearCompany applications and tools. We use a variety of open technical standards including REST,
JSON and others and encourage you to ask for direction or assistance if anything should arise during your
integration process.
If you have any questions regarding the contents of this specification, please contact your customer service
representative.
Contents
Introduction ................................................................................................................................................................... 1
Contents ........................................................................................................................................................................ 2
1. Web Services ......................................................................................................................................................... 6
2. Code Samples ........................................................................................................................................................ 6
3. Instantiating Requests ........................................................................................................................................... 6
Protocols ........................................................................................................................................................ 6
Authentication ............................................................................................................................................... 6
Response Codes ............................................................................................................................................. 8
Response Content Type ................................................................................................................................. 8
API Rate Limits ............................................................................................................................................... 8
4. Collections ............................................................................................................................................................. 9
Retrieve Countries ......................................................................................................................................... 9
Retrieve EEO Types ...................................................................................................................................... 10
Retrieve Budget Types ................................................................................................................................. 11
Retrieve Job Functions ................................................................................................................................ 12
Retrieve Industries....................................................................................................................................... 13
Retrieve Requisition Custom Fields ............................................................................................................. 14
Retrieve Candidate Custom Fields............................................................................................................... 16
Retrieve Forms ............................................................................................................................................ 17
Retrieve Candidate Workflow Stages .......................................................................................................... 18
Retrieve Genders ......................................................................................................................................... 18
Retrieve Ethnicities ...................................................................................................................................... 19
Retrieve Races ............................................................................................................................................. 20
Retrieve Legacy Veteran Status ................................................................................................................... 21
ClearCompany REST API Specification - Confidential Page 2

Retrieve Veteran Status: Pre-Offer.............................................................................................................. 22
Retrieve Veteran Status: Post-Offer ............................................................................................................ 23
Retrieve Disability Status: Pre-Offer ............................................................................................................ 24
Retrieve Disability Status: Post-Offer .......................................................................................................... 24
5. Office Requests .................................................................................................................................................... 25
Retrieve All Active Offices ........................................................................................................................... 25
Retrieve an Office by Office Id..................................................................................................................... 25
Retrieve an Office by Custom Office Id ....................................................................................................... 26
Create a New Office..................................................................................................................................... 26
Update an Office by Office Id ...................................................................................................................... 27
Update an Office by Custom Office Id ......................................................................................................... 28
Retrieve an Office Address by Office Id ....................................................................................................... 28
Retrieve an Office Address by Custom Office Id ......................................................................................... 29
Update an Office Address by Office Id ........................................................................................................ 29
Update an Office Address by Custom Office Id ........................................................................................... 30
6. Department Requests.......................................................................................................................................... 31
Retrieve All Active Departments ................................................................................................................. 31
Retrieve a Department by Department Id................................................................................................... 31
Retrieve a Department by Custom Department Id ..................................................................................... 32
Create a New Department .......................................................................................................................... 32
Update a Department by Office Id .............................................................................................................. 33
Update a Department by Custom Department Id ....................................................................................... 33
7. User Requests ...................................................................................................................................................... 34
Retrieve a User by User Id ........................................................................................................................... 34
Update a User by User Id............................................................................................................................. 35

Terminate a User Immediately by User Id................................................................................................... 36
Terminate a User on a Specific Date by User Id .......................................................................................... 36
Get Status for a Pending Termination for a User by User Id ....................................................................... 37
Cancel a Pending Termination for a User by User Id ................................................................................... 37
Restore a Terminated User by User Id ........................................................................................................ 37
8. User Account Requests ........................................................................................................................................ 38
Retrieve a User Account by User Id ............................................................................................................. 38
Create a User Account ................................................................................................................................. 39
Update a User Account by User Id .............................................................................................................. 40
Update a User Account by Custom Employee Id......................................................................................... 42
Retrieve User Account Permissions by User Id ........................................................................................... 44
Retrieve User Account Permissions by Employee Id ................................................................................... 44
Retrieve All Active or Inactive User Accounts ............................................................................................. 44
Retrieve All Active or Inactive User Accounts By Role ................................................................................ 45
9. Requisition Requests ........................................................................................................................................... 47
9.1.1 Retrieve a Requisition by Requisition Id .............................................................................................. 47
9.1.2 Retrieve a Requisition by Custom Requisition Id ................................................................................ 49
Create a New Requisition ............................................................................................................................ 51
Update Requisition By Requisition Id .......................................................................................................... 55
Listing Requisitions ...................................................................................................................................... 59
9.4.1 Get Requisitions By Status ................................................................................................................... 59
10. Applicant and Candidate Requests – A Primer ................................................................................................ 61
11. Applicant Requests .......................................................................................................................................... 61
Retrieve an Applicant Record ...................................................................................................................... 61
Retrieve an Applicant’s Onboarding Records .............................................................................................. 61

12. Candidate Requests ......................................................................................................................................... 63
Retrieve a Candidate by Candidate Id ......................................................................................................... 63
Retrieve Candidate Demographics by Candidate Id .................................................................................... 64
Retrieve Candidates by Requisition Id......................................................................................................... 65
Retrieve Candidates by Requisition Id and Current Workflow ................................................................... 66
Retrieve Candidates by Requisition Id and Historical Workflow ................................................................. 66
13. Appendix A ...................................................................................................................................................... 67
Permissions/User Rights/Roles.................................................................................................................... 67
Country Names & Codes.............................................................................................................................. 67
OData Properties ......................................................................................................................................... 72
API Changes ................................................................................................................................................. 72
13.4.1 Legacy API Base URL ............................................................................................................................ 72
13.4.2 Legacy Header Information ................................................................................................................. 73
13.4.3 Document Revisions and API Changes ................................................................................................ 73

1. Web Services
The API actions described in this document are accessed using RESTful HTTP requests to the ClearCompany
servers. As HTTP and JSON are open standards that can be used from nearly every programming language, we
recommend you look up how your specific programming language implements these technologies before trying to
use this integration document. For a brief background on RESTful web services see
http://en.wikipedia.org/wiki/Representational_state_transfer#RESTful_web_services. In order to access the
ClearCompany REST API you must provide a basic authentication API User Name and password which is available
through your customer service representative.
2. Code Samples
ClearCompany provides some limited code samples that accompany this documentation. These code samples are
provided "as is" and are meant only as a starting point for your integration with the ClearCompany web services.
Please feel free to modify them as needed in order to fit into your own implementation.
3. Instantiating Requests
Protocols
The ClearCompany REST API requires that all requests be made securely over HTTPS/SSL using port 443.
Authentication
Unless otherwise noted, all API endpoints require authentication in order to successfully complete the
request. To get an authentication token, pass Basic Authentication header information to an authentication
endpoint. For more information on Basic Authentication, see
http://en.wikipedia.org/wiki/Basic_access_authentication
The basic authentication scheme consists of adding a header value for "Authentication" with a value that
combines the username and password, separated by a colon, then base64 encoded. The pseudo code
would look like this:
request.addHeader("Authorization", "Basic" + base64encode("abcusername:abcuserpassword"));
Failure to provide a valid username and password, or if the account or organization has been disabled, will
result in a 401 Unauthorized response.
All API requests also require that you add a header value to identify the API that you are trying to access.
For all requests made to API endpoints in this document you will need to add the following header values:
API-Realm: CCAPI
Given a username of "abcusername" and a password of "abcuserpassword", the full formatted, required
header values for a basic authentication request would be as follows:
Authorization: Basic YWJjdXNlcm5hbWU6YWJjdXNlcnBhc3N3b3Jk

API-Realm: CCAPI

Note that while these are the only header fields that ClearCompany requires, the HTTP spec will require
additional fields, especially when doing POST and PUT requests, which often require Content-Length and
Content-Type values.
The authorization request is made to the following endpoint:
https://api.clearcompany.com/v1/users/auth/authenticate
The authorization response headers will contain the following API-Token that is required for subsequent
requests:
API-Token: OWQ1NWM2ZjMtODIyMy1mZDQzLTI5NjUtMmY0ZGUxMWY5OGA3
The pseudo code below shows how to make an authorization request and retrieving the authorization
token in order to call the endpoints described in this API guide. NOTE: This pseudo code does not include
checking for successful HTTP requests or exception handling that should be part of your code.
// Call authorization endpoint to get an API token to use on all subsequent requests
HttpClient restClient = new HttpClient();
restClient.AddHeader("Authorization", "Basic" + Base64encode("abcusername:abcuserpassword");
restClient.AddHeader("API-Realm", "CCAPI");
HttpClientResponse response = restClient.SendRequest(HttpVerb.GET,

. "https://api.clearcompany.com/v1/users/auth/authenticate");
if(response.Status != 200)
{
throw new Exception("Problem getting authorization token");
}
// Retrieve the API-Token header value

string apiToken = response.Headers["API-Token"];
// Set up a new http request using the token.

// Clear the previous headers so we *don’t* send the Authorization headers
restClient.Headers.Clear();
restClient.AddHeader("API-Token", apiToken);
restClient.AddHeader("API-Realm", "CCAPI");
// Retrieve all active offices

response = restClient.SendRequest(HttpVerb.GET,
. "https://api.clearcompany.com/v1/offices/active");
// Deserialize the JSON response body into a list of offices

List<Office> offices = Deserialize<List<Office>>(response.Body);
// Retrieve a user
string userGuid = "449ec217-8527-a445-90e8-9a78646ed5e6";
response = restClient.SendRequest(HttpVerb.GET,
. "https://api.clearcompany.com/v1/users/"+ userGuid +"/account");
// Deserialize the JSON response body into a list of offices

UserAccount user = Deserialize<UserAccount>(response.Body);

Response Codes
In accordance with the W3C HTTP spec, all responses will conform to the RFC spec.
Response Content Type

Unless otherwise specified, all content will be returned in JSON format.
API Rate Limits

Unless otherwise specified by your customer service representative, you should not exceed 15 requests
per second per set of issued credentials. Requests above the rate limit may be refused.

4. Collections
Retrieve Countries
Purpose: To retrieve the list of countries from the ClearCompany System.
Authentication: No Auth Required
Location: https://api.clearcompany.com/v1/collections/countries
Request Method: GET
Successful Response Code: 200 OK
Response Content Type: application/json
This endpoint is OData queryable: See the appendix for OData filtering examples.
Note: Sample output truncated for visibility.
Sample Response Content:
[
{
"CountryCode": "AF",
"Name": "AFGHANISTAN"
},
{
"CountryCode": "AX",
"Name": "ALAND ISLANDS"
},
{
"CountryCode": "AL",
"Name": "ALBANIA"
},
…
{
"CountryCode": "US",
"Name": "UNITED STATES"
},
…
]

Retrieve EEO Types
Purpose: To retrieve the list of available EEO Codes and Descriptions.
Location: https://api.clearcompany.com/v1/collections/eeo/types
Request Method: GET
[
{
"Id": "00000000-0000-0000-0000-000000000000",
"Code": "NotSet",
"Name": "Not Set"
},
{
"Id": "b12c90e4-012e-0000-0000-000000000000",
"Code": "ExecutiveAndSeniorLevelManagers",
"Name": "Executive/Senior Level Officials and Managers"
},
{
"Id": "4cc73f20-0126-0000-0000-000000000000",
"Code": "FirstAndMidLevelManagers",
"Name": "First/Mid-Level Officials and Managers"
},
{
"Id": "3e2d57a4-0127-0000-0000-000000000000",
"Code": "Professionals",
"Name": "Professionals"
},
{
"Id": "29acd168-0128-0000-0000-000000000000",
"Code": "Technicians",
"Name": "Technicians"
},
{
"Id": "1b12e9ec-0129-0000-0000-000000000000",
"Code": "SalesWorker",
"Name": "Sales Worker"
},
{
"Id": "05fb53d0-012a-0000-0000-000000000000",
"Code": "AdministrativeSupportWorkers",
"Name": "Administrative Support Workers"
},
{
"Id": "f7616c54-012a-0000-0000-000000000000",
"Code": "SkilledCraftWorkers",
"Name": "Craft Workers(Skilled)"
},
{
"Id": "e2e0e618-012b-0000-0000-000000000000",
"Code": "SemiSkilledOperatives",
"Name": "Operatives(Semi-Skilled)"
},
{
"Id": "d446fe9c-012c-0000-0000-000000000000",
"Code": "LaborersAndHelpers",
"Name": "Laborers and Helpers"
},
{
"Id": "bfc67860-012d-0000-0000-000000000000",
"Code": "ServiceWorkers",
"Name": "Service Workers"
}
]

Retrieve Budget Types
Purpose: To retrieve the list of available Budget Codes and Descriptions.
Location: https://api.clearcompany.com/v1/collections/budget/types
Request Method: GET
[
{
"Id": "00000000-0000-0000-0000-000000000000",
"Code": "NotSet",
"Name": "Not Set"
},
{
"Id": "4cc73f20-0126-0000-0000-000000000000",
"Code": "BudgetedAddition",
"Name": "Budgeted Addition"
},
{
"Id": "3e2d57a4-0127-0000-0000-000000000000",
"Code": "BudgetedReplacement",
"Name": "Budgeted Replacement"
},
{
"Id": "29acd168-0128-0000-0000-000000000000",
"Code": "BudgetedTemporary",
"Name": "Budgeted Temporary"
},
{
"Id": "1b12e9ec-0129-0000-0000-000000000000",
"Code": "UnbudgetedAddition",
"Name": "Unbudgeted Addition"
},
{
"Id": "05fb53d0-012a-0000-0000-000000000000",
"Code": "UnbudgetedReplacement",
"Name": "Unbudgeted Replacement"
},
{
"Id": "f7616c54-012a-0000-0000-000000000000",
"Code": "UnbudgetedTemporary",
"Name": "Unbudgeted Temporary"
},
{
"Id": "e2e0e618-012b-0000-0000-000000000000",
"Code": "BudgetedContractor",
"Name": "Budgeted Contractor"
},
{
"Id": "d446fe9c-012c-0000-0000-000000000000",
"Code": "UnbudgetedContractor",
"Name": "Unbudgeted Contractor"
},
{
"Id": "bfc67860-012d-0000-0000-000000000000",
"Code": "BudgetedInternship",
"Name": "Budgeted Internship"
},
{
"Id": "b12c90e4-012e-0000-0000-000000000000",
"Code": "UnbudgetedInternship",
"Name": "Unbudgeted Internship"
}
]

Retrieve Job Functions
Purpose: To retrieve the list of available Job Function Codes and Descriptions.
Location: https://api.clearcompany.com/v1/collections/jobfunctions
Request Method: GET
[
{
"Id": "f7616c54-012a-0000-0000-000000000000",
"Code": "AccountingFinance",
"Name": "Accounting/Finance"
},
{
"Id": "e2e0e618-012b-0000-0000-000000000000",
"Code": "AdminClericalSecretarial",
"Name": "Admin/Clerical/Secretarial"
},
{
"Id": "d446fe9c-012c-0000-0000-000000000000",
"Code": "BusinessDevelopment",
"Name": "Business Development"
},
…
{
"Id": "2e72ca1c-0143-0000-0000-000000000000",
"Code": "StrategyPlanning",
"Name": "Strategy/Planning"
},
{
"Id": "19f243e0-0144-0000-0000-000000000000",
"Code": "SupplyChain",
"Name": "Supply Chain"
}
]

Retrieve Industries
Purpose: To retrieve the list of available Industry Codes and Descriptions.
Location: https://api.clearcompany.com/v1/collections/industries
Request Method: GET
[
{
"Id": "0b585c64-0145-0000-0000-000000000000",
"Code": "AdvertisingMarketing",
"Name": "Advertising / Marketing"
},
{
"Id": "f6d7d628-0145-0000-0000-000000000000",
"Code": "Agricultural",
"Name": "Agricultural"
},
{
"Id": "e83deeac-0146-0000-0000-000000000000",
"Code": "AirlineAerospaceAviation",
"Name": "Airline/Aerospace/Aviation"
},
…
{
"Id": "ab2f6d28-0172-0000-0000-000000000000",
"Code": "TrainingTrainingProducts",
"Name": "Training/Training Products"
},
{
"Id": "9c9585ac-0173-0000-0000-000000000000",
"Code": "TransportationShipping",
"Name": "Transportation / Shipping"
}
]

Retrieve Requisition Custom Fields
Purpose: To retrieve the list of available Req Custom Fields and Options.
Authentication: Required (Any Authenticated User Type)
Location: https://api.clearcompany.com/v1/collections/reqs/customfields
Request Method: GET
[
{
"CustomFieldGuid": "cd58d456-02e5-425e-a034-b352c621991b",
"Name": "Category",
"Description": "Single-selection type",
"FamilyType": "ReqCustomField",
"FieldType": "LegacySingleSelect",
"DisplayOrder": 0,
"IsRequired": true,
"IsInternal": true,
"SourceType": "ReqCustomField",
"SourceProperty": "",
"Options": [
{
"OptionGuid": "fd589e71-94da-4ea8-9172-05f59b2b4f1d",
"FieldGuid": "cd58d456-02e5-425e-a034-b352c621991b",
"Text": "Exempt",
"Value": "Exempt",
"IsDefault": false,
"DisplayOrder": 0
},
{
"OptionGuid": "90974412-f3f4-4343-8140-a63b56feb4a7",
"FieldGuid": "cd58d456-02e5-425e-a034-b352c621991b",
"Text": "Hourly",
"Value": "Hourly",
"IsDefault": false,
"DisplayOrder": 0
}
]
},
{
"CustomFieldGuid": "538109d0-ac51-4a00-872e-2cef46e340dd",
"Name": "Advertising Costs",
"Description": "Total cost allowed for advertising this req",
"FieldType": "LegacyTextBox",
"DisplayOrder": 1,
"IsRequired": false,
"IsInternal": true,
"Options": null
},
{
"CustomFieldGuid": "c79d529b-3bc8-4b08-80f7-502d4381d787",
"Name": "Division",
"Description": "Division Single-Select",
"DisplayOrder": 2,
"IsRequired": true,
"IsInternal": true,
"Options": [
{
"OptionGuid": "397df725-f03c-403d-b70c-60ac6c143e3a",
"FieldGuid": "c79d529b-3bc8-4b08-80f7-502d4381d787",
"Text": "IT",
"Value": "IT",

"IsDefault": false,
"DisplayOrder": 0
},
{
"OptionGuid": "67c04cb0-de69-47b1-8693-465f09bd6773",
"Text": "Accounting",
"Value": "Accounting",
"IsDefault": false,
"DisplayOrder": 1
},
{
"OptionGuid": "69fe2ff0-381f-45d3-8272-fda0e5cfbfaf",
"Text": "Sales",
"Value": "Sales",
"IsDefault": false,
"DisplayOrder": 2
}
]
}
]

Retrieve Candidate Custom Fields
Purpose: To retrieve the list of available Candidates Custom Fields and Options.
Location: https://api.clearcompany.com/v1/collections/candidates/customfields
Request Method: GET
[
{
"CustomFieldGuid": "067fc66c-0160-4c29-8c73-a53012198665",
"Name": "Internal Source Id",
"Description": "Textbox type",
"FamilyType": "CandCustomField",
"FieldType": "LegacyTextBox",
"DisplayOrder": 1,
"IsInternal": true,
"SourceType": "CandCustomField",
"Options": null
},
{
"CustomFieldGuid": "fa9a51ca-f007-4fb5-a778-45a22f6abfef",
"Name": "Organizational Development",
"Description": "Choose the development track for this candidate",
"DisplayOrder": 3,
"IsInternal": true,
"Options": [
{
"OptionGuid": "a3bda5d1-3dad-46fa-8be2-7484dc3245f9",
"FieldGuid": "fa9a51ca-f007-4fb5-a778-45a22f6abfef",
"Text": "HIPO (High Potential)",
"Value": "HIPO (High Potential)",
"IsDefault": true,
"DisplayOrder": 0
},
{
"OptionGuid": "1de44b11-9fed-40d0-9355-0961b2845165",
"FieldGuid": "fa9a51ca-f007-4fb5-a778-45a22f6abfef",
"Text": "Standard Track",
"Value": "Standard Track",
"IsDefault": false,
"DisplayOrder": 0
}
]
},
{
"CustomFieldGuid": "1eb373e5-536c-455a-a3c3-e251116541e5",
"Name": "Phone Screen: Did the candidate meet the requirements for this stage?",
"Description": "Please explain",
"FieldType": "LegacyTextArea",
"DisplayOrder": 5,
"IsInternal": true,
"Options": null
}
]

Retrieve Forms
Purpose: To retrieve the list of forms currently in use.
Location: https://api.clearcompany.com/v1/collections/forms
Request Method: GET
[
{
"FormId": "2ff9960f-fa72-4635-8b90-1a1f13bfc48b",
"Name": "2014 I-9",
"Description": "I-9 2014",
"FormFamily": "EmployeeLifeCycle",
"FormTypeId": "f043fb2d-5228-400e-ac24-a47d8528f1e5",
"FormType": "Onboarding"
},
{
"FormId": " 8805c9e0-9fd4-4673-ac07-5000fe2ec36f",
"Name": "2014 W-4",
"Description": "",
"FormTypeId": "d300b864-018b-0000-0000-000000000000",
},
{
"FormId": "be803228-018c-0000-0000-000000000000",
"Name": "2012 W-4",
"Description": "2012 standard W-4",
"FormTypeId": "d300b864-018b-0000-0000-000000000000",
}
]

Retrieve Candidate Workflow Stages
Purpose: To retrieve the list of available Candidates Workflow Stages.
Location: https://api.clearcompany.com/v1/collections/candidates/workflow
Request Method: GET
Note: Workflow values are customizable. The values below are just an example of formatting.
[
{
"WorkflowId": "0712988c-09e0-4ed2-91ff-e85d1158f427",
"Name": "Flagged for follow up",
"Description": "",
"Order": 1
},
{
"WorkflowId": "94d72abf-e35b-4c40-8295-a1c57d355257",
"Name": "No Response",
"Description": "",
"Order": 2
},
{
"WorkflowId": "9aa2fff0-5da6-4b7c-93ee-851f0c3b4aac",
"Name": "Interview Scheduled",
"Description": "",
"Order": 3
},
{
"WorkflowId": "a151528f-7324-43c6-ab61-8cd6f4875a27",
"Name": "Interview Completed",
"Description": "",
"Order": 4
}
]
Retrieve Genders
Purpose: To retrieve the list of available genders
Location: https://api.clearcompany.com/v1/collections/gender
Request Method: GET
[
{
"Code": "not.specified",
"Name": "Not Specified"
},
{
"Code": "female",
"Name": "Female"
},
{
"Code": "male",
"Name": "Male"
}
]

Retrieve Ethnicities
Purpose: To retrieve the list of available ethnicities.
Location: https://api.clearcompany.com/v1/collections/ethnicity
Request Method: GET
[
{
"Id": 1,
"Name": "Unknown"
},
{
"Id": 2,
"Name": "Hispanic / Latino"
},
{
"Id": 3,
"Name": "Non-Hispanic / Non-Latino"
},
{
"Id": 4,
"Name": "I choose not to self-identify at this time"
}
]

Retrieve Races
Purpose: To retrieve the list of available races.
Location: https://api.clearcompany.com/v1/collections/race
Request Method: GET
[
{
"Id": 1,
"Name": "Unknown"
},
{
"Id": 2,
"Name": "Asian"
},
{
"Id": 3,
"Name": "American Indian, Alaskan"
},
{
"Id": 4,
"Name": "Black / African American"
},
{
"Id": 5,
"Name": "Native Hawaiian / Other Pacific Islander"
},
{
"Id": 6,
"Name": "White"
},
{
"Id": 7,
"Name": "I choose not to self-identify at this time"
}
]

Retrieve Legacy Veteran Status
Purpose: To retrieve the list legacy veteran status options.
Note: This result includes active and inactive values (for backwards compatibility purposes).
Location: https://api.clearcompany.com/v1/collections/veteran/status/legacy
Request Method: GET
[
{
"Active": false,
"Code": "U",
"Name": "Unknown Veteran Status"
},
{
"Active": true,
"Code": "N",
"Name": "Not a Veteran"
},
{
"Active": false,
"Code": "V",
"Name": "Vietnam Veteran"
},
{
"Active": false,
"Code": "S",
"Name": "Special Disabled Veteran"
},
{
"Active": false,
"Code": "O",
"Name": "Other War Veteran"
},
{
"Active": true,
"Code": "D",
"Name": "Disabled Veteran"
},
{
"Active": true,
"Code": "L",
"Name": "Recently Separated Veteran"
},
{
"Active": true,
"Code": "P",
"Name": "Other Protected Veteran"
},
{
"Active": true,
"Code": "A",
"Name": "Armed Forces Service Medal Veteran"
},
{
"Active": true,
"Code": "I",
"Name": "I Choose Not To Self-Identify"
}
]

Retrieve Veteran Status: Pre-Offer
Purpose: To retrieve the list of veteran status pre-offer options.
Location: https://api.clearcompany.com/v1/collections/veteran/status/preoffer
Request Method: GET
[
{
"Id": 0,
"Name": "Unknown"
},
{
"Id": 1,
"Name": "I am not a protected veteran"
},
{
"Id": 2,
"Name": "I identify as one or more of the classifications of protected veterans"
}
]

Retrieve Veteran Status: Post-Offer
Purpose: To retrieve the list of veteran status post-offer options.
Location: https://api.clearcompany.com/v1/collections/veteran/status/postoffer
Request Method: GET
[
{
"Id": 0,
"Name": "Unknown"
},
{
"Id": 1,
"Name": "I am not a protected veteran"
},
{
"Id": 2,
"Name": "I am a protected veteran but I choose not to self-identify the classifications to
which I belong"
},
{
"Id": 3,
"Name": "Disabled Veteran"
},
{
"Id": 4,
"Name": "Recently Separated Veteran"
},
{
"Id": 5,
"Name": "Active Wartime or Campaign Badge Veteran"
},
{
"Id": 6,
"Name": "Armed Forces Service Medal Veteran"
}
]

Retrieve Disability Status: Pre-Offer
Location: https://api.clearcompany.com/v1/collections/disability/status/preoffer
Request Method: GET
[
{
"Id": 0,
"Name": "Unknown"
},
{
"Id": 0,
"Name": "Yes, I have a disability"
},
{
"Id": 0,
"Name": "No, I do not have a disability"
},
{
"Id": 0,
"Name": "I don't wish to answer"
}
]
Retrieve Disability Status: Post-Offer

Location: https://api.clearcompany.com/v1/collections/disability/status/postoffer
Request Method: GET
[
{
"Id": 0,
"Name": "Unknown"
},
{
"Id": 0,
"Name": "Yes, I have a disability"
},
{
"Id": 0,
"Name": "No, I do not have a disability"
},
{
"Id": 0,
"Name": "I don't wish to answer"
}
]

5. Office Requests
Retrieve All Active Offices
Purpose: To retrieve a list of all active offices.
Location: https://api.clearcompany.com/v1/offices/active
Request Method: GET
[
{
"OfficeGuid": "c7320bb4-d24d-44bd-8073-2ecdea13991f",
"CoordinatorUserGuid": "00000000-0000-0000-0000-000000000000",
"CustomOfficeId": "Custom-Office-ID-479",
"Name": "Boston",
"CreatedDate": "2013-01-31T16:29:44Z",
"Phone": "617-901-1919",
"Fax": "617-555-1212",
"Active": true
},
{
"OfficeGuid": "47855d8e-0a3c-4071-9464-641e27574ec1",
"CustomOfficeId": "Another-Custom-Office-ID-524",
"Name": "Los Angeles",
"CreatedDate": "2013-01-31T17:02:58Z",
"Phone": null,
"Fax": null,
"Active": true
}
]
Retrieve an Office by Office Id

Purpose: To retrieve an office by providing the office id.
Location: https://api.clearcompany.com/v1/offices/{OfficeIdValue}
Example Location: https://api.clearcompany.com/v1/offices/c7320bb4-d24d-44bd-8073-2ecdea13991f
Request Method: GET
{
"Name": "Boston",
"CreatedDate": "2013-01-31T16:29:44Z",
"Phone": "617-901-1919",
"Fax": "617-555-1212",
"Active": true
}

Retrieve an Office by Custom Office Id
Purpose: To retrieve an office by providing the assigned custom office Id.
This is useful when you want to keep the ClearCompany Data in sync with your own records.
With this, you can set a custom id (your internal office id) and then retrieve
the record without knowing the ClearCompany Office Id.
Note: Custom Office Id’s can be any string or integer value.
Custom Office Id lookups are case insensitive.
Location: https://api.clearcompany.com/v1/offices/custom/{CustomOfficeIdValue}
Example Location: https://api.clearcompany.com/v1/offices/custom/Custom-Office-ID-479
Request Method: GET
{
"Name": "Boston",
"CreatedDate": "2013-01-31T16:29:44Z",
"Phone": "617-901-1919",
"Fax": "617-555-1212",
"Active": true
}
Create a New Office

Purpose: To create a new office in the ClearCompany System.
Authentication: Required (User Admin)
Location: https://api.clearcompany.com/v1/offices
Request Method: POST
Required Fields: Name (string)
Sample Request Content:
{
"CustomOfficeId": "Office-32",
"Name": "Miami",
"Phone": "305-555-1919",
"Fax": "305-555-2147"
}
Successful Response Code: 201 Created

Additional Response Headers:
Location: https://api.clearcompany.com/v1/offices/63b618a6-92e7-4719-a3d8-3220635279e6

{
"OfficeGuid": "63b618a6-92e7-4719-a3d8-3220635279e6",
"Name": "Miami",
"CreatedDate": "2013-01-31T16:29:44Z",
"Phone": "305-555-1919",
"Fax": "305-555-2147",
"Active": true
}

Update an Office by Office Id
Purpose: To update an office by providing the office id.
Location: https://api.clearcompany.com/v1/offices/{OfficeIdValue}
Example Location: https://api.clearcompany.com/v1/offices/63b618a6-92e7-4719-a3d8-3220635279e6
Required Fields: None – Partial updates allowed.
{
"CoordinatorUserGuid": "97e40760-93c7-4ad0-94f9-ea1c32e29f74",
"Name": "Miami Updated",
"Phone": "305-555-2342",
"Fax": "305-555-1234"
}

{
"CoordinatorUserGuid": "97e40760-93c7-4ad0-94f9-ea1c32e29f74",
"Name": "Miami Updated",
"CreatedDate": "2013-01-31T16:29:44Z",
"Phone": "305-555-2342",
"Fax": "305-555-1234",
"Active": true
}

Update an Office by Custom Office Id
Purpose: To update an office by providing the assigned custom office id.
With this, you can set a custom id (your internal office id) and then update
the office record without knowing the ClearCompany Office Id.
Location: https://api.clearcompany.com/v1/offices/custom/{CustomOfficeIdValue}
Example Location: https://api.clearcompany.com/v1/offices/custom/Office-35
{
"CoordinatorUserGuid": " 133e8c90-37c8-45dc-b24e-3493dcd71084",
"Name": "Miami Updated Again",
"Phone": "305-555-8787",
"Fax": "305-555-6959"
}

{
"CoordinatorUserGuid": " 133e8c90-37c8-45dc-b24e-3493dcd71084",
"Name": "Miami Updated Again",
"CreatedDate": "2013-01-31T16:29:44Z",
"Phone": "305-555-8787",
"Fax": "305-555-6959",
"Active": true
}
Retrieve an Office Address by Office Id

Purpose: To retrieve an office address by providing the office Id.
Location: https://api.clearcompany.com/v1/offices/{OfficeIdValue}/address
Example Location: https://api.clearcompany.com/v1/offices/c7320bb4-d24d-44bd-8073-2ecdea13991f/address
Request Method: GET
{
"AddressGuid": "f54d329c-cb9b-0002-0000-000000000000",
"Street": "7 Main Street",
"Street2": "Suite 3",
"City": "Concord",
"State": "MA",
"ZipCode": "02458",
"Country": "US",
"Province": "Massachusetts",
"AbbProvince": "MA",
"CountryName": "UNITED STATES"
}

Retrieve an Office Address by Custom Office Id
Purpose: To retrieve an office address by providing the office Id.
Location: https://api.clearcompany.com/v1/offices/custom/{CustomOfficeIdValue}/address
Example Location: https://api.clearcompany.com/v1/offices/custom/SomeCustomOfficeId/address
Request Method: GET
{
"Street": "7 Main Street",
"Street2": "Suite 3",
"City": "Concord",
"State": "MA",
"ZipCode": "02458",
"Country": "US",
}
Update an Office Address by Office Id

Purpose: To update an office address by providing the office Id.
Location: https://api.clearcompany.com/v1/offices/{OfficeIdValue}/address
Example Location: https://api.clearcompany.com/v1/offices/c7320bb4-d24d-44bd-8073-2ecdea13991f/address
Required Fields: None - Partial updates allowed.
Note: If you are updating the Country or CountryName values, then they must match one of
the provided values found in Appendix B.
No address fields are required in the system, but a minimum of City, State, ZipCode are
suggested.
{
"Street": "525 Washington Street",
"Street2": "Third Floor",
"City": "Bedford",
"State": "MA",
"ZipCode": "02154",
"Country": "US",
}

{
"City": "Bedford",
"State": "MA",
"ZipCode": "02154",
"Country": "US",
}

Update an Office Address by Custom Office Id
Purpose: To update an office address by providing the assigned custom office Id.
With this, you can set a custom id (your internal office id) and then update
the address record without knowing the ClearCompany Office Id.
Location: https://api.clearcompany.com/v1/offices/custom/{CustomOfficeIdValue}/address
Example Location: https://api.clearcompany.com/v1/offices/custom/SomeCustomOfficeId/address
Note: If you are updating the Country or CountryName values, then they must match one of
the provided values found in Appendix B.
No address fields are required in the system, but a minimum of City, State, ZipCode are
suggested.
{
"City": "Bedford",
"State": "MA",
"ZipCode": "02154",
"Country": "US",
}

{
"City": "Bedford",
"State": "MA",
"ZipCode": "02154",
"Country": "US",
}

6. Department Requests
Retrieve All Active Departments
Purpose: To retrieve a list of all active departments.
Location: https://api.clearcompany.com/v1/departments/active
Request Method: GET
[
{
"DepartmentGuid": " bf0e5497-1f9b-4080-a061-13e71921467c",
"CustomDepartmentId": "Dept-IT-945",
"IndustryGuid": "00000000-0000-0000-0000-000000000000",
"BusinessFunctionGuid": "00000000-0000-0000-0000-000000000000",
"Name": "Information Technology",
"CreatedDate": "2013-01-30T21:24:33Z",
"Active": true,
"Phone": "617-555-2322",
"Fax": "617-555-9282"
},
{
"DepartmentGuid": "176b829c-68c6-43d3-9cfe-f8e71f8953af",
"CustomDepartmentId": "Dept-Accounting",
"IndustryGuid": "00000000-0000-0000-0000-000000000000",
"Name": "Accounting",
"CreatedDate": "2013-01-30T21:35:03Z",
"Active": true,
"Phone":"617-555-8988",
"Fax": "617-555-8002"
}
]
Retrieve a Department by Department Id

Purpose: To retrieve an office by providing the assigned custom office id.
Location: https://api.clearcompany.com/v1/departments/{DepartmentIdValue}
Example Location: https://api.clearcompany.com/v1/departments/bf0e5497-1f9b-4080-a061-13e71921467c
Request Method: GET
{
"DepartmentGuid": "bf0e5497-1f9b-4080-a061-13e71921467c",
"IndustryGuid": "00000000-0000-0000-0000-000000000000",
"CreatedDate": "2013-01-30T21:24:33Z",
"Active": true,
"Phone": "617-555-2322",
"Fax": "617-555-9282"
}

Retrieve a Department by Custom Department Id
Purpose: To retrieve an office by providing the office id.
With this, you can set a custom id (your internal department id) and then retrieve
the record without knowing the ClearCompany department Id.
Location: https://api.clearcompany.com/v1/departments/custom/{CustomDepartmentIdValue}
Example Location: https://api.clearcompany.com/v1/departments/custom/Dept-IT-945
Request Method: GET
{
"DepartmentGuid": "bf0e5497-1f9b-4080-a061-13e71921467c",
"IndustryGuid": "00000000-0000-0000-0000-000000000000",
"CreatedDate": "2013-01-30T21:24:33Z",
"Active": true,
"Phone": "617-555-2322",
"Fax": "617-555-9282"
}
Create a New Department

Purpose: To create a new department in the ClearCompany System.
Location: https://api.clearcompany.com/v1/departments
Required Fields: Name (string)
{
"CustomDepartmentId": "Dept-Legal-201",
"IndustryGuid": "00000000-0000-0000-0000-000000000000",
"Name": "Legal"
}

Location: https://api.clearcompany.com/v1/departments/8cfa4d36-dba3-4c77-837a-e31effa9751f

{
"DepartmentGuid": "8cfa4d36-dba3-4c77-837a-e31effa9751f",
"IndustryGuid": "00000000-0000-0000-0000-000000000000",
"Name": "Legal",
"CreatedDate": "2013-01-30T21:24:33Z",
"Active": true,
}

Update a Department by Office Id
Purpose: To update a department by providing the department Id.
Location: https://api.clearcompany.com/v1/departments/{DepartmentIdValue}
Example Location: https://api.clearcompany.com/v1/departments/8cfa4d36-dba3-4c77-837a-e31effa9751f
{
"CustomDepartmentId": "Dept-Legalese-501",
"IndustryGuid": "00000000-0000-0000-0000-000000000000",
"Name": "Legal Services"
}

{
"DepartmentGuid": "8cfa4d36-dba3-4c77-837a-e31effa9751f ",
"IndustryGuid": "00000000-0000-0000-0000-000000000000",
"Name": "Legal Services",
"CreatedDate": "2013-01-30T21:24:33Z",
"Active": true
}
Update a Department by Custom Department Id

Purpose: To update a department by providing the assigned custom office Id.
With this, you can set a custom id (your internal department id) and then update
the department record without knowing the ClearCompany Department Id.
Location: https://api.clearcompany.com/v1/departments/custom/{CustomDepartmentIdValue}
Example Location: https://api.clearcompany.com/v1/departments/custom/Dept-Legal-501
{
"IndustryGuid": "00000000-0000-0000-0000-000000000000",
"Name": "Legal Services Etc"
}

{
"DepartmentGuid": "8cfa4d36-dba3-4c77-837a-e31effa9751f ",
"IndustryGuid": "00000000-0000-0000-0000-000000000000",
"Name": "Legal Services Etc",
"Active": true
}

7. User Requests
Retrieve a User by User Id
Purpose: To retrieve a user by providing the user id.
Location: https://api.clearcompany.com/v1/users/{UserIdValue}
Example Location: https://api.clearcompany.com/v1/users/996f6b38-9875-44a3-a431-f8e621c7ab16
Optional URL Parameter: includeProfileImage=true – Including this parameter will include the users
profile image as a Base64 encoded string in the “ProfileImage” JSON property
Request Method: GET
Note: To retrieve the legal first, middle and last names, you must be using API credentials that
have been granted the hr.admin permission
{
"LegalFirstName": "Robert",
"LegalMiddleName": "Johnson",
"LegalLastName": "Smith",
"MiddleName": "Johnson",
"UserId": "996f6b38-9875-44a3-a431-f8e621c7ab16",
"DisplayName": "Robert Smith",
"Title": "Senior Programmer",
"FirstName": "Robert",
"LastName": "Smith",
"Email": "Robert.Smith@somecompany.com",
"PersonalEmail": "Robert.Smith@example.org",
"MobilePhone": "610-555-1241",
"WorkPhone": "610-555-1231",
"SupervisorUserId": "f2e08f03-81d3-4afe-ad78-76a99be82f2d",
"DepartmentId": "92a1c9b2-8531-43ae-937f-b116708ad548",
"OfficeId": "9d9d96ea-20e5-45c5-a37c-efc75ce7bd31",
"LatestHireDate": "2018-11-12T00:00:00",
"RoleId": "23fc60c7-23d0-0c1a-60d6-d83d40eb759b",
"RoleName": "Senior Developer",
"RoleStartDate": "2018-11-12T00:00:00",
"ProfileImage": "Optional Base64 encoded user profile image",
"EmployeeId": "rs-453"
}

Update a User by User Id
Purpose: To update a user by providing the user id.
Note: If your users are managed by a ClearCompany integrated external system of record (such as ADP),
fields managed by that SOR will not be updated with this request.
Setting PersonalEmail requires ClearCompany to enable it in your account.
Fields listed in the sample request below can be modified unless otherwise noted.
Location: https://api.clearcompany.com/v1/users/{UserId}
Example Location: https://api.clearcompany.com/v1/users/996f6b38-9875-44a3-a431-f8e621c7ab16
{
"Title": "Senior Programmer Extraordinaire",
"FirstName": "Bob",
"LastName": "Smith Jr",
"MobilePhone": "610-555-7897",
"WorkPhone": "610-555-0987",
}

{
"Title": "Senior Programmer",
"MobilePhone": "610-555-1241",
"WorkPhone": "610-555-1231",
"RoleStartDate": "2018-11-12T00:00:00",

Terminate a User Immediately by User Id
Purpose: To terminate a user by providing the user id.
Authentication: Required (User Admin, HR Admin)
Location: https://api.clearcompany.com/v1/public/users/{UserId}/terminations
Example Location: https://api.clearcompany.com/v1/public/users/996f6b38-9875-44a3-a431-
f8e621c7ab16/terminations
Required Fields: All fields are required.
{
"TerminationScheduleType": "immediate",
"UtcTerminationDate": null,
"TerminationType": "voluntary",
"TerminationReason": "Applied for a different position at another company."
}

{
"TerminationScheduleType": "immediate",
"TerminationDateTime": null,
"TerminationType": "voluntary",
}
Terminate a User on a Specific Date by User Id

Purpose: To terminate a user by providing the user id and a future date.
Required Fields: All fields are required.
{
"TerminationScheduleType": "specific-time",
"UtcTerminationDate": "2020-01-27T22:07:43Z",
"TerminationType": "involuntary",
}

{
"TerminationDateTime": "2020-01-27T22:07:43Z",
}

Get Status for a Pending Termination for a User by User Id
Purpose: Get status information regarding a pending termination for a user set in a future date.
Request Method: GET

{
"TerminationDateTime": "2020-01-27T22:07:43Z",
}
Cancel a Pending Termination for a User by User Id

Purpose: To cancel a pending termination for a user that is set in a future date.
Request Method: DELETE
Restore a Terminated User by User Id

Purpose: Restore a user back to active status that has been previously terminated.
Location: https://api.clearcompany.com/v1/users/{UserId}/restore
Example Location: https://api.clearcompany.com/v1/users/996f6b38-9875-44a3-a431-f8e621c7ab16/restore
Request Method: PUT

8. User Account Requests
Retrieve a User Account by User Id
Purpose: To retrieve a user account by providing the user id. User Account data is slightly
different from standard User Data in that it contains slightly more administrative
and sensitive information such as the user’s user name, employee id and permissions.
Note: See Appendix A.1 for the meaning of various permissions.
Location: https://api.clearcompany.com/v1/users/{UserAccountIdValue}/account
Example Location: https://api.clearcompany.com/v1/users/996f6b38-9875-44a3-a431-
f8e621c7ab16/account
Optional URL Parameter: includeEntityDetails=true – If present the DepartmentName, OfficeName
SupervisorFirstName, SupervisorLastName properties will be populated.
Request Method: GET

{
"Username": "Robert.Smith.jr@somecompany.com",
"EmployeeId": "empl-38374874",
"CustomDepartmentId": "IT-123",
"CustomOfficeId": "Boston-234",
"Active": true,
"Permissions": [
"org.employee",
"hr.manager"
],
"DisplayName": "Bob Smith",
"FirstName": "Bob",
"Email": "Robert.Smith.jr@somecompany.com",
"PersonalEmail": "Robert.Smith.jr@example.org",
"MobilePhone": "610-555-7897",
"WorkPhone": "610-555-0987",
"RoleStartDate": "2018-11-12T00:00:00",
"LatestHireDate": "2018-11-12"

Create a User Account
Purpose: To create a new user account in the ClearCompany system.
Note: If your users are managed by a ClearCompany integrated external system of record (such as ADP),
fields managed by that SOR will not be updated with this request.
Setting PersonalEmail requires ClearCompany to enable it in your account.
Fields listed in the sample request below can be modified unless otherwise noted.

Location: https://api.clearcompany.com/v1/users/account
Required Fields: Username (string) – Minimum length 4 characters
FirstName(string) – Minimum length 1 character
LastName(string) – Minimum length 1 character
Email (string) – Must be a valid email address
DepartmentId or CustomDepartmentId (string) – One of the two must be provided
Note: Either DepartmentId or CustomDepartmentId must be provided. Likewise, you can
either (optionally) provide an OfficeId or a CustomOfficeId.
Passwords are salted, hashed and stored securely. If no password is provided, a random
password will be assigned and the user can reset their password when they go to login.
{
"Password": "SomeSecurePassword123",
"OfficeId": "9d9d96ea-20e5-45c5-a37c-efc75ce7bd31"
"Permissions": [
"org.employee",
"hr.manager"
],
"FirstName": "Bob",
"MobilePhone": "610-555-7897",
"WorkPhone": "610-555-0987",
"LatestHireDate": "2018-11-12",
"RoleId": "23fc60c7-23d0-0c1a-60d6-d83d40eb759b"
}

Location: https://api.clearcompany.com/v1/user/996f6b38-9875-44a3-a431-f8e621c7ab16/account

{
"Permissions": [
"org.employee",
"hr.manager"
],

"DisplayName": "Bob Smith",
"FirstName": "Bob",
"MobilePhone": "610-555-7897",
"WorkPhone": "610-555-0987",
"RoleStartDate": "2018-11-12T00:00:00"
}
Update a User Account by User Id

Purpose: To update a new user account in the ClearCompany system.
Location: https://api.clearcompany.com/v1/users/{UserIdValue}/account
f8e621c7ab16/account
Note: Either DepartmentId or CustomDepartmentId can be provided. Likewise, you can
either provide a OfficeId or a CustomOfficeId.
{
"Username": "RobertGriffinjr3",
"Password": "SomeNewPassword123",
"Permissions": [
"org.employee",
"hr.manager"
],
"LastName": "Griffin Jr3",
"Email": "Robert.Griffin.jr3@somecompany.com",
"MobilePhone": "610-555-7897",
"WorkPhone": "610-555-0987",
}

{

"Permissions": [
"org.employee",
"hr.manager"
],
"MobilePhone": "610-555-7897",
"WorkPhone": "610-555-0987",
"RoleStartDate": "2018-11-12T00:00:00"
}

Update a User Account by Custom Employee Id
Purpose: To update a user account by providing the assigned employee id.
With this, you can set an employee id (your internal employee or user id) and then update
the user account record without knowing the ClearCompany User Id.
Location: https://api.clearcompany.com/v1/users/custom/{EmployeeIdValue}/account
Example Location: https://api.clearcompany.com/v1/users/custom/empl-38374874/account
Note: Either DepartmentId or CustomDepartmentId can be provided. Likewise, you can
either provide a OfficeId or a CustomOfficeId.
{
"Password": "SomeNewPassword123",
"Permissions": [
"org.employee",
"hr.manager"
],
"MobilePhone": "610-555-7897",
"WorkPhone": "610-555-0987",
"RoleId": "23fc60c7-23d0-0c1a-60d6-d83d40eb759b"
}

{
"Permissions": [
"org.employee",
"hr.manager"
],
"MobilePhone": "610-555-7897",
"WorkPhone": "610-555-0987",

"RoleStartDate": "2018-11-12T00:00:00",
}

Retrieve User Account Permissions by User Id
Purpose: To retrieve user account permissions by providing the user id.
Location: https://api.clearcompany.com/v1/users/{UserAccountIdValue}/account/permissions
f8e621c7ab16/account/permissions
Request Method: GET
[
"org.employee",
"hr.manager"
]
Retrieve User Account Permissions by Employee Id

Purpose: To retrieve user account permissions by providing the assigned employee id.
Location: https://api.clearcompany.com/v1/users/custom/{EmployeeIdValue}/account/permissions
Example Location: https://api.clearcompany.com/v1/users/custom/empl-38374874/account/permissions
Request Method: GET
[
"org.employee",
"hr.manager"
]
Retrieve All Active or Inactive User Accounts

Purpose: To retrieve all active or inactive user accounts in the system.
Since this endpoint supports OData querying, it offers an alternate way
to do user lookups in this system.
Location: https://api.clearcompany.com/v1/users/account/active/all
https://api.clearcompany.com/v1/users/account/inactive/all
Request Method: GET
[
{
"UserId": "1465f3ec-e1a7-408b-8864-2885d45b06af",
"Permissions": [
"org.employee",
"hr.manager"
],

"MobilePhone": "610-555-7897",
"WorkPhone": "610-555-0987",
"RoleName": "Senior Developer"
},
…
{
"Username": "johnsmith45@someco.com",
"UserId": "269c86eb-52b7-47bb-8e55-75e6976e3afb",
"CustomDepartmentId": "Accounting-123",
"CustomOfficeId": "Chicago-345",
"DepartmentId": "b8c1b72c-742b-475c-a2b2-2e6f871ccc63",
"OfficeId": "1465f3ec-e1a7-408b-8864-2885d45b06af"
"Permissions": [
"org.employee",
"user.admin"
],
"Title": "Accountant",
"Email": " johnsmith45@someco.com ",
"MobilePhone": "610-555-3223",
"WorkPhone": "610-555-2322",
"SupervisorUserId": "5a3ff603-05f3-4d17-aeba-a67dfb6ee646",
"RoleId": "aae9c975-d149-a4b3-122b-e701955f8fae",
"RoleName": "Accountant"
}
]
Retrieve All Active or Inactive User Accounts By Role

Purpose: To retrieve all active or inactive user accounts in the system by role.
Location: https://api.clearcompany.com/v1/users/account/active/role/{providedRole}
https://api.clearcompany.com/v1/users/account/inactive/role/{providedRole}
Example Location: https://api.clearcompany.com/v1/users/account/active/role/user.admin
Request Method: GET
Note: See 10.1 for valid role values.
[
{
"Username": "teddavids232",
"UserId": " ea1f5337-d610-464c-be61-ae3da1861d2b",
"Permissions": [
"org.employee",
"user.admin"
],
"FirstName": "Ted",
"LastName": "Davids",
"Email": "teddavids@somecompany.com",
"MobilePhone": "610-555-1211",
"WorkPhone": "610-555-4223",

"RoleName": "Senior Developer"
},
…
{
"Username": "johnsmith45@someco.com",
"UserId": "269c86eb-52b7-47bb-8e55-75e6976e3afb",
"CustomDepartmentId": "Accounting-123",
"CustomOfficeId": "Chicago-345",
"DepartmentId": "b8c1b72c-742b-475c-a2b2-2e6f871ccc63",
"OfficeId": "1465f3ec-e1a7-408b-8864-2885d45b06af"
"Permissions": [
"org.employee",
"user.admin"
],
"Title": "Senior Accountant",
"Email": " johnsmith45@someco.com ",
"MobilePhone": "610-555-3223",
"WorkPhone": "610-555-2322",
"SupervisorUserId": "5a3ff603-05f3-4d17-aeba-a67dfb6ee646",
"RoleId": "aae9c975-d149-a4b3-122b-e701955f8fae",
"RoleName": "Accountant"
}
]

9. Requisition Requests
9.1.1 Retrieve a Requisition by Requisition Id
Purpose: To retrieve a requisition by providing the requisition id.
Location: https://api.clearcompany.com/v1/reqs/{ReqIdValue}
Example Location: https://api.clearcompany.com/v1/reqs/bf0e5497-1f9b-4080-a061-13e71921467c
Request Method: GET
{
"ReqGuid": "9d426147-3aae-4d60-bd3f-d9ffccde59bd",
"CustomReqId": "creq123",
"ReqDate": "2012-12-10T04:00:00Z",
"EmailAlias": "41074@somecompany.hrmdirect.com",
"JobTitle": "Director of Operations",
"JobDescription": "Essential functions of the position: Designs and implements programs,
policies, and practices to ensure that all operating departments are in compliance with federal,
state, and local regulatory requirements. Tracks laws and regulations that might affect the
organization's policies. Prepares compliance reports to present to management. Familiar with a
variety of the field's concepts, practices, and procedures. Relies on experience and judgment to
plan and accomplish goals. The incumbent is also responsible for compliance audits and, in
conjunction with the Legal department, assists in all state examinations. ESSENTIAL SUMMARY of
BENEFITS: We take great pride in providing our employees with a superior benefits package,
including 100% employer paid medical and dental plans and a comprehensive retirement program,
including 401(k).",
"Status": "O",
"ValidateResumes": false,
"AutoReply": true,
"InstantUploadAutoReply": false,
"IndustryGuid": "5878f1a5-d184-4914-beb9-423985cdc65c",
"JobFunctionGuid": "7d353845-1b3e-48b3-90b0-74935b48e7a2",
"SalaryLow": "33",
"SalaryHigh": "44",
"SalaryType": "PerHour",
"ClosedDate": "0001-01-01T05:00:00Z",
"ClosedReason": "",
"CreatedDate": "2012-12-12T05:00:00Z",
"DepartmentGuid": "4767fef9-33b3-4b3a-ae14-e966ce6670b2",
"DepartmentCustomId": "dept-it-342",
"DepartmentName": "IT Department",
"OfficeGuid": "0007ae7a-3663-428c-a178-fdf9ceefdc07",
"OfficeName": "Springfield Research Office",
"OfficeCustomId": "off-bos-441",
"OfficeLocation": {
"Id": "d09df814-1279-1c77-a38d-959719e028c3",
"AddressLine1": "2 Center Ct Dr",
"AddressLine2": "Suite 233",
"City": "Springfield",
"State": "MA",
"PostalCode": "02111",
"ProvinceName": "",
"AbbreviatedProvince": ""
},
"RecruiterGuid": "3c691ea6-0e8a-4c99-b900-7e815c936a75",
"RecruiterEmployeeId": "empl12244",
"HiringManagerGuid": "f99c075d-ced3-401c-8e0a-c6874ee3529f",
"HiringManagerEmployeeId": "emp43212",
"BudgetCode": "BudgetedContractor",
"EEOCode": "SkilledCraftWorkers",
"DaysOpen": 65,
"CycleTime": -1,
"HireTime": -1,
"DaysUntilPostedPublic": "7",
"DaysUntilPostedInternal": "0",
"ApplyProcessType": "Email",
"ApplyProcessGuid": "00000000-0000-0000-0000-00000000",
"AuthorizedUsers": [

{
"UserGuid": "d09df834-1779-4c77-b38c-479719e028c3",
"EmployeeId": "emp8322",
"AuthorizedByUserGuid": "3c691ea6-0e8a-4c99-b900-7e815c936a75",
"AuthorizationDate": "2013-01-15T17:13:01Z"
},
{
"UserGuid": "e08fae6a-5230-4393-92b3-bc1e8dd6eb47",
}
],
"CustomFieldAnswers": [
{
"CustomFieldGuid": "d1baaa9a-7ab0-48a3-b821-4be8af23cce7",
"FieldName": "Category",
"Answer": "Hourly",
"AnswerOptionGuid": [
"1fa5289d-739e-4999-a923-21a9cbbbe26e"
],
"Internal": true,
"Required": true,
"AnswerFieldType": "LegacySingleSelect"
},
{
"CustomFieldGuid": "b58b9aee-6087-487d-80c7-150a8f8843b9",
"FieldName": "Advertising Costs",
"Answer": "$1,500",
"AnswerOptionGuid": [ ],
"Internal": true,
"Required": false,
"AnswerFieldType": "LegacyTextBox"
},
{
"CustomFieldGuid": "771b41a5-daa1-44be-82cd-db906a0e449e",
"FieldName": "Preferred location",
"Answer": "Boston Copley",
"Internal": true,
"Required": false,
"AnswerFieldType": "LegacyTextArea"
},
{
"CustomFieldGuid": "6faee50a-047a-489d-ae7a-bfcfbc0621d1",
"FieldName": "Looking for full time?",
"Answer": "Yes",
"d15d88b9-d77a-4a90-8f3f-7c53d5dc0c3c"
], "Internal": true,
"Required": true,
},
{
"CustomFieldGuid": "be4ddbec-0d10-0000-0000-000000000000",
"FieldName": "Available for which shifts?",
"Answer": "First shift, Second Shift, Graveyard Shift",
"1c91c258-234b-0000-0000-000000000000",
"2962e5d9-234c-0000-0000-000000000000",
"71363cd9-234d-0000-0000-000000000000"
],
"Internal": true,
"Required": true,
"AnswerFieldType": "LegacyMultiSelect"
}
]
}

9.1.2 Retrieve a Requisition by Custom Requisition Id
Purpose: To retrieve an requisition by providing the assigned custom requisition id.
Location: https://api.clearcompany.com/v1/reqs/custom/{CustomReqIdValue}
Example Location: https://api.clearcompany.com/v1/reqs/custom/creq123
Request Method: GET
{
"ReqDate": "2012-12-10T04:00:00Z",
"JobDescription": "Essential functions of the position: Designs and implements programs,
policies, and practices to ensure that all operating departments are in compliance with federal,
state, and local regulatory requirements. Tracks laws and regulations that might affect the
organization's policies. Prepares compliance reports to present to management. Familiar with a
variety of the field's concepts, practices, and procedures. Relies on experience and judgment to
plan and accomplish goals. The incumbent is also responsible for compliance audits and, in
conjunction with the Legal department, assists in all state examinations. ESSENTIAL SUMMARY of
BENEFITS: We take great pride in providing our employees with a superior benefits package,
including 100% employer paid medical and dental plans and a comprehensive retirement program,
including 401(k).",
"Status": "O",
"AutoReply": true,
"SalaryLow": "33",
"SalaryHigh": "44",
"ClosedDate": "0001-01-01T05:00:00Z",
"ClosedReason": "",
"CreatedDate": "2012-12-12T05:00:00Z",
"OfficeLocation": {
"Id": "d09df814-1279-1c77-a38d-959719e028c3",
"State": "MA",
"ProvinceName": "",
},
"DaysOpen": 65,
"CycleTime": -1,
"HireTime": -1,
"ApplyProcessType": "Profile",
"ApplyProcessGuid": "e5c1572c-3f8b-4df1-ae7c-2952397e1a56",
{

},
{
}
],
{
"CustomFieldGuid": "d1baaa9a-7ab0-48a3-b821-4be8af23cce7",
"FieldName": "Category",
"Answer": "Hourly",
"1fa5289d-739e-4999-a923-21a9cbbbe26e"
],
"Internal": true,
"Required": true,
},
{
"CustomFieldGuid": "b58b9aee-6087-487d-80c7-150a8f8843b9",
"Answer": "$1,500",
"Internal": true,
"Required": false,
},
{
"CustomFieldGuid": "771b41a5-daa1-44be-82cd-db906a0e449e",
"Answer": "Boston Copley",
"Internal": true,
"Required": false,
},
{
"CustomFieldGuid": "6faee50a-047a-489d-ae7a-bfcfbc0621d1",
"FieldName": "Looking for full time?",
"Answer": "Yes",
"d15d88b9-d77a-4a90-8f3f-7c53d5dc0c3c"
],
"Internal": true,
"Required": true,
},
{
"FieldName": "Available for which shifts?",
"Answer": "First shift, Second Shift, Graveyard Shift",
"7786f407-cd7a-472b-9829-083ca44d3e5d",
"147e0311-b39b-42c6-aa84-e49232d83e72",
"cbc74048-7b4f-4a32-8556-c8cc3d5081fc"
],
"Internal": true,
"Required": true,
}
]
}

Create a New Requisition
Purpose: To create a new requisition in the ClearCompany System.
Authentication: Required (User Admin, Recruiter)
Location: https://api.clearcompany.com/v1/reqs
Required Fields: JobTitle (string)
JobDescription (string)
DepartmentGuid (string) or DepartmentCustomId (string)
OfficeGuid (string) or OfficeCustomId (string)
HiringManagerGuid (string) or HiringManangerEmployeeId (string)
RecruiterGuid (string) or RecruiterEmployeeId (string)
Notes on created
requisitions: All new reqs are created in "On Hold" status. This means it requires that a user
log
into ResumeDirect and change the status to Open, before the req will show up on
career websites or go out to third party job boards.
Notes on Apply
Process Type: Valid values for ApplyProcessType are "Email" or "Profile". If no
ApplyProcessType is provided, the default apply process type will be email. If
you provide an apply process type of Profile and do not provide a
ProfileProcessId, then the organizations default apply process id will be used.
Notes on
Authorized Users: When providing Authorized Users, you can provide either the users UserGuid or the
custom EmployeeId that you have set for them. One of these two properties needs
to be present in order to add an authorized user. See the sample request content
below.
Notes on Custom
Fields: See Section 4.6 to retrieve a list of your custom fields.
All Custom Field Answers require that you provide a CustomFieldGuid.
There are four types of Custom Field Answers. For the LegacyTextBox and
LegacyTextArea you provide the answer by populating the Answer property (which
accepts plain text responses).
For LegacySingleSelect and LegacyMultiSelect, you populate the AnswerOptionGuids
list with the corresponding selection from the CustomField.Options[ ].OptionGuid
value. See Section 4.6 for the OptionGuid property in Options list.
See the sample request content below.
{
"CustomReqId": "act-108741",
"ReqDate": "2013-02-15",
"JobTitle": "Certified Accountant Needed ASAP",
"JobDescription": "We need a good accountant with lots of experience.",
"AutoReply": false,
"IndustryGuid": "5e10feb6-f104-4898-9fae-c75475cb585a",
"JobFunctionGuid": "3f4a1244-26e4-4cc6-934a-e259d4eb9e1f",
"SalaryLow": "35000",
"SalaryHigh": "50000",
"SalaryType": "PerYear",
"DepartmentGuid": "6d3b167e-7c17-40be-a7c1-701c4f5d4537",
"OfficeLocation": {
"Id": "d09df814-1279-1c77-a38d-959719e028c3",
"State": "MA",
"ProvinceName": "",
},
"RecruiterGuid": "46a1043a-63fa-4cb6-be7a-7a69400b6c97",
"HiringManagerGuid": "b88299a4-e010-469b-abcc-6c1f21a84158",
"BudgetCode": "UnbudgetedContractor",
"EEOCode": "FirstAndMidLevelManagers",

{
"UserGuid": "22996fdd-1f2f-46ca-8631-d64de6941b04",
},
{
}
],
{
"CustomFieldGuid": "c9f9f058-013a-0000-0000-000000000000",
"Answer": "$1,300"
},
{
"CustomFieldGuid": "954502de-01be-0000-0000-000000000000",
"AnswerOptionGuids": [
"653823cf-0ac2-0000-0000-000000000000"
]
},
{
"FieldName": "Choose budgetary type:",
"2962e5d9-234c-0000-0000-000000000000",
"1c91c258-234b-0000-0000-000000000000"
]
}
]
}

Location: https://api.clearcompany.com/v1/reqs/23de845f-5215-47ee-bb9c-5adb3e36572d

{
"ReqGuid": "3f7fc437-32b8-47f0-8e08-8dade5c6ce50",
"CustomReqId": " act-108741",
"ReqDate": "2013-02-14T05:00:00Z",
"EmailAlias": "105517@abc.hrmdirect.com",
"JobTitle": " Certified Accountant Needed ASAP ",
"JobDescription": " We need a good accountant with lots of experience ",
"Status": "H",
"AutoReply": false,
"IndustryGuid": "a209133c-014a-0000-0000-000000000000",
"JobFunctionGuid": "ca0d7858-013a-0000-0000-000000000000",
"ClosedDate": "0001-01-01T05:00:00Z",
"ClosedReason": "",
"CreatedDate": "2013-02-15T05:00:00Z",
"DepartmentGuid": "5165de93-018f-0000-0000-000000000000",
"DepartmentCustomId": "IT",
"OfficeLocation": {
"Id": "d09df814-1279-1c77-a38d-959719e028c3",
"State": "MA",

"ProvinceName": "",
},
"RecruiterGuid": "20679983-2a86-0000-0000-000000000000",
"RecruiterEmployeeId": "django.bliss",
"HiringManagerGuid": "203461bd-731a-0003-0000-000000000000",
"HiringManagerEmployeeId": "ben.counter",
"DaysOpen": 1,
"CycleTime": -1,
"HireTime": -1,
{
"AuthorizedByUserGuid": "2b3c23fc-ecd1-47db-b805-3d32cb880c16",
},
{
"UserGuid": "aef0f5d6-4f5a-0020-0000-000000000000",
"EmployeeId": "",
}
],
{
"Answer": "$1,300",
"AnswerOptionGuids": [ ],
"Internal": true,
"Required": false,
},
{
"CustomFieldGuid": "bca60ec4-0171-0000-0000-000000000000",
"Answer": "cfAnswer- - 2/15/2013@5:53 PM.997 R1438976",
"Internal": true,
"Required": false,
},
{
"FieldName": "Division",
"Answer": "Accounting Division",
"653823cf-0ac2-0000-0000-000000000000"
],
"Internal": true,
"Required": true,
},
{
"FieldName": "Checkboxes",
"Answer": "Unbudgeted Addition, Seasonal Help",
"2962e5d9-234c-0000-0000-000000000000",
"1c91c258-234b-0000-0000-000000000000"
],
"Internal": true,
"Required": true,

}
]
}

Update Requisition By Requisition Id
Purpose: To update an existing requisition in the ClearCompany System.
Location: https://api.clearcompany.com/v1/reqs/{ReqGuid}
Required Fields: JobTitle (string)

JobDescription (string)
Status(string)
DepartmentGuid (string) or DepartmentCustomId (string)
OfficeGuid (string) or OfficeCustomId (string)
HiringManagerGuid (string) or HiringManangerEmployeeId (string)
RecruiterGuid (string) or RecruiterEmployeeId (string)
Notes on updating
requisitions: Only requistions that are in "Open", "Hold", or "Closed" status can be updated
and they can only be updated to the "Open", "Hold", or "Closed" status.
Notes on Apply
Process Type: Valid values for ApplyProcessType are "Email" or "Profile". If no
ApplyProcessType is provided, the default apply process type will be email. If
you provide an apply process type of Profile and do not provide a
ProfileProcessId, then the organizations default apply process id will be used.
Notes on
Authorized Users: When providing Authorized Users, you can provide either the users UserGuid or the
custom EmployeeId that you have set for them. One of these two properties needs
to be present in order to add an authorized user. See the sample request content
below.
Notes on Custom
Fields: See Section 4.6 to retrieve a list of your custom fields.
All Custom Field Answers require that you provide a CustomFieldGuid.
There are four types of Custom Field Answers. For the LegacyTextBox and
LegacyTextArea you provide the answer by populating the Answer property (which
accepts plain text responses).
For LegacySingleSelect and LegacyMultiSelect, you populate the AnswerOptionGuids
list with the corresponding selection from the CustomField.Options[ ].OptionGuid
value. See Section 4.6 for the OptionGuid property in Options list.
See the sample request content below.
{
"CustomReqId": "act-108741",
"ReqDate": "2013-02-15",
"Status": "C",
"JobTitle": "Certified Accountant Needed ASAP",
"JobDescription": "We need a good accountant with lots of experience.",
"AutoReply": false,
"IndustryGuid": "5e10feb6-f104-4898-9fae-c75475cb585a",
"JobFunctionGuid": "3f4a1244-26e4-4cc6-934a-e259d4eb9e1f",
"SalaryType": "PerYear",
"OfficeLocation": {
"Id": "d09df814-1279-1c77-a38d-959719e028c3",
"State": "MA",
"ProvinceName": "",
},
"DepartmentGuid": "6d3b167e-7c17-40be-a7c1-701c4f5d4537",

"RecruiterGuid": "46a1043a-63fa-4cb6-be7a-7a69400b6c97",
"HiringManagerGuid": "b88299a4-e010-469b-abcc-6c1f21a84158",
{
},
{
}
],
{
"Answer": "$1,300"
},
{
"653823cf-0ac2-0000-0000-000000000000"
]
},
{
"FieldName": "Choose budgetary type:",
"2962e5d9-234c-0000-0000-000000000000",
"1c91c258-234b-0000-0000-000000000000"
]
}
]
}
Successful Response Code: 200 Updated

{
"CustomReqId": " act-108741",
"ReqDate": "2013-02-14T05:00:00Z",
"EmailAlias": "105517@abc.hrmdirect.com",
"JobTitle": " Certified Accountant Needed ASAP ",
"JobDescription": " We need a good accountant with lots of experience ",
"Status": "C",
"AutoReply": false,
"IndustryGuid": "a209133c-014a-0000-0000-000000000000",
"JobFunctionGuid": "ca0d7858-013a-0000-0000-000000000000",
"ClosedDate": "0001-01-01T05:00:00Z",
"ClosedReason": "",
"CreatedDate": "2013-02-15T05:00:00Z",
"OfficeLocation": {
"Id": "d09df814-1279-1c77-a38d-959719e028c3",

"State": "MA",
"ProvinceName": "",
},
"DepartmentGuid": "5165de93-018f-0000-0000-000000000000",
"DepartmentCustomId": "IT",
"RecruiterGuid": "20679983-2a86-0000-0000-000000000000",
"RecruiterEmployeeId": "django.bliss",
"HiringManagerGuid": "203461bd-731a-0003-0000-000000000000",
"HiringManagerEmployeeId": "ben.counter",
"DaysOpen": 1,
"CycleTime": -1,
"HireTime": -1,
{
},
{
"UserGuid": "aef0f5d6-4f5a-0020-0000-000000000000",
"EmployeeId": "",
}
],
{
"Answer": "$1,300",
"Internal": true,
"Required": false,
},
{
"CustomFieldGuid": "bca60ec4-0171-0000-0000-000000000000",
"Answer": "cfAnswer- - 2/15/2013@5:53 PM.997 R1438976",
"Internal": true,
"Required": false,
},
{
"FieldName": "Division",
"Answer": "Accounting Division",
"653823cf-0ac2-0000-0000-000000000000"
],
"Internal": true,
"Required": true,
},
{
"FieldName": "Checkboxes",
"Answer": "Unbudgeted Addition, Seasonal Help",
"2962e5d9-234c-0000-0000-000000000000",

"1c91c258-234b-0000-0000-000000000000"
],
"Internal": true,
"Required": true,
}
]
}

Listing Requisitions
9.4.1 Get Requisitions By Status
Purpose: To retrieve a list of requisitions that are in the provided status.
Location: https://api.clearcompany.com/v1/reqs/status/{ReqStatus}
Example Location: https://api.clearcompany.com/v1/reqs/status/open
Request Method: GET
Valid {ReqStatus}Values: open, pending, rejected, hold, closed, deleted, all, template,
templatedeleted
Note: All is a special ReqStatus that will return all reqs regardless of status.
[
{
"ReqGuid": "bad436a6-2e1a-4320-81d4-9a0f5440453b",
"ReqDate": "2012-12-10T04:00:00Z",
"JobDescription": "Essential functions of the position….",
"Status": "O",
"AutoReply": true,
"SalaryLow": "33",
"SalaryHigh": "44",
"ClosedDate": "0001-01-01T05:00:00Z",
"ClosedReason": "",
"CreatedDate": "2012-12-12T05:00:00Z",
"OfficeLocation": {
"Id": "d09df814-1279-1c77-a38d-959719e028c3",
"State": "MA",
"ProvinceName": "",
},
"DepartmentId": "IT Department",
"DaysOpen": 65,
"CycleTime": -1,
"HireTime": -1,
{

},
{
}
],
"CustomFieldAnswers": []
},
{
"ReqGuid": "3c84cbf4-6574-499c-b4c7-11515709801d",
"ReqDate": "2012-11-08T04:00:00Z",
"JobTitle": "Director of IT",
"JobDescription": "Essential functions of the position….",
"Status": "O",
"AutoReply": true,
"ClosedDate": "0001-01-01T05:00:00Z",
"ClosedReason": "",
"CreatedDate": "2012-12-12T05:00:00Z",
"DaysOpen": 65,
"CycleTime": -1,
"HireTime": -1,
"AuthorizedUsers": [],
"CustomFieldAnswers": []
}
]

10. Applicant and Candidate Requests – A Primer
Before diving into the Applicant and Candidate part of the API, the relationship between the two should
be explained. An Applicant can be thought of as a single individual person. They can submit their
candidacy to multiple requisitions, thus becoming a candidate for those positions. Put another way, any
given applicant can have multiple candidate records, each one associated with the requisition they are
applying for.
Applicant - John Smith
 John Smith Candidate Record #1 for Requisition Bank Manager

 John Smith Candidate Record #2 for Requisition Branch Manager
 John Smith Candidate Record #3 for Requisition Bank Teller
11. Applicant Requests

Retrieve an Applicant Record
Purpose: To retrieve an applicant by providing the applicant id.
Authentication: Required (user.admin, hr.manager, hiring.manager)
Location: https://api.clearcompany.com/v1/applicants/{ApplicantIdValue}
Example Location: https://api.clearcompany.com/v1/applicants/5b8518a9-9145-44c8-8336-a1f31e7a2888
Request Method: GET
Note: The values supplied in the Applicant Candidacy list are all of the candidate records for a
given applicant.
{
"ApplicationId": "5b8518a9-9145-44c8-8336-a1f31e7a2888",
"OriginalReqId": "997f048b-e72d-42fa-b02b-293ce75c0d1e",
"CreatedDate": "2014-05-08T20:52:15Z",
"Candidacy": [
"aa81665f-530f-4bc6-90b7-8f33b2872af1",
"b45e678c-ae90-4374-925e-e2f3cb2b8c2d",
"10d5e592-7db4-4981-ac41-e84320b3c841"
]
}
Retrieve an Applicant’s Onboarding Records

Purpose: To retrieve an applicant’s onboarding records by applicant id.
Location: https://api.clearcompany.com/v1/applicants/{ApplicantIdValue}/onboarding
Example Location: https://api.clearcompany.com/v1/applicants/5b8518a9-9145-44c8-8336-
a1f31e7a2888/onboarding
Request Method: GET
Note: Potential values for Stage, chronologically as they happen: New, Assigned, Started,
Completed.
[
{

"EmployeeLifecycleId": "84b7b7c1-a6af-491b-bcf6-80d66349cf80",
"ReqId": "82ca2205-0dff-4abb-9d54-4d88b5184d6e",
"Stage": "Assigned",
"EmployeeCandidateId": "2dbf5b2e-63d9-4b63-924b-d182a8dbeefc",
"EmployeeUserId": "26f0f4ef-1507-4e4e-a807-c6199e644efe",
"StartDate": "2014-05-31T04:00:00Z",
"EmployeePacketDueDate": "2014-05-21T04:00:00Z",
"ApproverPacketDueDate": "2014-05-25T04:00:00Z",
"JobTitle": "Senior Account Executive 3",
"Ssn": "",
"DepartmentId": "0dcedd2b-1667-4410-8397-009489f4fd4a",
"OfficeId": "9fbbf0b9-2569-47df-99ce-b10abff3e68c",
"ManagerUserId": "d519fb64-e9e6-4362-b76f-cf7c43c135c7",
"CoordinatorUserId": "4418e056-2e19-4347-a69c-3ab575d25f9c",
"CreatedDate": "2014-04-30T19:28:50Z",
"UpdatedDate": "2014-04-30T20:42:24Z"
},
{
"EmployeeLifecycleId": "c01c5302-2d65-43b6-a1f8-09ea8ce7dff2",
"ReqId": "82ca2205-0dff-4abb-9d54-4d88b5184d6e",
"Stage": "Started",
"EmployeeCandidateId": "2dbf5b2e-63d9-4b63-924b-d182a8dbeefc",
"EmployeeUserId": "26f0f4ef-1507-4e4e-a807-c6199e644efe ",
"StartDate": "2014-05-31T04:00:00Z",
"JobTitle": "Senior Account Executive 3",
"Ssn": "",
"DepartmentId": "0dcedd2b-1667-4410-8397-009489f4fd4a",
"OfficeId": "9fbbf0b9-2569-47df-99ce-b10abff3e68c",
"ManagerUserId": "d519fb64-e9e6-4362-b76f-cf7c43c135c7",
"CoordinatorUserId": "4418e056-2e19-4347-a69c-3ab575d25f9c",
"CreatedDate": "2014-04-30T19:28:50Z",
"UpdatedDate": "2014-04-30T20:42:24Z"
},
{
"EmployeeLifecycleId": "e4416aa5-fd7b-4617-80a7-f44ce9fe9d35",
"ReqId": "702ed70c-17f4-4116-ac23-6c75d03bc387",
"Stage": "Assigned",
"EmployeeCandidateId": "a12934fe-0305-48af-b61d-720dc5e54fb1",
"EmployeeUserId": "f58479d2-2f84-4231-a871-d61e42f6679b",
"StartDate": "2013-07-01T04:00:00Z",
"JobTitle": "Account Executive",
"Ssn": "",
"DepartmentId": "fec2a8ca-a6cb-4037-88a1-1952acb412aa",
"OfficeId": "86e8e5e7-d35e-4144-a260-f7f603e9ba75",
"ManagerUserId": "15f053b3-a9e9-4924-be82-f6882f8190af",
"CoordinatorUserId": "b9ec140a-8b79-436b-b1e0-256dae5f3cc1",
"CreatedDate": "2013-06-12T17:14:14Z",
"UpdatedDate": "2013-06-20T20:52:15Z"
}
]

12. Candidate Requests
Retrieve a Candidate by Candidate Id
Purpose: To retrieve a candidate by providing the candidate id.
Location: https://api.clearcompany.com/v1/candidates/{CandidateIdValue}
Example Location: https://api.clearcompany.com/v1/candidates/e677b86a-8a1e-41c5-94e4-171b600aa483
Request Method: GET
Note: The values supplied in the Applicant Candidacy list are all of the candidate records for a
given applicant.
{
"Applicant": {
"ApplicationId": "fb601019-9b79-4d94-a2a2-ef453fdb35d1",
"OriginalReqId": "21595c0f-f25a-4ed5-addb-dd38464f7ebc",
"CreatedDate": "2013-02-21T20:44:34Z",
"Candidacy": [
"ad36b646-3869-4356-960b-8e4a6b8d1ac9",
"717f6e97-2cd1-4d7d-97b5-25907ebb3af2",
"1d23c814-241c-48c8-af61-80c7c93b3da6"
]
},
"ContactInfo": {
"Id": "e7d5d9c7-cb79-41c3-b353-b0926420a450",
"FirstName": "David",
"LastName": "Simon",
"Email": "david.simon@someemail.com",
"PrimaryPhoneNumber": "",
"PrimaryPhoneNumberType": "Other",
"SecondaryPhoneNumber": "",
"SecondaryPhoneNumberType": "Other",
"ContactInfo": "",
"Address": {
"Id": "926c3e27-44ed-4ace-b3a2-9df6b41a8457",
"AddressLine1": "1 City Center",
"AddressLine2": "Apt 2",
"City": "Boston ",
"State": "MA",
"ProvinceName": "",
},
"CreatedDate": "2013-02-21T15:44:34"
}
"Candidate": {
"Id": "ad36b646-3869-4356-960b-8e4a6b8d1ac9",
"ReqId": "21595c0f-f25a-4ed5-addb-dd38464f7ebc",
"ApplicationId": "fb601019-9b79-4d94-a2a2-ef453fdb35d1",
"DateApplied": "2013-02-21T20:51:24Z",
"ReadByUserId": "fb7543eb-9e31-475a-95d0-b50e15f8776a",
"DateRead": "2013-02-26T15:09:43",
"UpdatedDate": "2013-03-26T04:00:00Z",
"CurrentWorkflow": {
"Id": "52dbab53-c612-4106-ad83-580f861dc2d4",
"Order": 2,
"Name": "Interview Scheduled",
"Description": ""
},
"UserGrade": null,

"SystemGrade": "X",
"Deleted": false,
"History": [
{
"Id": "41ce765e-4ce0-4a92-9cd5-4bb23a305e76",
"WorkflowId": "00000000-0000-0000-0000-000000000000",
"WorkflowName": "",
"CandidateId": "ad36b646-3869-4356-960b-8e4a6b8d1ac9",
"Notes": "Online Application Completed, email sent to david.simon@someemail.com ",
"RecordedDate": "2013-02-21T20:51:47Z",
"RecordedByUserId": "7851ca0b-2144-4878-a60a-e07130137be4"
},
{
"Id": "737ded08-4aa7-4f85-acea-f6329823d559 ",
"WorkflowId": "00000000-0000-0000-0000-000000000000",
"WorkflowName": "",
"Notes": "Forwarded Email",
"RecordedDate": "2013-04-01T20:14:39Z",
"RecordedByUserId": "a29a7c50-6146-4a86-a5b2-11ae6a07a959"
},
{
"Id": "912d6dce-b066-4c32-8b54-c4c8c54a60dc ",
"WorkflowId": "59e38b31-6b1f-4142-b6b8-5c77b0ea0b8f ",
"WorkflowName": "Phone Screen Scheduled",
"Notes": "",
"RecordedDate": "2013-03-26T21:13:22Z",
"RecordedByUserId": "a29a7c50-6146-4a86-a5b2-11ae6a07a959"
}
]
}
}
Retrieve Candidate Demographics by Candidate Id

Purpose: To retrieve candidate demographics by providing the candidate id.
Location: https://api.clearcompany.com/v1/candidates/{CandidateIdValue}
Example Location: https://api.clearcompany.com/v1/candidates/e677b86a-8a1e-41c5-94e4-
171b600aa483/demographics
Request Method: GET
Note: For a list of the following mappings, please see Section 4 Collections:
Gender, Ethnicity, Race, DisabilityPreOffer, DisabilityPostOffer, LegacyVeteranStatus,
VeteranStatusPreOffer, VeteranStatusPostOffer
Race and VeteranStatusPostOffer both allow a combination of answers.
{
"Ssn": "123-45-6789",
"DateOfBirth": "1983-04-24",
"Gender": "not.specified",
"Ethnicity": 3,
"Race": [
4,
6
],
"LegacyVeteranStatus": "P",
"DisabiltyStatusPreOffer": 1,
"DisabiltyStatusPostOffer": 3,
"VeteranStatusPreOffer": 2,
"VeteranStatusPostOffer": [
4,
5
]
}

Retrieve Candidates by Requisition Id
Purpose: To retrieve all candidates that have applied to a given requisition.
Location: https://api.clearcompany.com/v1/reqs/{RequisitionIdValue}/candidates
Example Location: https://api.clearcompany.com/v1/reqs/ 18745e30-f94c-479b-b732-
93de6aceff7b/candidates
Request Method: GET
[
{
"CandidateId": "1f4a41bd-ab65-48b8-91d2-764b10e72fcd",
"FirstName": "Georgie",
"LastName": "Porgie",
"CurrentWorkflowId": "2c0ddd21-0938-4b42-8cbc-0f8705e15bca",
"CurrentWorkflowName": "Interview Request Sent",
"DateApplied": "2012-10-05T12:05:05Z"
},
{
"CandidateId": "aa05ab0b-7f9d-4c6b-b00c-5d8c1450b497",
"FirstName": "Alan",
"LastName": "Stevenson",
"CurrentWorkflowId": "a9264859-828a-409b-9a18-514b00a28cce",
"CurrentWorkflowName": "Interview Scheduled",
"DateApplied": "2012-10-05T14:31:37Z"
},
{
"CandidateId": "2548046b-0b66-4507-891a-971394684a2c",
"FirstName": "Rachel",
"CurrentWorkflowId": "5eca33ed-ce4f-4dcf-b778-28730d3c8b66",
"CurrentWorkflowName": "Offer Extended",
"DateApplied": "2012-10-12T16:34:57Z"
}
]

Retrieve Candidates by Requisition Id and Current Workflow
Purpose: To retrieve all candidates that are currently in a specific workflow that have applied to
a given requisition.
Location:
https://api.clearcompany.com/v1/reqs/{RequisitionIdValue}/candidates/workflow/current/{WorkflowId}
93de6aceff7b/candidates/workflow/current/ 03a49090-224e-4a0f-8972-1eb2ef905c76
Request Method: GET
[
{
"CandidateId": "8bd96603-007b-47b0-9350-a5814c5f9ee5",
"FirstName": "Tom",
"LastName": "Brady",
"CurrentWorkflowId": "03a49090-224e-4a0f-8972-1eb2ef905c76",
"CurrentWorkflowName": "Rejected - Overqualified",
"DateApplied": "2014-03-05T12:05:05Z"
},
{
"CandidateId": "aa05ab0b-7f9d-4c6b-b00c-5d8c1450b497",
"FirstName": "Drew",
"LastName": "Brees",
"CurrentWorkflowId": "03a49090-224e-4a0f-8972-1eb2ef905c76",
"CurrentWorkflowName": "Rejected - Overqualified ",
"DateApplied": "2014-01-02T14:31:37Z"
}
]
Retrieve Candidates by Requisition Id and Historical Workflow

Purpose: To retrieve all candidates that have ever been in in a specific workflow that have applied
to a given requisition.
Location:
https://api.clearcompany.com/v1/reqs/{RequisitionIdValue}/candidates/workflow/history/{WorkflowId}
93de6aceff7b/candidates/workflow/history/ 03a49090-224e-4a0f-8972-1eb2ef905c76
Request Method: GET
[
{
"CandidateId": "45c981a8-f440-4a0a-b26d-c54f773c5415",
"FirstName": "Jeff",
"LastName": "Bridges",
"CurrentWorkflowId": "fa49229c-9094-4438-accc-16c5d0af6513",
"CurrentWorkflowName": "Interview Request Sent",
"DateApplied": "2013-03-05T12:05:05Z"
},
{
"CandidateId": "188b72d1-5bfd-4b66-8584-5756fd3301aa",
"FirstName": "Daniel",
"LastName": "Day-Lewis",
"CurrentWorkflowId": "d410b698-dd21-41bc-8a54-cabca32defcc",
"CurrentWorkflowName": "Hired",
"DateApplied": "2013-01-02T14:31:37Z"
}
]

13. Appendix A
Permissions/User Rights/Roles
Note: Certain user rights will incur additional billing costs. Speak with your customer service
representative if you have any questions about the costs associated with various permissions.
org.ceo Identifies a user as the CEO of an organization – No additional cost.

org.employee Identifies a user as an employee of the organization – No additional cost.
department.head Identifies a user as a department head. Make sure you only identity
one per department – No additional cost.
hr.manager Identifies a user as a recruiter – Associated costs.
hiring.manager Identifies a user as a Hiring Manager – Typically no additional cost.
learning Gives access to the Learning Module – Associated costs.
offboarding Gives access to the Offboarding Module – Associated costs.
onboarding Gives access to the Onboarding Module – Associated costs.
performance.admin Gives a user Performance Admin rights – Typically no additional cost.
perf.management Gives access to the Performance Module – Associated costs.
offer.letter Gives access to the Offer Letter Module – Associated costs.
alignment Gives access to the Goals Module – Associated costs.
alignment.admin Gives a user Goals Module User Admin rights – Typically no additional cost.
user.admin Gives a user User Admin rights – Typically no additional cost.
hr.admin Gives a user HR Admin rights (HRIS) – Typically no additional cost.
vendor Identifies a user as a vendor (recruiting) - Typically no additional cost.
Country Names & Codes

Note: If we are missing a country that you require, please let us know.
AFGHANISTAN AF
ALAND ISLANDS AX
ALBANIA AL
ALGERIA DZ
AMERICAN SAMOA AS
ANDORRA AD
ANGOLA AO
ANGUILLA AI
ANTARCTICA AQ
ANTIGUA AND BARBUDA AG
ARGENTINA AR
ARMENIA AM
ARUBA AW
AUSTRALIA AU
AUSTRIA AT
AZERBAIJAN AZ
BAHAMAS BS
BAHRAIN BH
BANGLADESH BD
BARBADOS BB
BELARUS BY
BELGIUM BE
BELIZE BZ
BENIN BJ
BERMUDA BM
BHUTAN BT
BOLIVIA BO

BOSNIA AND HERZEGOVINA BA
BOTSWANA BW
BOUVET ISLAND BV
BRAZIL BR
BRITISH INDIAN OCEAN TERRITORY IO
BRUNEI DARUSSALAM BN
BULGARIA BG
BURKINA FASO BF
BURUNDI BI
CAMBODIA KH
CAMEROON CM
CANADA CA
CAPE VERDE CV
CAYMAN ISLANDS KY
CENTRAL AFRICAN REPUBLIC CF
CHAD TD
CHILE CL
CHINA CN
CHRISTMAS ISLAND CX
COCOS (KEELING) ISLANDS CC
COLOMBIA CO
COMOROS KM
CONGO CG
CONGO, THE DEMOCRATIC REPUBLIC OF THE CD
COOK ISLANDS CK
COSTA RICA CR
COTE D'IVOIRE CI
CROATIA HR
CUBA CU
CYPRUS CY
CZECH REPUBLIC CZ
DENMARK DK
DJIBOUTI DJ
DOMINICA DM
DOMINICAN REPUBLIC DO
ECUADOR EC
EGYPT EG
EL SALVADOR SV
EQUATORIAL GUINEA GQ
ERITREA ER
ESTONIA EE
ETHIOPIA ET
FALKLAND ISLANDS (MALVINAS) FK
FAROE ISLANDS FO
FIJI FJ
FINLAND FI
FRANCE FR
FRENCH GUIANA GF
FRENCH POLYNESIA PF
FRENCH SOUTHERN TERRITORIES TF
GABON GA
GAMBIA GM
GEORGIA GE
GERMANY DE
GHANA GH
GIBRALTAR GI

GREECE GR
GREENLAND GL
GRENADA GD
GUADELOUPE GP
GUAM GU
GUATEMALA GT
GUERNSEY GG
GUINEA GN
GUINEA-BISSAU GW
GUYANA GY
HAITI HT
HEARD ISLAND AND MCDONALD ISLANDS HM
HOLY SEE (VATICAN CITY STATE) VA
HONDURAS HN
HONG KONG HK
HUNGARY HU
ICELAND IS
INDIA IN
INDONESIA ID
IRAN, ISLAMIC REPUBLIC OF IR
IRAQ IQ
IRELAND IE
ISLE OF MAN IM
ISRAEL IL
ITALY IT
JAMAICA JM
JAPAN JP
JERSEY JE
JORDAN JO
KAZAKHSTAN KZ
KENYA KE
KIRIBATI KI
KOREA, DEMOCRATIC PEOPLE'S REPUBLIC OF KP
KOREA, REPUBLIC OF KR
KUWAIT KW
KYRGYZSTAN KG
LAO PEOPLE'S DEMOCRATIC REPUBLIC LA
LATVIA LV
LEBANON LB
LESOTHO LS
LIBERIA LR
LIBYAN ARAB JAMAHIRIYA LY
LIECHTENSTEIN LI
LITHUANIA LT
LUXEMBOURG LU
MACAO MO
MACEDONIA, THE FORMER YUGOSLAV REPUBLIC OF MK
MADAGASCAR MG
MALAWI MW
MALAYSIA MY
MALDIVES MV
MALI ML
MALTA MT
MARSHALL ISLANDS MH
MARTINIQUE MQ
MAURITANIA MR

MAURITIUS MU
MAYOTTE YT
MEXICO MX
MICRONESIA, FEDERATED STATES OF FM
MOLDOVA, REPUBLIC OF MD
MONACO MC
MONGOLIA MN
MONTSERRAT MS
MOROCCO MA
MOZAMBIQUE MZ
MYANMAR MM
NAMIBIA NA
NAURU NR
NEPAL NP
NETHERLANDS NL
NETHERLANDS ANTILLES AN
NEW CALEDONIA NC
NEW ZEALAND NZ
NICARAGUA NI
NIGER NE
NIGERIA NG
NIUE NU
NORFOLK ISLAND NF
NORTHERN MARIANA ISLANDS MP
NORWAY NO
OMAN OM
PAKISTAN PK
PALAU PW
PALESTINIAN TERRITORY, OCCUPIED PS
PANAMA PA
PAPUA NEW GUINEA PG
PARAGUAY PY
PERU PE
PHILIPPINES PH
PITCAIRN PN
POLAND PL
PORTUGAL PT
PUERTO RICO PR
QATAR QA
REUNION RE
ROMANIA RO
RUSSIAN FEDERATION RU
RWANDA RW
SAINT HELENA SH
SAINT KITTS AND NEVIS KN
SAINT LUCIA LC
SAINT PIERRE AND MIQUELON PM
SAINT VINCENT AND THE GRENADINES VC
SAMOA WS
SAN MARINO SM
SAO TOME AND PRINCIPE ST
SAUDI ARABIA SA
SENEGAL SN
SERBIA AND MONTENEGRO CS
SEYCHELLES SC
SIERRA LEONE SL

SINGAPORE SG
SLOVAKIA SK
SLOVENIA SI
SOLOMON ISLANDS SB
SOMALIA SO
SOUTH AFRICA ZA
SOUTH GEORGIA AND THE SOUTH SANDWICH ISLANDS GS
SPAIN ES
SRI LANKA LK
SUDAN SD
SURINAME SR
SVALBARD AND JAN MAYEN SJ
SWAZILAND SZ
SWEDEN SE
SWITZERLAND CH
SYRIAN ARAB REPUBLIC SY
TAIWAN, PROVINCE OF CHINA TW
TAJIKISTAN TJ
TANZANIA, UNITED REPUBLIC OF TZ
THAILAND TH
TIMOR-LESTE TL
TOGO TG
TOKELAU TK
TONGA TO
TRINIDAD AND TOBAGO TT
TUNISIA TN
TURKEY TR
TURKMENISTAN TM
TURKS AND CAICOS ISLANDS TC
TUVALU TV
UGANDA UG
UKRAINE UA
UNITED ARAB EMIRATES AE
UNITED KINGDOM GB
UNITED STATES US
UNITED STATES MINOR OUTLYING ISLANDS UM
URUGUAY UY
UZBEKISTAN UZ
VANUATU VU
VENEZUELA VE
VIET NAM VN
VIRGIN ISLANDS, BRITISH VG
VIRGIN ISLANDS, U.S. VI
WALLIS AND FUTUNA WF
WESTERN SAHARA EH
YEMEN YE
ZAMBIA ZM
ZIMBABWE ZW

OData Properties
For endpoints that are marked with OData support, you can run operations against the object properties
to filter the result set. Below you will find some examples of using OData on endpoints found within this
document. For the full OData specification, see http://www.odata.org/
Note: Many of the conditions below are formatted for readability but should be URL encoded during the
query. For example, ?$filter=Name eq ‘John Smith’ would become
?$filter=Name%20eq%20%27John%20Smith%27
Option Description
$filter Filters the results based on a Boolean condition.
See http://msdn.microsoft.com/en-us/library/hh169248(v=nav.71).aspx
$orderby Sorts the results
$skip Skips the first n results
$top Returns only the first n results
Examples
Request https://api.clearcompany.com/v1/reqs/status/closed?$top=10$skip=20
Result Returns 10 results starting a 20, resulting in entries 21 through 30 to be returned
Request https://api.clearcompany.com/v1/reqs/status/all?$filter=JobTitle eq ‘Account

Executive’ and RecruiterGuid eq guid‘87204dfe-c7ea-47c6-8965-a810e9d91aa6’
Result Returns all jobs or templates with the JobTitle exact value of "Account Executive"
that have the RecruiterGuid of "87204dfe-c7ea-47c6-8965-a810e9d91aa6"
Request https://api.clearcompany.com/v1/reqs/status/closed?$filter=year(CreatedDate) eq 2012

and DaysOpen gt 100
Result Returns all closed reqs created in 2012 that were open for more than 100 days
Request https://api.clearcompany.com/v1/reqs/status/closed?$filter=indexof(tolower(JobTitle),
‘account’) ne -1&$orderby=CreatedDate desc, Status asc
Result Returns all closed reqs that had "account" in the JobTitle (case insensitive) and order
the results by CreatedDate descending, job Status ascending
Request https://api.clearcompany.com/v1/users/active/all? $filter=indexof(tolower(Email),

'tsmith@somecompany.com') ne -1
Result Returns all active users with an email address of "tsmith@somecompany.com" (case
insensitive).
API Changes
13.4.1 Legacy API Base URL
In previous versions of this document, the API base location was https://ccapi.hrmdirect.com. As of
November 1st, 2013, the API base location has been changed to https://api.clearcompany.com. Requests
to either domain access identical functionality and there are no plans to prevent requests to the previous
base URL. Nevertheless, the old ccapi.hrmdirect.com location is depreciated and it is recommended to
move to the new base URL.

13.4.2 Legacy Header Information
In previous versions of this document, the required header values for requests were prefixed with
"HRM-". As of November 1st, 2013, these prefixes have changed to "API-". Requests using the old prefixes
are depreciated but will continue to work well into the future. Furthermore, the prefix you provide
determines the prefix you will receive in the request response headers. See the table below for previous
to current header mappings.
Previously: HRM-Realm Currently: API-Realm

Previously: HRM-Token Currently: API-Token
Previously: HRM-Token-Expires Currently: API-Token-Expires
13.4.3 Document Revisions and API Changes
Version 1.02 – 2022.01.21
 API rate limiting guidance changed. Users should not exceed 15 requests per second per set of API
credentials.
 Retrieve User by User
o Added the following fields to the JSON response. Note: These fields will be empty until
retrieved with API credentials granted the hr.admin permission.
 LegalFirstName
 LegalMiddleName
 LegalLastName
 MiddleName
o Added PersonalEmail to the JSON response
o Added optional URL parameter includeProfileImage=true that will return the users Base64
encoded user profile image in the ProfileImage property
 Update User by User Id
o The following fields can now be set
 LegalFirstName
 LegalMiddleName
 LegalLastName
 MiddleName
 PersonalEmail
 Retrieve User by User Id
o Added the following fields to the JSON response.
 LegalFirstName
 LegalMiddleName
 LegalLastName
 MiddleName
 PersonalEmail
 RoleId
 RoleStartDate
o Added an option URL parameter includeEntityDetails=true that will populate the following
JSON properties
 DepartmentName
 OfficeName

 SupervisorFirstName
 SupervisorLastName
 Create a User Account
 LegalFirstName
 LegalMiddleName
 LegalLastName
 MiddleName
 PersonalEmail
 RoleId
 Update a User Account by User Id or Custom Employee Id
 LegalFirstName
 LegalMiddleName
 LegalLastName
 MiddleName
 PersonalEmail
 RoleId
Version 1.01 – 2019.12.04
 Added following sections:

o Terminate a User Immediately by User Id
o Terminate a User on a Specific Date by User Id
o Get Status for a Pending Termination for a User by User Id
o Cancel a Pending Termination for a User by User Id
o Restore a Terminated User by User Id
Version 1.00 – 2019.11.05
 Added a section on how to authenticate separately from making REST endpoint calls. NOTE: This
does not invalidate in-line authentication for REST calls but that functionality might be sunset in
the future.
 Added authentication sample code
 Added a section on API rate limiting
Version 0.99 – 2019.07.26
 New properties were added to the Requisition object

o DepartmentName
o OfficeName
o OfficeLocation object (containing the address)
Version 0.98 – 2019.01.28
 User Account (employee) records can set the LatestHireDate when creating or updating a record.
 User Account (employee) object examples contain the following properties when doing GET
requests:

o LatestHireDate – The most recent start date for an employee
o RoleId – The id of the role assigned to the employee
o RoleName – The name of the role assigned to the employee
o RoleStartDate – The date the employee started in the current role
o EmployeeId – Your custom identifier for a given employee
 User Account (employee) objects can now SET the following property on creation and update
requests:
o LatestHireDate – The most recent start date for an employee
Version 0.97 – 2017.01.26
 API Fix: Requisitions are once again created in "On Hold" status.
 API Fix: Requisitions can be created using custom id’s for Office, Department, Hiring Manager and
Recruiter.
 API Fix: Username and EmployeeId property values restored to the user account JSON object.
 LastHireDate, RoleName, RoleId, RoleStartDate added to the user account JSON object.
Version 0.96 – 2017.09.29
 Added Update Requisition by Requisition Id.
Version 0.95 – 2017.01.25
 New user permissioned added to Appendix 13.1

 Fixed typos in authentication section.
Version 0.94 – 2015.02.26
 Updated Get Legacy Veteran Status results to include an "Active" property. Only active values are shown to applicants,
but for backwards compatibility the non-active values are now included in the collection.
Version 0.93 – 2014.05.09
 Added Get Applicant by Applicant Id.

 Added Get Applicant Onboarding Records by Applicant Id (OData queryable).
 Added Get Candidate by Candidate Id.
 Added Get Candidate Demographics by Candidate Id.
 Added Get Candidates by Requisition Id (OData queryable).
 Added Get Candidates by Requisition Id and Current Workflow Id (OData queryable).
 Added Get Candidates by Requisition Id and Historical Workflow Id (OData queryable).
 Added the following collections:
o Forms (OData queryable)
o Candidate Workflow Stages (OData queryable)
o Genders (OData queryable)
o Ethnicities (OData queryable)
o Races (OData queryable)
o Legacy Veteran Status (OData queryable)
o Veteran Status: Pre-Offer (OData queryable)
o Veteran Status: Post-Offer (OData queryable)
o Disability Status: Pre-Offer (OData queryable)
o Disability Status: Post-Offer (OData queryable)

 The following collections are now OData queryable
o Countries
o EEO Types
o Budget Types
o Job Functions
o Industries
o Requisition Custom Fields
o Candidate Custom Fields
 Get All Active Offices and Get All Active Departments are now OData queryable.
Version 0.92 – 2013.11.12
 Added Get All Active or Inactive User Accounts endpoint with OData support.
 Added Get All Active or Inactive User Accounts by Role endpoint with OData support.
Version 0.91 – 2013.11.06
 Added Get Requisitions by Status endpoint with OData support.

 All documentation updated to reflect new company name ClearCompany and new base API location moved to
api.clearcompany.com
 Documentation updates for authentication requests. Header names migrated from HRM- prefixes to API- prefixes.
 OData examples added in Appendix 10.3

ClearCompany REST API Specifications.v1.02

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

ClearCompany REST API Specifications.v1.02

Uploaded by

Copyright:

Available Formats

REST API Specifications

1. Web Services ......................................................................................................................................................... 6

2. Code Samples ........................................................................................................................................................ 6

3. Instantiating Requests ........................................................................................................................................... 6

Response Codes ............................................................................................................................................. 8

Response Content Type ................................................................................................................................. 8

API Rate Limits ............................................................................................................................................... 8

Retrieve Countries ......................................................................................................................................... 9

Retrieve EEO Types ...................................................................................................................................... 10

Retrieve Budget Types ................................................................................................................................. 11

Retrieve Job Functions ................................................................................................................................ 12

Retrieve Requisition Custom Fields ............................................................................................................. 14

Retrieve Candidate Custom Fields............................................................................................................... 16

Retrieve Forms ............................................................................................................................................ 17

Retrieve Candidate Workflow Stages .......................................................................................................... 18

Retrieve Genders ......................................................................................................................................... 18

Retrieve Ethnicities ...................................................................................................................................... 19

Retrieve Races ............................................................................................................................................. 20

Retrieve Legacy Veteran Status ................................................................................................................... 21

ClearCompany REST API Specification - Confidential Page 2

Retrieve Veteran Status: Post-Offer ............................................................................................................ 23

Retrieve Disability Status: Pre-Offer ............................................................................................................ 24

Retrieve Disability Status: Post-Offer .......................................................................................................... 24

5. Office Requests .................................................................................................................................................... 25

Retrieve All Active Offices ........................................................................................................................... 25

Retrieve an Office by Office Id..................................................................................................................... 25

Retrieve an Office by Custom Office Id ....................................................................................................... 26

Create a New Office..................................................................................................................................... 26

Update an Office by Office Id ...................................................................................................................... 27

Update an Office by Custom Office Id ......................................................................................................... 28

Retrieve an Office Address by Office Id ....................................................................................................... 28

Retrieve an Office Address by Custom Office Id ......................................................................................... 29

Update an Office Address by Office Id ........................................................................................................ 29

Update an Office Address by Custom Office Id ........................................................................................... 30

Retrieve All Active Departments ................................................................................................................. 31

Retrieve a Department by Department Id................................................................................................... 31

Retrieve a Department by Custom Department Id ..................................................................................... 32

Create a New Department .......................................................................................................................... 32

Update a Department by Office Id .............................................................................................................. 33

Update a Department by Custom Department Id ....................................................................................... 33

7. User Requests ...................................................................................................................................................... 34

Retrieve a User by User Id ........................................................................................................................... 34

Update a User by User Id............................................................................................................................. 35

ClearCompany REST API Specification - Confidential Page 3

Terminate a User on a Specific Date by User Id .......................................................................................... 36

Get Status for a Pending Termination for a User by User Id ....................................................................... 37

Cancel a Pending Termination for a User by User Id ................................................................................... 37

Restore a Terminated User by User Id ........................................................................................................ 37

8. User Account Requests ........................................................................................................................................ 38

Retrieve a User Account by User Id ............................................................................................................. 38

Create a User Account ................................................................................................................................. 39

Update a User Account by User Id .............................................................................................................. 40

Update a User Account by Custom Employee Id......................................................................................... 42

Retrieve User Account Permissions by User Id ........................................................................................... 44

Retrieve User Account Permissions by Employee Id ................................................................................... 44

Retrieve All Active or Inactive User Accounts ............................................................................................. 44

Retrieve All Active or Inactive User Accounts By Role ................................................................................ 45

9. Requisition Requests ........................................................................................................................................... 47

9.1.1 Retrieve a Requisition by Requisition Id .............................................................................................. 47

9.1.2 Retrieve a Requisition by Custom Requisition Id ................................................................................ 49

Create a New Requisition ............................................................................................................................ 51

Update Requisition By Requisition Id .......................................................................................................... 55

Listing Requisitions ...................................................................................................................................... 59

9.4.1 Get Requisitions By Status ................................................................................................................... 59