Changelog
Back to All

Offers API - Expose Property Details with External Codes

October 5th, 2026

Description

The following endpoints now include a new propertiesDetails field alongside the existing properties field:

  • GET /candidates/{id}/jobs/{jobId}/offers
  • GET /candidates/{id}/jobs/{jobId}/offers/{offerId}

properties remains unchanged: a flat map of merge field key to raw string value. propertiesDetails is additive and gives richer, per-field detail, including each field's definition id, its origin, and its resolved value (including externalCode when the underlying field or value is managed by an external integration, e.g. SuccessFactors).

Example:

{
  "properties": {
    "Job_SF_Object_LegalEntity_Company": "642551541"
  },
  "propertiesDetails": [
    {
      "mergeFieldKey": "Job_SF_Object_LegalEntity_Company",
      "key": "SF_Object_LegalEntity_Company",
      "id": "18bd0065-fee3-46fc-95ca-6cae082fdb2c",
      "origin": "JOB_FIELD",
      "value": {
        "id": "642551541",
        "label": "LegalOO1",
        "externalCode": "LegEnt_OO"
      }
    }
  ]
}

Fields

  • mergeFieldKey: the same key used in properties.
  • key: the field's key. For JOB_FIELD entries this strips the Job_ prefix from mergeFieldKey; APPLICATION_FIELD and OFFER_AD_HOC_FIELD entries have no prefix, so key is identical to mergeFieldKey.
  • id: the field definition's id. null for ad hoc fields (fields not backed by a job or candidate field definition, e.g. ApplicantCountryCode).
  • origin: the field's origin: JOB_FIELD, APPLICATION_FIELD, or OFFER_AD_HOC_FIELD.
  • value.id, value.label, value.externalCode: the resolved value. For text fields, id holds the raw text and label/externalCode are absent. For single-select fields, id and label are populated when the selected value is currently resolvable; externalCode is included only when a cross-system data code is set for that value.

Handling missing data

  • If a field's definition can no longer be resolved (e.g. removed from company configuration), it is omitted from propertiesDetails entirely, even though its raw value is still present in properties.
  • If the field definition is still active but the previously selected value can no longer be resolved (e.g. deactivated), the entry is still included, with the real field id and an empty value object.

Impact

This is an additive, backward-compatible change. Existing consumers reading properties are unaffected. propertiesDetails is a new, optional field.

References