---
category: [Administration & Integrations, Administration & Integrations/Workday API, Platform and Product Extensions, Platform and Product Extensions/Integration]
nav: wcp_docs
parent_url: /wcp_docs/
title: >- 
  Reference: Workers
layout: subsection
---

## <a id="conref_common_service_urlBasePath"></a>URL Base Path

<b>Workday API Gateway Base Path</b>

For REST API calls in Workday Extend and Orchestrate for Integrations, use the regional API Gateway base URL for your account. See [Reference: Workday Extend API Gateways and Authorization Base URLs](https://developer.workday.com/documentation/dlh1653340161856) on the Developer Site. Note that the API Gateway base URL doesn’t include the tenant name.

<b>Tenant Base Path</b>

For traditional Integrations using tenanted REST APIs calls:

```
https://<hostname>/api/common/<version>/<tenant>
```

Example:

```
https://yourTenantHostName.com/api/common/v1/gms
```

## <a id="refsyn_N10019_N10016_N10001"></a>URI

Collection of workers:

```
/workers
```

<a id="refsyn_N1002F_N10016_N10001"></a>
Individual worker:

```
/workers/{id}
```

<b>URI Parameters</b>

<table><thead><tr><th>URI Parameter</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>Reference to the worker. Example: Worker WID. In place of an ID, you can use the word me for the current user.</td></tr></tbody></table><br/>

## <a id="section_N10066_N10016_N10001"></a>Description

Workers resource represents workers. You can only view the workers and worker information permitted by the security profile of the current user.

Workers supports this method:

-   [GET Workers](/wcp_docs/dan1370797991225.html#GET)


## <a id="GET"></a>GET Workers

-   <b>Secured by:</b>

    <i>Worker Data: Public Worker Reports</i> in the Staffing functional area.



No request body required or available for this method. When retrieving a collection, use these optional query parameters:

<table><thead><tr><th>Query Parameter</th><th>Description</th></tr></thead><tbody><tr><td>limit</td><td>Limit of object data entries included in a single response. The default is 20, and the maximum is 100.</td></tr><tr><td>offset</td><td>Offset to the first object in a collection to include in the response. The default is zero.</td></tr><tr><td>search</td><td>Search for workers by name only. Use at least 3 consecutive characters in the search text. The search is case-insensitive, and the search text only matches names that start with the search text.</td></tr><tr><td>view</td><td>View for the response body.</td></tr></tbody></table><br/>

The response body is in JSON format.

## <a id="section_N10103_N10016_N10001"></a>Views

Views for the GET Workers resource:

-   workerSummary - default view for GET /workers.
-   workerProfile - default view for GET /workers/{id}.
-   timeOffSummary - displays total time-off balances for a worker. Displays the total hourly balance for hourly plans, and/or the total daily balance for daily plans.


The table lists the JSON name/value pairs returned in the response body for the workerSummary and workerProfile views. Unless specified, the values are strings. The body doesn't include empty value pairs, pair orders can change, and Workday might introduce new pairs in patches between releases. Your application must respond to these changes.

<table><thead><tr><th>Name</th><th>workerSummary</th><th>workerProfile</th><th>Notes</th></tr></thead><tbody><tr><td>descriptor</td><td>X</td><td>X</td><td>Display name of the object. <p>Depending on the General Name Display Type on <b>Edit Tenant Setup - System</b>, the descriptor returns either the legal name, preferred name, or a concatenation of the legal and preferred names of the worker.</p></td></tr><tr><td>id</td><td>X</td><td>X</td><td>Workday object ID.</td></tr><tr><td>href</td><td>X</td><td>X</td><td>URL that represents the object.</td></tr><tr><td>businessTitle</td><td>X</td><td>X</td><td> </td></tr><tr><td>dateOfBirth</td><td> </td><td>X</td><td> </td></tr><tr><td>isManager</td><td>X</td><td>X</td><td>Boolean.</td></tr><tr><td>location</td><td> </td><td>X</td><td>Location object.</td></tr><tr><td>primarySupervisoryOrganization</td><td>X</td><td>X</td><td>Supervisory organization object.</td></tr><tr><td>primaryWorkAddressText</td><td> </td><td>X</td><td> </td></tr><tr><td>primaryWorkEmail</td><td>X</td><td>X</td><td> </td></tr><tr><td>primaryWorkPhone</td><td>X</td><td>X</td><td> </td></tr><tr><td>supervisoryOrganizationsManaged</td><td> </td><td>X</td><td>Supervisory organizations managed by the worker.</td></tr><tr><td>yearsOfService</td><td> </td><td>X</td><td> </td></tr></tbody></table><br/>

## <a id="section_N10258_N10016_N10001"></a>Search

The search query parameter searches the worker names for matches. The search is case-insensitive and only matches names that start with that text. Example: These searches return Logan McNeil:

```
/workers?search=log

/workers?search=mcneil

/workers?search=Mcne
```

But this search doesn’t:

```
/workers?search=ogan
```

A hyphen represents a space for name searches. This search returns Juan-Carlos Salazar Jimenez:

```
/workers?search=carlos
```

You can also include multiple search texts. The results are ORed together. This search result includes Betty Liu and Logan McNeil:

```
/workers?search=logan liu
```

## <a id="section_N1029E_N10016_N10001"></a>GET Workers Examples

This GET request retrieves all the workers available to the current user:

```
GET /workers
```

The response is a collection of workers, in JSON format (only 2 workers in the response):

```
{
  "total": 303,
  "data":    [
           {
        "descriptor": "Abby Brennan [C]",
        "id": "6dcb8106e8b74b5aabb1fc3ab8ef2b92",
        "href": "https://{Workday REST API Endpoint}/workers/6dcb8106e8b74b5aabb1fc3ab8ef2b92",
        "primarySupervisoryOrganization":          {
           "descriptor": "Global Support - USA Group",
           "id": "dd2061e4fd644a95b4fe2df815462b6b",
           "href": "https://{Workday REST API Endpoint}/supervisoryOrganizations/dd2061e4fd644a95b4fe2df815462b6b"
        },
        "businessTitle": "Senior Customer Services Representative",
        "primaryWorkEmail": "abrennan@gmail.com",
        "isManager": false,
        "primaryWorkPhone": "+1 (773) 721-9821"
     },
           {
        "descriptor": "Adam Carlton",
        "id": "1da8b422311b4929bfa4520f7f0b4e83",
        "href": "https://{Workday REST API Endpoint}/workers/1da8b422311b4929bfa4520f7f0b4e83",
        "primarySupervisoryOrganization":          {
           "descriptor": "Payroll Department",
           "id": "31fd8a267e4b4375aa8ff594033193cf",
           "href": "https://{Workday REST API Endpoint}/supervisoryOrganizations/31fd8a267e4b4375aa8ff594033193cf"
        },
        "businessTitle": "Staff Payroll Specialist",
        "primaryWorkEmail": "acarlton@workday.net",
        "isManager": false,
     },
    ...
]
}
 
```

This request retrieves 5 workers, starting with the 100th worker, available to the current user:

```
GET /workers?limit=5&offset=99
```

The response is a collection of workers, in JSON format (only 1 worker in the response):

```


   {
      "total": 303,
      "data":
      [
          {
              "descriptor": "Emma Hobson",
              "id": "19f7dabb79994d29931cd139df6272ed",
              "href": "https://{Workday REST API Endpoint}/workers/19f7dabb79994d29931cd139df6272ed",
              "primarySupervisoryOrganization":
              {
                  "descriptor": "Global Support - UK & Ireland Group",
                  "id": "7159687c81c24f91b0769772c4a6ac90",
                  "href": "https://{Workday REST API Endpoint}/supervisoryOrganizations/7159687c81c24f91b0769772c4a6ac90"
              },
              "businessTitle": "Customer Service Representative",
              "primaryWorkEmail": "ehobson@workday.net",
              "isManager": false,
          },
        ...
      ]
   }


 
```

This request retrieves the workers whose names (first, last, or middle) start with carl, available to the current user:

```
GET /workers?search=carl
```

The response is a collection of 4 workers, in JSON format:

```


   {
      "total": 4,
      "data":
      [
          {
              "descriptor": "Adam Carlton",
              "id": "1da8b422311b4929bfa4520f7f0b4e83",
              "href": "https://{Workday REST API Endpoint}/workers/1da8b422311b4929bfa4520f7f0b4e83",
              "primarySupervisoryOrganization":
              {
                  "descriptor": "Payroll Department",
                  "id": "31fd8a267e4b4375aa8ff594033193cf",
                  "href": "https://{Workday REST API Endpoint}/supervisoryOrganizations/31fd8a267e4b4375aa8ff594033193cf"
              },
              "businessTitle": "Staff Payroll Specialist",
              "primaryWorkEmail": "acarlton@workday.net",
              "isManager": false,
          },
          {
              "descriptor": "Carlos Alves",
              "id": "18294789b9d0415b9003267724265acc",
              "href": "https://{Workday REST API Endpoint}/workers/18294789b9d0415b9003267724265acc",
              "primarySupervisoryOrganization":
              {
                  "descriptor": "Sales",
                  "id": "50577df7ae5c4292a969e8a64c8650ed",
                  "href": "https://{Workday REST API Endpoint}/supervisoryOrganizations/50577df7ae5c4292a969e8a64c8650ed"
              },
              "businessTitle": "Director, Field Sales LATAM",
              "primaryWorkEmail": "calves@workday.net",
              "isManager": true,
          },
          {
              "descriptor": "Gwen Carlisle",
              "id": "c66430f9a4fc4416b1fef1785f3a6ae5",
              "href": "https://{Workday REST API Endpoint}/workers/c66430f9a4fc4416b1fef1785f3a6ae5",
              "primarySupervisoryOrganization":
              {
                  "descriptor": "Planning & Analysis Department",
                  "id": "64a64b71dcec4ecca7c5ff134c8697ce",
                  "href": "https://{Workday REST API Endpoint}/supervisoryOrganizations/64a64b71dcec4ecca7c5ff134c8697ce"
              },
              "businessTitle": "Regional Finance Manager",
              "primaryWorkEmail": "gcarlisle@workday.net",
              "isManager": false,
              "primaryWorkPhone": "+44 (020) 7881-9844"
          },
          {
              "descriptor": "Juan-Carlos Salazar Jimenez",
              "id": "8e1d0a3b6df04f42926648669df7d447",
              "href": "https://{Workday REST API Endpoint}/workers/8e1d0a3b6df04f42926648669df7d447",
              "primarySupervisoryOrganization":
              {
                  "descriptor": "Consulting Services",
                  "id": "97159ecbf62d49a4936f85c338e886d2",
                  "href": "https://{Workday REST API Endpoint}/supervisoryOrganizations/97159ecbf62d49a4936f85c338e886d2"
              },
              "businessTitle": "Director, Consulting Services - LATAM",
              "primaryWorkEmail": "jsalazar@workday.net",
              "isManager": true,
          }
      ]
   }



 
```

This request retrieves information about Logan McNeil (id=66faa65677834f0a9b586dd5645e9004).

```
GET /workers/66faa65677834f0a9b586dd5645e9004
```

The worker in the response body contains additional information, compared with the previous body that contains a collection of workers:

```
{
  "descriptor": "Logan McNeil",
  "id": "66faa65677834f0a9b586dd5645e9004",
  "href": "https://{Workday REST API Endpoint}/workers/66faa65677834f0a9b586dd5645e9004",
  "dateOfBirth": "1972-05-25",
  "businessTitle": "Chief Human Resources Officer",
  "supervisoryOrganizationsManaged": "https://{Workday REST API Endpoint}/workers/66faa65677834f0a9b586dd5645e9004/supervisoryOrganizationsManaged",
  "isManager": true,
  "location":    {
     "descriptor": "San Francisco",
     "id": "6cb76d060ed24d0993b64558ed8ce550"
  },
  "primarySupervisoryOrganization":    {
     "descriptor": "Executive Management",
     "id": "d79004d00fa5481ba4b941aaa9cfc78e",
     "href": "https://{Workday REST API Endpoint}/supervisoryOrganizations/d79004d00fa5481ba4b941aaa9cfc78e"
  },
  "primaryWorkAddressText": "3939 The Embarcadero, San Francisco, CA 94111",
  "yearsOfService": "13"
}
      
```

This request retrieves information about Adam Carlton (id=1da8b422311b4929bfa4520f7f0b4e83), but instead of the default view, it uses the workerSummary view:

```
GET /workers/1da8b422311b4929bfa4520f7f0b4e83?view=workerSummary
```

The worker in this response body contains the same information returned by default for collections of workers:

```
{
   "descriptor": "Adam Carlton",
   "id": "1da8b422311b4929bfa4520f7f0b4e83",
   "href": "https://{Workday REST API Endpoint}/workers/1da8b422311b4929bfa4520f7f0b4e83",
   "primarySupervisoryOrganization": {
       "descriptor": "Payroll Department",
       "id": "31fd8a267e4b4375aa8ff594033193cf",
       "href": "https://{Workday REST API Endpoint}/supervisoryOrganizations/31fd8a267e4b4375aa8ff594033193cf"
   },
   "businessTitle": "Staff Payroll Specialist",
   "primaryWorkEmail": "acarlton@workday.net",
   "isManager": false
}
      
```

This request retrieves information about Logan McNeil's time-off balance (id=66faa65677834f0a9b586dd5645e9004), using the timeOffSummary view:

```
GET /workers/66faa65677834f0a9b586dd5645e9004?view=timeOffSummary
```

The result displays Logan McNeil and their time-off balance:

```
{
  "descriptor": "Logan McNeil",
  "id": "66faa65677834f0a9b586dd5645e9004",
  "href": "https://{Workday REST API Endpoint}/workers/66faa65677834f0a9b586dd5645e9004",
  "totalHourlyBalance": "184"
}
```

This request retrieves all the workers available to the current user and their time-off balances, using the timeOffSummary view:

```
GET /workers/?view=timeOffSummary
```

The result is a collection of workers with their time-off balances (only 2 workers in the response):

```
{
  "total": 130,
  "data":    [
           {
        "descriptor": "Abby Brennan [C]",
        "id": "6dcb8106e8b74b5aabb1fc3ab8ef2b92",
        "href": "https://{Workday REST API Endpoint}/workers/6dcb8106e8b74b5aabb1fc3ab8ef2b92",
        "totalHourlyBalance": "144"
     },
           {
        "descriptor": "Adam Carlton",
        "id": "1da8b422311b4929bfa4520f7f0b4e831",
        "href": "https://{Workday REST API Endpoint}/workers/1da8b422311b4929bfa4520f7f0b4e831",
        "totalHourlyBalance": "184"
     },
    ...
]
}
    
```