---
nav: wcp_docs
parent_url: /wcp_docs/
title: Workday REST API Fundamentals
layout: subsection
---

## <a id="overview"></a>Overview

The Workday REST APIs present a simple, consistent view of Workday business objects and the relationships between them. They are designed for small, self-service transactions initiated by end-users where a quick return of a small set of information is required. The REST APIs utilize the JSON format for all request and response data.

To see the API documentation of all Workday REST services and to try the REST APIs, go to the [REST API Explorer](https://developer.workday.com/rest-api-explorer).

## <a id="base_path"></a>Base Path

The base path for a REST API varies based on the application type:

-   <b>Extend and Orchestrate for Integrations</b>: The URL uses the API Gateway base path:

    ```
    https://{apiGatewayBasePath}/{serviceName}/{version}
    ```

    -   <b>{apiGatewayBasePath}</b>: The region-based API Gateway base path. See [Reference: Workday Extend API Gateways and Authorization Base URLs](/wcp_docs/dlh1653340161856.html).
    -   <b>{serviceName}</b>: The name of the Workday REST service.
    -   <b>{version}</b>: The version of the web service.

    Sample full URL for GET /workers: `https://api.us.wcp.workday.com/staffing/v7/workers`.

-   <b>Integrations</b>: The URL uses the tenant host base path:

    ```
    https://{tenantHostname}/api/{serviceName}/{version}/{tenant}
    ```

    -   <b>{tenantHostname}</b>: The hostname of the Workday REST web service.
    -   <b>{serviceName}</b>: The name of the Workday REST service.
    -   <b>{version}</b>: The version of the web service.
    -   <b>{tenant}</b>: The name of your tenant.

    Sample full URL for GET /workers: `https://tenant1.myworkday.com/api/staffing/v7/gms/workers`.



## <a id="versioning"></a>Versioning

Each Workday REST service has its own version. The REST API Explorer lists the latest full-use versions under <b>Production Services</b>. The <b>Experimental Services</b> section in the REST API Explorer lists the versions with labs, alpha, and beta designations. Note that the experimental services are for evaluation purposes only in Extend and Orchestrate. Don't use experimental services in production apps because these APIs will change before progressing to their production version. See the [Availability Statuses](https://developer.workday.com/terms/availabilitystatuses).

## <a id="error_messages"></a>Error Messages

See [Reference: REST API Error Messages](/wcp_docs/GUID-6f06b090-c7b5-47cc-b929-d2a1f1116eef-enHYPHENus.html).

## <a id="resource_collections"></a>Resource Collections

REST API resources typically represent a collection of business objects returned in the `data[ ]` array with the `total` field containing the number of the returned objects. You can control the paging of these collections using optional query parameters:

-   `limit`: Specifies the maximum number of objects in a single response (Default: 20, Maximum: 100).
-   `offset`: Specifies the starting point within the collection (Default: 0).


Example: <i>GET /workers?limit=5&offset=99</i> returns 5 workers starting with the 100th worker.

## <a id="object_identifiers"></a>Object Identifiers

All business objects include a unique identifier in the <b>id</b> field. The pattern for requesting a specific object is: <i>/{businessObjects}/{id}</i>.

Supported identifier formats:

<table><thead><tr><th>{id}</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>Workday ID (WID)</td><td>A unique 32-character system identifier.</td><td>GET /workers/6dcb8106e8b74b5aabb1fc3ab8ef2b92</td></tr><tr><td>Reference ID</td><td>A unique alternative ID, which uses the format <i>Reference_ID=id</i>: <ul><li><i>Reference_ID</i> is a valid name. For the valid <i>Reference_ID</i> names supported by an API endpoint, see its {id} path parameter description.
</li><li><i>id</i> is the unique ID reference ID value.
</li></ul></td><td>GET /workers/Employee_ID=21005</td></tr><tr><td><code>me</code></td><td>Represents the current user.</td><td>GET /workers/me</td></tr></tbody></table><br/>

## <a id="section_1"></a>Sub-resources

Sub-Resources represent collections of objects in Workday associated with a particular instance of a resource. Example: the inbox tasks associated with a specific worker is accessed with this subresource:

```
GET /workers/{id}/inboxTasks
```

This resource accesses the inbox tasks of the worker with that ID. In the same way:

```
GET /supervisoryOrganizations/{id}/workers
```

accesses a collection of workers in a specific supervisory organization, and:

```
GET /workers/{id}/directReports
```

accesses a collection of workers that directly report to a specific worker (their manager).

Here are some examples of accessing the inbox tasks of a specific worker, using different types of IDs:

```
GET /workers/6dcb8106e8b74b5aabb1fc3ab8ef2b92/inboxTasks 
GET /workers/me/inboxTasks 
GET /workers/Employee_ID=21005/inboxTasks 
```

## <a id="response_body"></a>Response Body

The response body contains JSON data. A collection returns an array of objects; a single object response is a single JSON object. Objects always contain:

-   `descriptor`: A human-readable description of the object.
-   `id`: The Workday ID of the object.
-   `href`: A URL representing the object.


When you work with the returned values in the response body:

-   If a field value is empty, the name/value pair is not included in the response.
-   The order of the pairs might change, so don't depend on order to parse the values.
-   Service updates and later releases can contain additional fields.
-   There may be additional fields in a single-object response that do not appear when the object is part of a collection.