Changelog
Back to All

Configuration API - Job Ad Fields configuration management

October 5th, 2026

Description

The Configuration API now exposes endpoints for managing the Job Ad Fields configuration for a company.

The following endpoints are available:

  • GET /configuration/job-ad-fields — retrieves the current Job Ad Fields configuration for the company.
  • PUT /configuration/job-ad-fields — updates the Job Ad Fields configuration for the company.

The configuration describes whether each active Job Ad field is OPTIONAL or MANDATORY. The set of available fields depends on the company's enabled features.

The GET response includes companyId, a fields map of field identifiers to their requirement, and updatedAt — a Unix timestamp in milliseconds of the last explicit update. updatedAt is null when the configuration has never been explicitly set.

Example GET response:

{
  "companyId": "6a29256849bbea9f2a373f57",
  "fields": {
    "JOB_DESCRIPTION": { "requirement": "MANDATORY" },
    "QUALIFICATIONS":  { "requirement": "OPTIONAL" }
  },
  "updatedAt": 1710000000000
}

The PUT request must include all currently active fields for the company — partial updates are not supported. On success, the response returns the updated configuration in the same shape as GET.

Example PUT request body:

{
  "fields": {
    "JOB_DESCRIPTION": { "requirement": "MANDATORY" },
    "QUALIFICATIONS":  { "requirement": "OPTIONAL" }
  }
}

The endpoints require the following OAuth scopes:

  • configuration_read — for GET /configuration/job-ad-fields
  • configuration_manage — for PUT /configuration/job-ad-fields

Impact

This is an additive, backward-compatible change. No existing endpoints or integrations are affected.

Clients with the required scopes can now retrieve and manage the Job Ad Fields configuration programmatically instead of relying solely on the SmartRecruiters user interface.

The update endpoint returns HTTP 422 with error code INVALID_JOB_AD_FIELD_CONFIGURATION when the request contains an unknown field identifier or does not include all currently active fields for the company. Clients should call GET /configuration/job-ad-fields first to inspect the current configuration before submitting an update.

Access is denied with HTTP 403 when the OAuth token is missing the configuration_manage scope or when the Configurable Job Ad Fields feature is not enabled for the company.

No migration steps are required for existing integrations.

References