Create 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.
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. Omit this field if addresses are not being provided during create; send an empty array to indicate the employee has no addresses. 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. Omit this field if phone numbers are not being provided during create; send an empty array to indicate the employee has no phone numbers.
Show child attributes
Response
Created – Employee record successfully created
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.
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.