Users API - Expose personIdExternal on user responses

Description

The personIdExternal field is now exposed on all user read responses. It holds the external person identifier from the managing system (e.g. SuccessFactors personIdExternal) and is useful for correlating SmartRecruiters users with their counterparts in an external systems.

This field is read-only: currently, it is set by the SuccessFactors integration only and cannot be modified through the SmartRecruiters API.

Users API

Changed

• GET /users — each item in content now includes personIdExternal when set on the user. A dedicated personIdExternal query parameter (repeatable, max 100 values) allows filtering users by their external person identifier: GET /users?personIdExternal=P00012345&personIdExternal=P00099999.
• GET /users/{id} — response now includes personIdExternal when set on the user.
• GET /users/me — response now includes personIdExternal when set on the user.
• PATCH /users/{id} — response now includes personIdExternal when set on the user. Patch operations targeting /personIdExternal are silently ignored.
• POST /users — response schema now includes personIdExternal. The field cannot be set via this endpoint and will always be absent on a newly created user.

Example response with personIdExternal:

{
  "id": "50c098202cdc5982df671c43",
  "firstName": "John",
  "lastName": "Doe",
  "personIdExternal": "P00012345"
}

Example response without personIdExternal (field absent when not set):

{
  "id": "50c098202cdc5982df671c43",
  "firstName": "Jane",
  "lastName": "Smith"
}

Impact

No breaking changes. personIdExternal is an additive, read-only field on existing response schemas. Existing clients that do not read it are unaffected. Write endpoints (POST /users, PATCH /users/{id}) do not accept this field as input.

References

• GET /users
• GET /users/{id}
• GET /users/me
• PATCH /users/{id}
• POST /users