API introduction
The Kallidus Recruit Backoffice API is accessible by Super Users only from the settings menu in the Recruit backoffice. Simply click ‘API tokens’ at the foot of the left-hand menu in Settings.
Important note
An API token gives you super user access to the system via the API, so protect your tokens and don't share them with anyone or send to anyone else by email, etc. All activity which takes place via the API using your token(s) will be audited in your name.
If ever in doubt, deactivate or delete an existing token and create a new one.
Third party users who require access to the API should be added as a Super user to the system first and given details about how to create their own API tokens.
The API key needs to be supplied in a request header called "x-api-token".
Rate Limiting
We reserve the right to enforce a limit in cases where API use negatively impacts system performance. Some general advice:
- Wait a reasonable amount of time between each call, e.g., if a call takes 1 second then wait a second before calling it again. If it takes 5 seconds then wait 5 seconds.
- If an error happens, then retry, but only retry a set number of times with substantial delays between. If it fails, then try again straight away, but if it fails again, wait 10 mins, and if it still fails, wait an hour, etc.
- Finally, look at what you are ultimately doing and how many times you're doing it. Does it seem appropriate?
API use cases
- Manage the requisition templates that are available to start a new requisition with based on the positions that are actually vacancy within an HRIS, e.g. SAP
- Approve a vacancy in a third-party system then push that vacancy into Kallidus Recruit
- Get a list of candidates at an "Awaiting export to HR system" status, then pull all the data and documents for each candidate into your HR system and run a process to move each candidate to an "Exported" status in Kallidus Recruit once complete
- Get a list of active vacancies and associated vacancy data to display this information somewhere else
- Manage users automatically in the Kallidus Recruit system from another internal system
- Add or update data for one or more specific fields associated with a Person or Application record from a third party system, e.g. a Test score and taken date
Full list of API calls
Candidate
- List candidates - get a list of candidates who are in a particular status folder
- Get a candidate - get all the available data for a particular candidate
- Get a printable view - get a particular PDF document for a candidate
- Run a process - run a particular process on a particular candidate
- Update application data - allows data to be added to one or more Candidate fields (this is data that is specific to particular candidate application)
- Update person data - allows data to be added to one or more Person fields (this is data that is common to all of a particular candidate's applications, e.g. their address)
Configuration
- List classifiers - get a list of all the classifiers and classifier items in your system
- List vacancy texts - get a list of all the text-based vacancy fields in your system
- List folders - get a full nested list of all the candidate status folders in your system
- List printable views - find out what PDF documents are available for a candidate
- List security groups - get a list of the available user security groups for your system
- List user roles - get a list of all the available user roles in your system
- List candidate processes - get a list of the candidate processes that are available
- List vacancy workflows - returns a list of available vacancy workflow statuses in your system and their associated guids (global unique identifiers), so these may be used as a filter in other API calls
- List vacancy statuses - returns a list of the available standard system vacancy statuses and their associated IDs, so these may be used as a filter in other API calls
- List vacancy documents - returns a list of the available vacancy document fields and their associated guids, so these may be used in other API calls
- List available candidate application data evaluators - returns a list of the available Candidate/Application data fields and their associated guids (this is data that may be different between different applications), so these may be used in other API calls
- List available candidate person data evaluators - returns a list of the available Person data fields and their associated guids (this is data that is common to all of a particular candidate's applications, e.g. their address), so these may be used in other API calls
- Search classifiers - pass a search term to return a list of any classifiers containing the search term, along with all list options for the returned classifiers and all guids, so these may be used in other API calls
- Search classifier items - pass a search term to return a list of any classifier items containing the search term, along with all the guids, so these may be used in other API calls
- Find classifier items by exact name - pass a classifier name and a search term to return a list of any classifier items exactly matching the search term within the named classifier, along with all the guids, so these may be used in other API calls
Requisition templates
- List requisition templates - get a list of all requisition templates in your system
- Delete a requisition template - allows a requisition template to be deleted
- Get a requisition template - get all the data for a particular requisition template
- Update a requisition template - allows an existing requisition template to be updated via the API
- Add a requisition template - allows a new requisition template to be added via the API
- Delete a requisition document - allows a requisition document to be deleted via the API
- Retrieve a requisition document - allows a requisition document to be obtained via the API
- Add or update a requisition document - allows a new requisition document to be added or an existing one to be updated via the API
User
- Get current user - get all the details for the user whose API token it is
- Save a user - add a new user or update an existing user
- Delete a user - allows an existing user to be deleted
- Get user by ID - get all the details for a particular user
- List users - get a list of all the users in your system
- User search - pass a search term to return a list of any users where the search term matches their login or email address
Vacancy
- List vacancies - get a list of all vacancies in your system or vacancies at a particular status (or workflow status if implemented)
- Update a vacancy - allows an existing vacancy to be updated via the API
- Add a vacancy - allows a new vacancy to be added via the API
- Get a vacancy - get all the data for a particular vacancy
- Delete a vacancy document - allows a vacancy document to be deleted via the API
- Retrieve a vacancy document - allows a vacancy document to be obtained via the API
- Add or update a vacancy document - allows a new vacancy document to be added or an existing one to be updated via the API
Common use case - pull new hires into your HR system using the API