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 primaryAssignment field.

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:

1. If a candidate has more than one active application, the API will return the most recently updated active application in the primaryAssignment field.
2. If there is just one active application, the API will return it in the primaryAssignment field.
3. If there are no active applications, the most recently updated inactive application will be returned in the primaryAssignment field.

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
>PUT /candidates/{id}/onboardingStatus	PUT /candidates/{id}/jobs/{jobId}/onboardingStatus
GET /candidates/{id}/onboardingStatus	GET /candidates/{id}/jobs/{jobId}/onboardingStatus
GET /candidates/{id}/properties	GET /candidates/{id}/jobs/{jobId}/properties
PUT /candidates/{id}/properties/{propertyId}	PUT /candidates/{id}/jobs/{jobId}/properties/{propertyId}
PUT /candidates/{id}/status	PUT /candidates/{id}/jobs/{jobId}/status
GET /candidates/{id}/status/history	GET /candidates/{id}/jobs/{jobId}/status/history

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 primaryAssignment field.

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, PUT /candidates/{id}/properties

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.