Important Customer API Updates
No schema changes or new elements are introduced in the January 2018 Winter release. However, due to the introduction of parallel processing, Candidate API endpoints will begin returning multiple applications per candidate if a candidate has multiple applications.
Before parallel processing, a candidate could only have 1 active application at a time for a single company. Active applications are those in any status but Lead. All other applications were marked inactive. When requesting a candidate from the Customer API, endpoints would always modify or return the active application found in the
Now that parallel processing has been introduced, a candidate can have more than 1 active application with a company. As a result, there are 2 key updates :
Update #1 – For all Customer API endpoints that contain the
primaryAssignment field in the request response, the underlying logic has changed in the following way:
- If a candidate has more than one active application, the API will return the most recently updated active application in the
- If there is just one active application, the API will return it in the
- If there are no active applications, the most recently updated inactive application will be returned in the
Update #2 – We are deprecating several endpoints that may no longer behave as expected due to this change.
We recommend you review your integrations to see if they use any of the below endpoints. When possible, you should update to the alternative endpoints provided which require both candidateID and jobID as parameters. This will ensure that you access a specific candidate’s application rather than the last updated application or be subject to the logic in Update #1.
If using any of the deprecated endpoints today, you must migrate to the corresponding alternative endpoints by November 29, 2018.
We will be extending the life of these endpoints until January 31, 2019 to provide customers with more time to adjust their integrations.
|Deprecated endpoints||Alternative endpoints|
Again, the deprecated endpoints will be available until they are sunset on November 29, 2018.
We will be extending the life of these endpoints until January 31, 2019 to provide customers with more time to adjust their integrations. We recommend migrating integrations to the alternate version of the endpoint as soon as possible.
Detailed examples of endpoint logic changes
The examples below demonstrate how this release will affect responses from Customer API endpoints which contain the
1. Integrations using the
GET /candidates endpoint to search candidate applications
Previously, searching candidates using the
GET /candidates endpoint would return only candidates whose primary applications match the specified criteria.
Now, all applications belonging to a candidate will be searched, and a candidate could be returned multiple times if the candidate has multiple matching applications. If this is undesirable for your integration, you should also specify
jobID in your query.
2. Integrations that get or modify candidate application properties using only CandidateID, for example,
These endpoints will only retrieve or modify the
primaryAssignment application following the logic outlined in the last section. Instead, integrations should use endpoints that also accept
jobId to be sure the right application is retrieved or modified. See the table above.
Updated 9 months ago