# Workday — HRIS API: gotchas

> Canonical URL: https://developers.apideck.com/apis/hris/workday/gotchas

## GET /hris/employees

To avoid request timeouts when fetching all employees, it's recommended to use a limit of 20. Workday can return large amounts of data per employee, and requests exceeding 30 seconds will timeout with an "Endpoint request timed out" error.

List Employees returns the employee's department (`department_id`, `department_name`) and company (`company_id`, `company_name`), with the same values as Get Employee. `division_id`, `division` and `custom_fields` are returned on Get Employee only.

`company_id` and `company_name` are the worker's legal company: the Workday organization of type Company assigned to the worker's primary job. Company hierarchies (consolidation roll-ups such as regions) are not returned. When the worker has no job data visible to the integration user, both fields are empty.

List Employees returns workers as of today, so future-dated hires (hire date after today) are not included by default. Pass `filter[as_of_date]` (YYYY-MM-DD) with a future date to include them; it is sent to Workday as `Response_Filter.As_Of_Effective_Date`. Note that a future as-of date also returns existing workers as of that date, including any future-dated job or compensation changes. Get Employee does not accept this filter and always returns the worker as of today.

Address lines: when Workday's address format for the country splits the street into components, `addresses[].line1` is built from them in this order: the street type when there is one (for example Spanish `Calle` or `Carrer`), then the street name, then the house number; so a Spanish address reads `Calle Montesa 16` and the house number is also returned as `street_number`. `line1` always places the house number after the street name, even where Workday's own formatted address in `string` puts it first, as for France and South Africa (`Rue Juliette Lamber 13`). When the format has a house number but no labelled street name, the lowest-numbered other component is used as the street name. The remaining typed components (building, unit, floor and similar) fill `line2` to `line5` in Workday's line order. For formats without a street-type or street-name component and without a house-number component (for example the US), `line1` is the lowest-numbered address line as Workday returns it, the others follow in `line2` to `line5`, and `street_number` is omitted. `jobs[].location` applies the same `line1` and `street_number` rules; its `line2` to `line5` are not mapped.

## GET /hris/employees/{id}

Job Level (e.g., Junior, Intermediate, Senior, Principal) is exposed as a custom field `Job_Level_ID` on the Get Employee response only — not on List Employees. It is sourced from a separate `Get_Job_Profiles` SOAP call against Workday's Human_Resources service and merged into the response.

Job Level is omitted when the worker's job profile does not define `Job_Level_Reference` in Workday (configured per profile), or when the connection's Integration System User does not have access to `Get_Job_Profiles` on the Human_Resources web service. Other custom fields and the rest of the response are unaffected in either case.

This enrichment is intentionally not performed on List Employees to avoid an extra SOAP call per worker.

On Get Employee, `manager.name`, `manager.first_name`, `manager.last_name`, `manager.email` and `manager.employment_status` are populated from a separate lookup of the manager's own worker record (List Employees returns `manager.id` only). When Workday cannot return that record — for example the manager is terminated, or is outside the integration user's security scope — those fields are omitted, `manager.id` is still returned, the rest of the employee is unaffected, and the response carries a `meta.warnings` entry of type `downstream_request_failed`. When the employee has no manager reference, `manager` is omitted from the response entirely and no warning is emitted.

`company_id` and `company_name` are the worker's legal company: the Workday organization of type Company assigned to the worker's primary job. Company hierarchies (consolidation roll-ups such as regions) are not returned. When the worker has no job data visible to the integration user, both fields are empty.

Address lines: when Workday's address format for the country splits the street into components, `addresses[].line1` is built from them in this order: the street type when there is one (for example Spanish `Calle` or `Carrer`), then the street name, then the house number; so a Spanish address reads `Calle Montesa 16` and the house number is also returned as `street_number`. `line1` always places the house number after the street name, even where Workday's own formatted address in `string` puts it first, as for France and South Africa (`Rue Juliette Lamber 13`). When the format has a house number but no labelled street name, the lowest-numbered other component is used as the street name. The remaining typed components (building, unit, floor and similar) fill `line2` to `line5` in Workday's line order. For formats without a street-type or street-name component and without a house-number component (for example the US), `line1` is the lowest-numbered address line as Workday returns it, the others follow in `line2` to `line5`, and `street_number` is omitted. `jobs[].location` applies the same `line1` and `street_number` rules; its `line2` to `line5` are not mapped.


[API reference](https://developers.apideck.com/apis/hris/reference.md) · [Coverage matrix](https://developers.apideck.com/apis/hris/coverage)