This article explains how to use the ELMO Candidate API, a feature designed to help you securely get candidate details directly from your ELMO recruitment module. This is particularly useful for integrating with third-party recruitment tools (like those for background checks or psychometric assessments).
đ
Access to the ELMO Public API, including the Candidate API, requires a specific setup and subscription. Please contact your ELMO Account Manager to discuss enabling API access for your organisation.
Key Features of the Candidate API
The ELMO Candidate API is part of our ELMO Public API. It allows external systems, like your chosen recruitment tools, to build their own integrations directly into ELMO to receive candidate information.
Here are the key functionalities:
Access Candidate Data: A new endpoint, GET /candidates, is now available (you can access it via https://[your_tenant].elmotalent.com.au/api/recruitment/v1/candidates). This lets your applications request and receive lists of candidates from ELMO.
Search and Filter: You'll be able to search for specific candidates or narrow down your list using various details. Supported search criteria include:
Candidate's Name (using firstName and lastName parameters)
Email Address (email)
Phone Number (mobile, homePhone)
Unique Candidate ID (id)
Pagination: To handle large lists efficiently, the endpoint supports pagination. This means data can be retrieved in smaller, manageable chunks or "pages" using the standard page and itemsPerPage query parameters.
Retrieve Key Candidate Information: The data returned for each candidate includes essential details needed for partner integrations, such as:
Contact Information (name, email, phone, address)
Education History
Work Experience
Language Proficiencies
Skills
How to Get Started
Contact Your Account Manager: Access to the ELMO Public API, including the Candidate API, requires a specific setup and subscription. Please contact your ELMO Account Manager to discuss enabling API access for your organisation.
Review Developer Documentation: Once access is enabled, your technical team or chosen third-party vendor should refer to the ELMO developer portal for the most current and detailed information on authentication requirements and how to use the API.
Developer Portal: https://developer.elmotalent.com.au/
Getting Started with ELMO API
When adding new API credentials, select the Scope as 'Recruitment API'.
â
â ď¸
Please note that if you have selected only the Recruitment API Scope, your generated API credentials will grant access exclusively to Candidate Endpoints.
Frequently Asked Questions (FAQs)
What kind of API is the Candidate API? +
The Candidate API is part of ELMO's Public API offering. It works over HTTPS and follows REST standards, using JSON format for exchanging data between systems.
Can the Candidate API data be used with more than one third-party system? +
Yes. Once a partner system gets candidate data using the Candidate API, that data can be used as needed by that partner. This means they could potentially integrate it with multiple other systems or tools on their side. Standard API rate limits still apply, no matter how many systems use the data they retrieve.
How do we get access to use the Candidate API? +
Access to the ELMO Public API, including the Candidate API endpoint, requires some setup and a subscription. Please contact your ELMO Account Manager to discuss enabling API access for your organisation.
How does authentication work for the Candidate API? +
The Candidate API, as part of the ELMO Public API, uses OAuth 2.0 for secure, token-based authorisation. This is our recommended method. Your partners should set up a suitable OAuth 2.0 process to get access tokens for their API requests. For the most up-to-date details on authentication, please refer to the ELMO developer portal.
How does the /candidates endpoint fit within the broader ELMO Public API ecosystem? +
The GET /candidates endpoint is a core part of the ELMO Public API and works under the same rules and standards as other available endpoints. This means:
Setup & Access: Access to the candidate endpoint is managed through the standard ELMO Public API subscription. Your credentials usually cover multiple endpoints based on your agreement. We offer granular access control, so you can give different third parties access to specific endpoints only (e.g., one can access user data, another only candidate data).
Rate Limiting & Quotas: Using the Candidate endpoint contributes to your overall API rate limits and usage quotas defined for your client account across the entire ELMO Public API. Calls to this endpoint count towards your total alongside calls to other endpoints.
Developer Experience: This endpoint follows the same technical standards (REST principles, JSON data format), uses the shared OAuth 2.0 authentication, and is documented within the central ELMO developer portal using the same OpenAPI v3 specification as other Public API endpoints. This consistency provides a familiar experience when integrating with various parts of ELMO via the API.
Is there a developer portal or documentation for the Candidate API? +
Yes, ELMO provides a developer portal with full documentation for the Public API, including the /candidates endpoint. The documentation follows the OpenAPI Specification v3 standard and includes details on endpoints, parameters, data formats, sample responses, and potentially sample code.
Does ELMO support Webhooks for real-time updates (e.g., about candidates)? +
While this initial Candidate API endpoint focuses on getting existing candidate data when requested, ELMO does not currently offer webhooks support for the Candidate endpoint for real-time updates.
Does the Candidate API support pagination for large lists? +
Yes, the GET /candidates endpoint supports pagination. You can retrieve large lists of candidates in manageable chunks using the page and itemsPerPage query parameters, as detailed in the API documentation.
How are changes to the Candidate API communicated? Is there a change history? +
ELMO aims to ensure backward compatibility for updates to Public API endpoints like the Candidate API. Major changes typically involve API versioning. Significant API releases and updates are communicated via ELMO's monthly Product update emails. While a dedicated public change history for the API is planned for the future, it is not available at this point (as of late April 2025).