Changelog

Candidates API - Added validation when updating candidate

Description

We have introduced enhanced validation measures to prevent the creation of duplicate records during candidate updates.
Validation is not passed when an attempt is made to update a candidate's email address or last name to one already
associated with another candidate. In our system, the combination of email and last name must be unique, and it is not
possible to have two candidates with the same email address and last name.

Impact

This change affects the PATCH /candidates/id endpoint (operationId: candidates.update) in the Candidates API. If users try to update a candidate's e-mail
or last name to one that another candidate already owns, they will receive a 409 Conflict status code with
the code CANDIDATE_DATA_CONFLICT.

References

Candidates API - Relaxed UUID validation

Description

We have removed UUID validation for the id property in the PUT /candidates/{id}/jobs/{jobId}/properties endpoint
(operationId: candidates.properties.values.batchUpdateForJob). This change is intended to maintain consistency with other parameters
that do not have this format enforced. The valid format for the id remains unchanged and will remain as UUID.

Impact

There shouldn’t be any significant impact as there were no server-side validation of this format.
If user doesn’t provide UUID, he will receive status 404 NOT FOUND with code PROPERTY_NOT_FOUND as usual.
The only potential impacts are:

  • relaxed validation in the Swagger/UI of the Developer portal
  • if the user manually reads and interprets OpenAPI Specification for any reason.

References

Jobs API - Support coordinates for Job and Job ad

Description

We have added support for the latitude and longitude properties for the location object.

Impact

Job and Job ad can be created and updated with coordinates: latitude and longitude provided in the location property.
This change is backward compatible. The latitude and longitude properties are optional.
If not provided, the Job or Job ad location will be saved/updated without the coordinates.

References

Configuration API - Expose sandbox public api [BETA]

Description

Sandbox Public API [BETA] endpoints are for creating customer integrations using new sandboxes.

There is a concept of configuration id introduced. This is an additional identifier linking related entities in production company and sandbox(es). If integration hardcodes the configuration id of referenced object instead of entity id the actual entity id for the production/sandbox company (associated with the credentials) could be retrieved from the entity mapping. This allows for keeping the integration code intact while running it against production or sandboxes.

These are the new sandboxes endpoints:

  • getting list of available entity names [BETA]: /configuration/entity-mapping/entity-names
  • retrieve entity mappings by configuration id [BETA]: /configuration/entity-mapping/entity-name/{entityName}/by-configuration-id
  • retrieve entity mappings by entity id [BETA]: /configuration/entity-mapping/entity-name/{entityName}/by-entity-id

Notes:

  • please be aware that these endpoints are [BETA] and can be changed or removed without prior warning.
  • department entity mappings currently available only using dedicated DEPARTMENT entity name. Not available as backing it JOB_PROPERTY.

Impact

There is no impact of this change on the users. New endpoints don't change any existing functionality but introduce a new one.

Also these endpoints are [BETA] and can be changed or removed without prior warning.

References

Event Management API - Introduction

Description

Introducing our new public API - Event Management API.
This API enables you to manage scheduling events within SmartRecruiters, allowing you to create, update, delete, and retrieve events. Additionally, you can manage event sessions and session attendees, including both interviewers and applicants.
Please note, as the Event Management feature is still under development, the public API may not fully align with the UI yet. We are actively working on this.
To use this API, you will need the following access scopes: event_management_read or event_management_write.

Impact

The Event Management API empowers you to handle events and sessions in SmartRecruiters, providing similar functionality to the UI.

References

SmartOnboard API - add new webhooks for integration relevant-assignments

Description

SmartOnboard API endpoint to get all assignments expose additional optional property integrationKey for all types of assignments (ACTIVITY, WEB_FORM, FILLABLE_PDF_FORM)

2 new webhooks are added to SmartOnboard API to notify about integration-relevant assignments(with integrationKey defined) completion:

  • when single integration-relevant assignment is completed: onboarding.assignment.integration-relevant.completed
  • when all integration-relevant assignments are completed: onboarding.assignments.integration-relevant.completed

Additionally we have exposed an endpoint to retrieve particular assignment by assignment ID and onboarding ID.

Impact

The new property "integration key" allows users to track integration status of onboarding assignments.
The integration status field is exposed to recruiter UI to set and change. The field itself is optional and the API
allows filtering assignment that have this property.

References

Configuration API - Expose source identifier

Description

Configuration API endpoints expose additional property sourceIdentifier for the following source related endpoints:

  • GET /configuration/sources/{sourceType}/values
  • GET /configuration/sources/{sourceType}/values/{sourceValueId}

The enhanced Source object structure with sourceIdentifier property

     type: object
     required:
       - id
       - sourceIdentifier
       - label
       - sourceSubType
       - actions
     properties:
       id:
         type: string
       sourceIdentifier:
         type: string
         format: uuid
       label:
         type: string
       sourceSubType:
         $ref: '#/components/schemas/Identifiable'

Impact

The new property allows to obtain the source identifier for use with apply URL or posting URL every candidate you push to SmartRecruiters.
To know where the candidate came from you will need the sourcing identifier (TRID or SID).

Sourcing identifier is the query parameter at the end of apply / posting URL.

The URL have the following format:

https://apply_URL.?trid=sourceIdentifier

References

Jobs API - Support location for job ad

Description

We have added support for the location property for a Job Ad in the Jobs API.

Impact

Job Ad can be created, updated and retrieved with the location property.
This change is backward compatible. The location property in Job ad is optional.
If not provided, it will default to the Job location, following the current system behavior.

References

Application API - Removed SmartR links

Description

Due to SmartR service sunset (the extended opt-out period ended on Jun 19, 2024), it's no longer possible for
Application API clients to request and receive SmartR Join Url and Candidate Portal (SmartR) Url when creating an application.

The following changes have been made in the Application API - Post an Application endpoint:

  • createJoinLink property removed from request payload
  • smartrJoinUrl property removed from the response body
  • candidatePortalUrl property removed from response body

Impact

Requests with the createJoinLink property will be accepted, however its value will be ignored by the API.

There is no replacement for the smartrJoinUrl or candidatePortalUrl properties.
The link to the new solution (Applicant Tracking Portal) will be sent to the candidate via email.

References

Webhooks API - Fix error handling for subscription activation

Description

We have fixed an issue in the Webhooks API where the activation of a subscription could fail due to an error in fetching the token needed for handshake authentication. Previously, this would result in a general 500 error. Now, the API will return a 424 HTTP status code if the token required for handshake authentication cannot be fetched during subscription activation.

The 424 HTTP status code was already used for handshake failures. With this change, authentication needed for the handshake is also treated as part of the handshake failure. From now on, instead of a general 500 error, a 424 error will be returned with the following response body:

{
  "errors": [
    {
      "code": "HANDSHAKE_FAILED",
      "message": "[Fallback] Problem with getting token for subscription: 41a50be7-3edd-42a1-a302-bc7fca51d7c5"
    }
  ]
}

Impact

This change is backward compatible, it does not introduce any new error codes, 424 was already returned in case of handshake failure.

References