--- 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: Batch Protocol REST API layout: subsection --- Batch Protocol provides a REST API endpoint that submits multiple REST API subrequests. ## Batch Protocol Endpoint ``` https://{tenantHostname}/batch/v1/{tenantName} ``` Example: `https://yourTenantHostName.com/batch/v1/gms` Note: The Batch Protocol REST API version is different from the version of the Workday REST APIs in the subrequests. The current Batch Protocol REST API version is `v1`. ## HTTP Method POST ## Request Body A JSON map containing the `batch[]` array. Each item in `batch[]` is a subrequest containing these request fields: - name Data type: string Required: Yes for referential dependencies and debugging with `continueOnFailure`. Description: Identifies the subrequest. Specify a unique double-quoted string, which can contain alphanumeric characters, underscores, and dashes. Can contain referential dependencies: No Examples: ``` "request_1" "create-employee" "allWorkers" ``` - method Data type: string Required: Yes Description: The HTTP method. Possible values: - GET - POST - PUT - PATCH - DELETE Can contain referential dependencies: No - relativeUri Data type: string Required: Yes Description: The relative path of a Workday REST API endpoint. Begin the path with a valid REST service name and version, followed by the resource path. The base path assumes the tenant base path of the Batch Protocol endpoint. Note that Batch Protocol: - Doesn't support bulk updates in a subrequest. You can't specify the query parameter `bulk=true`. - Requires URL encoding for special characters and spaces. Example: If a subrequest calls the WQL REST API, all spaces in the `query` parameter must be encoded as `%20`. ``` "relativeUri": "wql/v1/data?query=SELECT%20workdayID%20FROM%20workersForHCMReporting%20(dataSourceFilter%20=%20allActiveWorkers)" ``` - Uses the same tenant specified in the base URL of the Batch Protocol REST API. Don’t include the tenant path parameter in `relativeUri`. Can contain referential dependencies: Yes in these path parameters:
Path ParameterExample
Resource ID"recruiting/v3/prospects/{create-employee:$.id}"
Subresource ID"recruiting/v3/prospects/4ab154d8cbc10180394c7031a5205001/experiences/{employee-experience:$.id}"
Reference ID value

"recruiting/v3/prospects/COMPANY_ID=Company_{create-employee:$.companyId}"

"recruiting/v3/prospects/{get-worker:$.id}"

Query parameter value"staffing/v6/workers?search={create-employee:$.firstName} {create-employee:$.lastName}"

Note: The reference ID and query parameter values can mix regular text and multiple referential dependencies. However, the resource and subresource IDs can only accept a single referential dependency.  - continueOnFailure Data type: boolean Required: No Description: If true, Batch Protocol continues processing when this subrequest encounters an error. For more information, see Continuing Batch Processing on Failure in [Concept: Batch Protocol for Workday REST APIs](/wcp_docs/GUID-52feabc4-6c3e-4cd4-a4bc-cf58a5bdfab7-enHYPHENus.html). Default: false Can contain referential dependencies: No - defaultVars Data type: JSON object Required: No Description: Defines variables for default values in referential dependencies. Define `defaultVars` for referential dependencies in the same subrequest. For more information, see Default Variables in [Concept: Batch Protocol for Workday REST APIs](/wcp_docs/GUID-52feabc4-6c3e-4cd4-a4bc-cf58a5bdfab7-enHYPHENus.html). Can contain referential dependencies: No Examples: ``` { "defaultId": 0, "noName": "blank" } ``` - body Data type: JSON object Required: Yes for requests that require a request body. If the REST API requires an empty request body, specify `"body": {}`. Description: Contains the data for POST, PUT, and PATCH subrequests.  Can contain referential dependencies: Yes in field values. Field names can't contain referential dependencies. Examples: ``` { "name": "Joe Cool", "greeting": "Hello {get-employee:$.preferredName}!", "age": "{get-employee:$.age}" } ``` ## Response Codes - 200 Successful or partial response. The response data contains these fields: - `total` - The number of processed subrequests. - `data[]` - An array containing the response data for each subrequest. Each item in `data[]` contains these fields: - `name` - The subrequest name, if given. - `body` - The response data from the subrequest if the subrequest succeeded. Note: If the subrequest failed and the `continueOnFailure` flag is true, the `body` contains the error messages and error code. Always check for errors even if the status code is 200. - `status` - The HTTP status code from the subrequest. Example: ``` { "total": 3, "data": [ { "name": "create-prospect", "body": { "id": "6c742b78640290000b951cc4a6890000", "descriptor": "Jane Prospect", "candidate": { "id": "6c742b78640290000b951d5e311c0000", "descriptor": "Jane Prospect", "countryPhoneCode": { "descriptor": "United States of America (+1)", "id": "db8d3ca6446c11de98360015c5e6daf6" }, "email": "JaneProspect@acme.com", "name": { "id": "6c742b78640210000b951d5e311c0002", "descriptor": "Jane Prospect", "country": { "descriptor": "United States of America", "id": "bc33aa3152ec42d4995f4791a106ed09" }, "firstName": "Jane", "primary": "Prospect" }, "phoneNumber": "1200361755" }, "contactConsent": false }, "status": 201 }, { "name": "create-prospect-experience", "body": { "error": "invalid request: validation errors", "errors": [ { "error": "Enter a start year.", "code": "A258" } ] }, "status": 400 }, { "name": "create-prospect-skills", "body": { "id": "6c742b78640290000b9588a2cffe0000", "name": "Administration" }, "status": 201 } ] } ``` - 400 Invalid request. Possible causes: - The HTTP method used with the Batch Protocol REST API is invalid. Ensure that the HTTP method is `POST`. - Duplicate subrequest names in the batch request. - A subrequest with `"continueOnFailure": false` encountered one of these possible errors: - Invalid `relativeUri`. - Invalid request field name. - Nested referential dependency. - Invalid fields inside `body`. - Application validation error. - A referential dependency in a subrequest references a subrequest that has  `"continueOnFailure": true`. - 404 Not found. A subrequest with `"continueOnFailure": false` encountered one of these possible errors: - Incorrect `method`. - Invalid resource or subresource in the `relativeUri` field. - Other standard HTTP codes Batch Protocol can return other standard HTTP status codes, such as: - 408 - Timeout error. - 429 - Too many requests. - 500 - Server error. ### Related Information [Reference: Sample Batch Protocol Requests](/wcp_docs/GUID-b4c1e8f5-2313-41b1-9696-8bac93edbe61-enHYPHENus.html)