Changelog
Back to All

Candidates & Configuration APIs - Expose External Code for Property Values

September 7th, 2026

Description

Exposes externalCode on property value responses for fields managed by external integrations e.g. SuccessFactors.

What is externalCode?

externalCode is the source system's natural key for a value — the stable, human-readable identifier assigned by the external system (e.g. SuccessFactors externalCode on picklist entries or org objects).
It is used to correlate SmartRecruiters field values with their counterparts in the originating system.
This field is read-only: currently, it is set by the SuccessFactors integration only and cannot be modified through the SmartRecruiters API.

Configuration API

Changed

  • GET /configuration/job-properties/{id}/values — response items now include externalCode when a cross-system data code is set.
  • GET /configuration/candidate-properties/{id}/values — response items now include externalCode when a cross-system data code is set.
  • GET /configuration/candidate-properties/{id}/values/{valueId} — response now includes externalCode when a cross-system data code is set.
  • GET /configuration/job-properties/{id}/dependents/{dependentId}/values — child values in content[].values now include externalCode when a cross-system data code is set.
  • GET /configuration/job-properties/{id}/values/{valueId}/dependents/{dependentId}/values — response items now include externalCode when a cross-system data code is set (applies to both streaming and paged responses).

New dedicated response types introduced:

  • JobPropertyValueView — extends JobPropertyValueDefinition
  • CandidatePropertyValueView — extends CandidatePropertyValue

Existing response types extended with optional externalCode:

  • DependentJobPropertyValue
  • RelationJobPropertyValue

These types are used only on the read endpoints above. Write endpoints (POST, PUT) retain the base schemas and are unaffected.

Example value with externalCode:

{
  "id": "abc123",
  "label": "Engineering",
  "externalCode": "ENG_01"
}

Example value without externalCode (field absent, not null):

{
  "id": "def456",
  "label": "Sales"
}

Candidates API

Changed

  • GET /candidates/{id}/properties — each item in the existing selectedValueLabels array now includes externalCode when a cross-system data code is set on that value option.
  • GET /candidates/{id}/jobs/{jobId}/properties — same as above.

selectedValueLabels is present on SELECT and MULTI_SELECT fields. Each entry previously contained { id, label }; it now optionally includes externalCode.

Example selectedValueLabels entry with externalCode:

{
  "id": "abc123",
  "label": "Engineering",
  "externalCode": "ENG_01"
}

Example selectedValueLabels entry without externalCode (field absent, not null):

{
  "id": "def456",
  "label": "Sales"
}

Impact

No breaking changes. externalCode is an additive field on existing selectedValueLabels items — existing clients that do not read it are unaffected.

References