Replace Employee
Header Parameters
Optional correlation ID for distributed tracing.
Required client-generated UUID v4 used to deduplicate retried mutating requests (POST, PUT, PATCH, DELETE). Requests without this header are rejected with 400 Bad Request. The first successful (2xx) response is cached for 24h and replays of the same key return the cached response without re-executing the operation.
Path Parameters
Employee record external identifier (UUID v4).
Body Parameters
Unique employee number within the employer.
Employee's first name.
Employee's last name.
Employee's middle name.
Employee's email address.
Date of birth (YYYY-MM-DD).
US Social Security Number.
Self-reported gender of the employee.
Partner identifier for cross-domain lookups.
Employer identifier for cross-domain lookups.
Employment information sub-object for employee creation and full update.
Show child attributes
Employee postal addresses. Replaces the entire collection when supplied; omit this field or send an empty array to clear all addresses. null is not accepted. If one or more entries are supplied, at most one entry per type (HOME, WORK, MAILING), and at most one entry may be flagged as is_primary: true.
Show child attributes
Employee phone numbers. Replaces the entire list when supplied; omit this field or send an empty array to clear all phone numbers. null is not accepted.
Show child attributes
Current version for optimistic concurrency. The request is rejected with 409 Conflict if it does not match the persisted version.
Response
OK – Employee record updated
Response Attributes
Unique identifier for the employee record (UUID v4).
Unique employee number within the employer.
Employee's first name.
Employee's last name.
Employee's middle name.
Employee's email address.
Date of birth (YYYY-MM-DD). Direct identifier — handled as restricted data.
US Social Security Number. Direct identifier — handled as restricted data.
Self-reported gender of the employee.
Employment information for an employee.
Show child attributes
Employee postal addresses. Always present; may be an empty array when no addresses are on file. When one or more entries are present, at most one entry per type (HOME, WORK, MAILING), and at most one entry is flagged as is_primary: true.
Show child attributes
Partner identifier for cross-domain lookups.
Employer identifier for cross-domain lookups.
Monotonically increasing version used for optimistic concurrency control on PUT/PATCH. Always returned.
Employee phone numbers. Returned only when the request specifies expand=PHONE_NUMBERS; otherwise, this property is omitted. When returned, the value is an array and may be empty.
Show child attributes
Bad Request – Validation failed. The errors map keys mirror the snake_case JSON property names used in the request payload.
Response Attributes
List of invalid parameters that caused the validation error.
Show child attributes
Human-readable validation error messages keyed by field name. Each key maps to one or more error message strings.
Show child attributes
Field-level validation errors keyed by field name. Each key maps to one or more structured error details.
Unauthorized – Missing or invalid credentials.
Response Attributes
List of invalid parameters that caused the validation error.
Show child attributes
Human-readable validation error messages keyed by field name. Each key maps to one or more error message strings.
Field-level validation errors keyed by field name. Each key maps to one or more structured error details.
Forbidden – Insufficient permissions.
Response Attributes
List of invalid parameters that caused the validation error.
Show child attributes
Human-readable validation error messages keyed by field name. Each key maps to one or more error message strings.
Field-level validation errors keyed by field name. Each key maps to one or more structured error details.
Not Found – Employee record does not exist.
Response Attributes
List of invalid parameters that caused the validation error.
Show child attributes
Human-readable validation error messages keyed by field name. Each key maps to one or more error message strings.
Field-level validation errors keyed by field name. Each key maps to one or more structured error details.
Conflict – Returned for duplicate-record conflicts and optimistic concurrency version mismatches. See duplicate_record and version_conflict examples.
Response Attributes
List of invalid parameters that caused the validation error.
Show child attributes
Human-readable validation error messages keyed by field name. Each key maps to one or more error message strings.
Field-level validation errors keyed by field name. Each key maps to one or more structured error details.
Internal Server Error.
Response Attributes
List of invalid parameters that caused the validation error.
Show child attributes
Human-readable validation error messages keyed by field name. Each key maps to one or more error message strings.
Field-level validation errors keyed by field name. Each key maps to one or more structured error details.
Internal Server Error.
Response Attributes
List of invalid parameters that caused the validation error.
Show child attributes
Human-readable validation error messages keyed by field name. Each key maps to one or more error message strings.
Field-level validation errors keyed by field name. Each key maps to one or more structured error details.