---
category: [Administration & Integrations, Administration & Integrations/Workday API, Platform and Product Extensions, Platform and Product Extensions/Integration]
keyword: [Extend, Integrate, REST API]
nav: wcp_docs
parent_url: /wcp_docs/
title: >- 
  Concept: REST Metadata API Header
layout: subsection
---

The Metadata API `wd-metadata-api-version` header for Workday REST APIs enables you to retrieve metadata information about the REST API request and response. To retrieve the REST API metadata information, specify this HTTP header in your request:

```
wd-metadata-api-version: {version}
```

`{version}` is the header value that specifies the version of the REST Metadata API to use. It isn't the version of the requested REST web service. Specify the {version} value:

<table><thead><tr><th>Value</th><th>Description</th></tr></thead><tbody><tr><td>v1</td><td>Returns metadata in OpenAPI 2.0 format. The response contains schema definitions in a <code>definitions</code> block and returns a single default representation for the requested operation.</td></tr><tr><td>v2</td><td>Returns metadata in OpenAPI 3.0.1 format as a complete OpenAPI document. The response includes these top-level elements: <ul><li>openapi
</li><li>info
</li><li>servers
</li><li>paths
</li><li>components
</li></ul> The POST, PUT, and PATCH operations return separate request and response schema representations.</td></tr></tbody></table><br/>

<b>Note:</b> The header value isn't the version of the requested REST web service.

## <a id="section_zyn_yqd_l4b"></a>Security

The REST Metadata API uses the same security access model as the standard REST APIs. If the user has the appropriate security privileges to call an API without the header, the same privileges enable the user to call that API with the `wd-metadata-api-version` header.

## <a id="section_dnv_crd_l4b"></a>Metadata Response

When you specify the `wd-metadata-api-version` header, the request returns the metadata instead of the data from your tenant. The metadata uses the standard Javascript Object Notation (JSON) format.

The metadata enables you to discern the API response fields based on the configured conditions or the security permissions of the current user. The metadata contains information related to display options, textual data, and data types.

Display options include:

<table><thead><tr><th>Field Attribute</th><th>Description</th></tr></thead><tbody><tr><td>required</td><td>A standard request must specify the field.</td></tr><tr><td>readOnly</td><td>A POST, PUT, or PATCH method can't update the field.</td></tr><tr><td>hidden</td><td>The field is contextual depending on what type of object you're calling, related object conditions, or security configuration. <p>Example: A standard REST response can hide a field if the current user lacks permission to view the field. If the current user lacks security permission, the metadata returns the field with <code>"hidden":"true"</code> (for v1) or <code>"x-hidden":"true"</code> (for v2). If the current user can view the field, the <code>hidden</code> (or <code>x-hidden</code>) field in the metadata returns false.</p></td></tr></tbody></table><br/>

Textual data:

-   Labels
-   Help text
-   Name


Field data types:

<table><thead><tr><th>Data Type</th><th>Included Information</th></tr></thead><tbody><tr><td>Array</td><td>Nonsingular instance.</td></tr><tr><td>Boolean</td><td>Indicates that the field is a boolean.</td></tr><tr><td>Integer</td><td>Multiple of, maximum, minimum.</td></tr><tr><td>Number</td><td>Multiple of, maximum, minimum.</td></tr><tr><td>Object</td><td>Single instance.</td></tr><tr><td>String</td><td>Maximum length.</td></tr><tr><td>String (date)</td><td>Date format and precision.</td></tr></tbody></table><br/>

The metadata response is dynamic. If the required attribute of a field has changed, Workday reflects the change in the metadata response. Similarly, the Metadata API reflects changes based on the security configuration of the user.

## <a id="section_xfg_krd_l4b"></a>Guidelines and Limitations

Consider these guidelines and limitations:

-   For an array data type, the metadata specifies `items` and a reference to the schema definition of an array item. This specification is standard JSON schema specification. Example:

    ```
    "items": {
       "$ref": "#/definitions/jobPostingAnchorSummary"
    }
    ```

    For the v1 version, the `definition` section of the metadata includes the referenced schema definitions. Example `items` reference:

    ```
    "items": {
       "$ref": "#/definitions/jobPostingAnchorSummary"
    }
     
    ```

    Example referenced schema in the `definition` section:

    ```
    "definitions": {
      "jobPostingAnchorSummary": {
        "additionalProperties": false,
        "properties": {
         "endDate": {
          "hidden": false,
          "label": "End Date",
          "readOnly": false,
          "format": "date",
          "precision": "YYYY-MM-DD",
          "type": "string"
         },
         "timeType": {
          "hidden": false,
          "label": "Full/Part-time",
          "readOnly": false,
          "$ref": "#/definitions/positionTimeTypeDetail"
       },
       . . .
    }
    
     
    ```

    For the v2 version, the `components/schemas` section contains the referenced schema definitions. Example `items` reference:

    ```
    "items": {
       "$ref": "#/components/schemas/jobPostingAnchorSummary"
    }
     
    ```

    Example referenced schema in the `components/schemas` section:

    ```
    "components": {
        "schemas": {
          "jobPostingAnchorSummary": {
            "additionalProperties": false,
            "properties": {
              "endDate": {
                "format": "date",
                "type": "string",
                "x-precision": "YYYY-MM-DD",
                "readOnly": false,
                "x-hidden": false,
                "x-label": "End Date"
              },
              "timeType": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/positionTimeTypeDetail"
                  }
                ],
                "readOnly": false,
                "x-hidden": false,
                "x-label": "Time Type"
              },
       . . .
    }
     
    ```

    Note that the `timeType` field in the `jobPostingAnchorSummary` schema also references another schema, `positionTimeTypeDetail`. The `definition` (for v1) and `components/schemas` (for v2) sections includes all referenced schemas in the metadata.

-   When you use the `wd-metadata-api-version` header with a POST, PUT, or PATCH request, specify a request body or an empty request body `{}`. If you specify a non-empty request body, the metadata includes information about the request fields.

-   You can't use the `wd-metadata-api-version` header with these requests:

    -   DELETE operations.
    -   Prompt endpoints. A prompt endpoint is a GET operation that returns Workday ID values for certain resources. Example: `GET /values/jobChangesGroup/jobs/` in the Staffing REST web service.
    -   Bulk operations. A bulk operation is an endpoint that specifies the `bulk=true` parameter. Example: `POST /requisitions/{ID}/requisitionLines?bulk=true` in the Procurement REST web service.
    -   Reports-as-a-Service requests.



## <a id="section_j1w_n53_pkb"></a>Example: v1

This sample request retrieves information about job postings:

```
GET /jobPostings
```

To retrieve the metadata of the job postings, specify the `wd-metadata-api-version` header. Example:

```
"header": [
   {
      "key": "wd-metadata-api-version",
      "value": "v1",
   }
]
```

This snippet shows the sample metadata response:

```
{
    "type": "object",
    "properties": {
        "total": {
            "hidden": false,
            "readOnly": true,
            "multipleOf": 1.0,
            "exclusiveMax": 2147483647,
            "exclusiveMin": 0,
            "type": "integer"
        },
        "data": {
            "hidden": false,
            "readOnly": true,
            "type": "array",
            "items": {
                "$ref": "#/definitions/jobPostingAnchorSummary"
            }
        }
    },
    "definitions": {
        "jobPostingAnchorSummary": {
            "additionalProperties": false,
            "properties": {
                "endDate": {
                    "hidden": false,
                    "label": "End Date",
                    "readOnly": false,
                    "format": "date",
                    "precision": "YYYY-MM-DD",
                    "type": "string"
                },
                "timeType": {
                    "hidden": false,
                    "label": "Full/Part-time",
                    "readOnly": false,
                    "$ref": "#/definitions/positionTimeTypeDetail"
                },
                "title": {
                    "hidden": false,
                    "label": "Job Posting Title",
                    "readOnly": false,
                    "type": "string"
                },
                "jobSite": {
                    "hidden": false,
                    "label": "Job Posting Site",
                    "readOnly": false,
                    "$ref": "#/definitions/jobPostingSiteDetail"
                },
                "url": {
                    "hidden": false,
                    "label": "External URL",
                    "readOnly": false,
                    "type": "string"
                },
                "jobDescription": {
                    "hidden": false,
                    "label": "~Job Description~",
                    "readOnly": false,
                    "type": "string"
                },
                "categories": {
                    "hidden": false,
                    "label": "Job Category",
                    "readOnly": false,
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/jobFamilyGroupDetail"
                    }
                },
                "id": {
                    "hidden": false,
                    "readOnly": true,
                    "type": "string"
                },
                "jobType": {
                    "hidden": false,
                    "label": "Job Type",
                    "readOnly": false,
                    "$ref": "#/definitions/positionWorkerTypeDetail"
                },
                "spotlightJob": {
                    "hidden": false,
                    "label": "~Spotlight Job~",
                    "readOnly": false,
                    "type": "boolean"
                },
                "startDate": {
                    "hidden": false,
                    "label": "Start Date",
                    "readOnly": false,
                    "format": "date",
                    "precision": "YYYY-MM-DD",
                    "type": "string"
                }
            },
            "type": "object"
        },
        "jobPostingSiteDetail": {
            "additionalProperties": false,
            "properties": {
                "id": {
                    "hidden": false,
                    "readOnly": true,
                    "type": "string"
                },
                "descriptor": {
                    "hidden": false,
                    "readOnly": true,
                    "type": "string"
                }
            },
            "type": "object"
        },
        "positionTimeTypeDetail": {
            "additionalProperties": false,
            "properties": {
                "id": {
                    "hidden": false,
                    "readOnly": true,
                    "type": "string"
                },
                "descriptor": {
                    "hidden": false,
                    "readOnly": true,
                    "type": "string"
                }
            },
            "type": "object"
        },
        "jobFamilyGroupDetail": {
            "additionalProperties": false,
            "properties": {
                "id": {
                    "hidden": false,
                    "readOnly": true,
                    "type": "string"
                },
                "descriptor": {
                    "hidden": false,
                    "readOnly": true,
                    "type": "string"
                }
            },
            "type": "object"
        },
        "positionWorkerTypeDetail": {
            "additionalProperties": false,
            "properties": {
                "id": {
                    "hidden": false,
                    "readOnly": true,
                    "type": "string"
                },
                "descriptor": {
                    "hidden": false,
                    "readOnly": true,
                    "type": "string"
                }
            },
            "type": "object"
        },
        . . .
    },
    "additionalProperties": false
}
```

## <a id="section_1"></a>Example: v2

This sample request retrieves information about job postings:

```
GET /jobPostings
```

To retrieve the metadata of the job postings, specify the `wd-metadata-api-version` header. Example:

```
"header": [
   {
      "key": "wd-metadata-api-version",
      "value": "v2",
   }
]
```

This snippet shows the sample metadata response:

```
{
  "openapi": "3.0.1",
  "info": {
    "title": "recruiting",
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://myhost.workday.com/api/recruiting/v1/gms"
    }
  ],
  "paths": {
    "/jobPostings": {
      "get": {
        "responses": {
          "200": {
            "description": "Default successful response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "properties": {
                    "total": {
                      "type": "integer",
                      "multipleOf": 1.0,
                      "maximum": 2147483647,
                      "exclusiveMaximum": true,
                      "minimum": 0,
                      "exclusiveMinimum": false,
                      "readOnly": true,
                      "x-hidden": false
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/jobPostingAnchorSummary"
                      },
                      "readOnly": true,
                      "x-hidden": false
                    }
                  },
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "jobPostingAnchorSummary": {
        "additionalProperties": false,
        "properties": {
          "candidateAvailabilityTemplateVersion": {
            "additionalProperties": false,
            "properties": {
              "descriptor": {
                "type": "string",
                "readOnly": true,
                "x-hidden": false
              },
              "id": {
                "type": "string",
                "readOnly": true,
                "x-hidden": false
              },
              "href": {
                "type": "string",
                "readOnly": true,
                "x-hidden": false
              }
            },
            "type": "object",
            "readOnly": false,
            "x-hidden": false,
            "x-label": "Candidate Availability Template Version"
          },
          "endDate": {
            "format": "date",
            "type": "string",
            "x-precision": "YYYY-MM-DD",
            "readOnly": false,
            "x-hidden": false,
            "x-label": "End Date"
          },
          "timeType": {
            "allOf": [
              {
                "$ref": "#/components/schemas/positionTimeTypeDetail"
              }
            ],
            "readOnly": false,
            "x-hidden": false,
            "x-label": "Time Type"
          },
          "title": {
            "type": "string",
            "readOnly": false,
            "x-hidden": false,
            "x-label": "Job Posting Title"
          },
          "url": {
            "type": "string",
            "readOnly": false,
            "x-hidden": false,
            "x-label": "External URL"
          },
          "jobSite": {
            "allOf": [
              {
                "$ref": "#/components/schemas/jobPostingSiteDetail"
              }
            ],
            "readOnly": false,
            "x-hidden": false,
            "x-label": "Job Posting Site"
          },
          "jobDescription": {
            "type": "string",
            "readOnly": false,
            "x-hidden": false,
            "x-label": "~Job Description~"
          },
          "id": {
            "type": "string",
            "readOnly": true,
            "x-hidden": false
          },
          "categories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/jobFamilyGroupDetail"
            },
            "readOnly": false,
            "x-hidden": false,
            "x-label": "Job Category"
          },
          "spotlightJob": {
            "type": "boolean",
            "readOnly": false,
            "x-hidden": false,
            "x-label": "~Spotlight Job~"
          },
          "jobType": {
            "allOf": [
              {
                "$ref": "#/components/schemas/positionWorkerTypeDetail"
              }
            ],
            "readOnly": false,
            "x-hidden": false,
            "x-label": "Job Type"
          },
          "startDate": {
            "format": "date",
            "type": "string",
            "x-precision": "YYYY-MM-DD",
            "readOnly": false,
            "x-hidden": false,
            "x-label": "Start Date"
          }
        },
        "type": "object"
      },
      "positionTimeTypeDetail": {
        "additionalProperties": false,
        "properties": {
          "descriptor": {
            "type": "string",
            "readOnly": true,
            "x-hidden": false
          },
          "id": {
            "type": "string",
            "readOnly": true,
            "x-hidden": false
          }
        },
        "type": "object"
      },
      "jobPostingSiteDetail": {
        "additionalProperties": false,
        "properties": {
          "descriptor": {
            "type": "string",
            "readOnly": true,
            "x-hidden": false
          },
          "id": {
            "type": "string",
            "readOnly": true,
            "x-hidden": false
          }
        },
        "type": "object"
      },
      "positionWorkerTypeDetail": {
        "additionalProperties": false,
        "properties": {
          "descriptor": {
            "type": "string",
            "readOnly": true,
            "x-hidden": false
          },
          "id": {
            "type": "string",
            "readOnly": true,
            "x-hidden": false
          }
        },
        "type": "object"
      },
      "jobFamilyGroupDetail": {
        "additionalProperties": false,
        "properties": {
          "descriptor": {
            "type": "string",
            "readOnly": true,
            "x-hidden": false
          },
          "id": {
            "type": "string",
            "readOnly": true,
            "x-hidden": false
          }
        },
        "type": "object"
      },
      . . .
    }
  }
}
 
```

This next v2 example retrieves the metadata for a POST request:

```
POST /workers/ad3b6e21b21b100301e6c888e90816da/jobChanges
```

To retrieve the metadata of the job postings, specify the `wd-metadata-api-version` header. Example:

```
"header": [
   {
      "key": "wd-metadata-api-version",
      "value": "v2",
   }
]
 
```

Request body:

```
{}
```

This snippet shows the sample metadata response:

```
{
  "openapi": "3.0.1",
  "info": {
    "title": "staffing",
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://myhost.workday.com/api/staffing/v1/gms"
    }
  ],
  "paths": {
    "/workers/ad3b6e21b21b100301e6c888e90816da/jobChanges": {
      "post": {
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/jobChangesStartDetailsPOSTData"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Default successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/jobChangesStartDetailsPOSTData"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "jobChangesStartDetailsPOSTData": {
        "required": [
          "date",
          "reason"
        ],
        "additionalProperties": false,
        "properties": {
          "date": {
            "format": "date",
            "type": "string",
            "x-precision": "YYYY-MM-DD",
            "readOnly": false,
            "x-hidden": false,
            "x-label": "Effective Date"
          },
          "reason": {
            "additionalProperties": false,
            "properties": {
              "descriptor": {
                "type": "string",
                "readOnly": true,
                "x-hidden": false
              },
              "id": {
                "type": "string",
                "readOnly": true,
                "x-hidden": false
              },
              "href": {
                "type": "string",
                "readOnly": true,
                "x-hidden": false
              }
            },
            "type": "object",
            "readOnly": false,
            "x-hidden": false,
            "x-label": "Business Process Reason"
          },
          "supervisoryOrganization": {
            "additionalProperties": false,
            "properties": {
              "descriptor": {
                "type": "string",
                "readOnly": true,
                "x-hidden": false
              },
              "id": {
                "type": "string",
                "readOnly": true,
                "x-hidden": false
              },
              "href": {
                "type": "string",
                "readOnly": true,
                "x-hidden": false
              }
            },
            "type": "object",
            "readOnly": false,
            "x-hidden": false,
            "x-label": "~Supervisory Organization~ - Proposed (REST)"
          },
          "location": {
            "additionalProperties": false,
            "properties": {
              "descriptor": {
                "type": "string",
                "readOnly": true,
                "x-hidden": false
              },
              "id": {
                "type": "string",
                "readOnly": true,
                "x-hidden": false
              },
              "href": {
                "type": "string",
                "readOnly": true,
                "x-hidden": false
              }
            },
            "type": "object",
            "readOnly": false,
            "x-hidden": false,
            "x-label": "Location - Proposed (REST)"
          },
          "descriptor": {
            "type": "string",
            "readOnly": true,
            "x-hidden": false
          },
          "id": {
            "type": "string",
            "readOnly": true,
            "x-hidden": false
          },
          "job": {
            "additionalProperties": false,
            "properties": {
              "descriptor": {
                "type": "string",
                "readOnly": true,
                "x-hidden": false
              },
              "id": {
                "type": "string",
                "readOnly": true,
                "x-hidden": false
              },
              "href": {
                "type": "string",
                "readOnly": true,
                "x-hidden": false
              }
            },
            "type": "object",
            "readOnly": false,
            "x-hidden": false,
            "x-label": "Position - Current (REST)"
          }
        },
        "type": "object"
      }
    }
  }
}
 
```

### Related Information

[FAQ: REST Metadata API](/wcp_docs/eyc1645578208431.html)