--- category: [Administration & Integrations, Administration & Integrations/Workday API, Platform and Product Extensions, Platform and Product Extensions/Integration, Administration & Integrations/Custom Integrations & Apps, Platform and Product Extensions/Workday Extend] nav: wcp_docs parent_url: /wcp_docs/ title: Custom Object (Multi-Instance) REST APIs layout: subsection --- This topic provides an overview and usage guidance on the Custom Object (Multi-Instance) REST APIs. ## Overview Custom objects are extensions of existing Workday business objects, and enable your enterprise to store custom data related to the business objects. Your integrations or apps can call the Custom Object REST APIs to get, create, update, and delete custom object data. A multi-instance custom object is a collection of custom object instances attached to a Workday business object. In Workday, users can view or edit a custom object table on the Additional Data tab of the business object. Example: The Worker object can associate a custom object named Stock Grants. Because a worker can have more than 1 stock grant, the Stock Grants custom object is a multi-instance custom object. When you or administrators create a custom object definition in Workday, certain configuration settings affect how you must specify the Custom Object REST API requests. This table summarizes how custom object settings affect the REST APIs:
Custom Object SettingCustom Object REST API Implication
Web Service AliasDetermines the root resource name of the REST API endpoints that access the custom object data.
Allow Multiple Instances per ObjectIf true, the custom object is multi-instance. For GET, PUT, and DELETE endpoints, the ID path parameter is a compound ID consisting of the business object ID and custom object Reference ID.
Reference IDEnables an easy way to identify custom objects in a GET, PUT, or DELETE request.

Note: Workday strongly recommends the use of Reference IDs with multi-instance custom objects. If you don't use Reference IDs, the custom object WIDs aren't easily available, which makes it difficult to identify a custom object instance.


Note: The Custom Object REST APIs don't support effective-dated custom objects. To update an effective-dated custom object, use the equivalent SOAP web service operation on the business object additional data. For reference documentation about the Custom Object (Multi-Instance) REST APIs, see the Custom Object Data (Multi-Instance) service in the [REST API Explorer on the Developer Site](https://developer.workday.com/rest-api-explorer) or [Workday REST Services Directory](https://community.workday.com/sites/default/files/file-hosting/restapi/index.html). ## Security Considerations When creating a custom object definition, you can assign Workday-defined and custom domains to the custom object. The configured security policies on the custom object determine the required REST API permissions on the custom object data. To view the security domains for a custom object, access the View Custom Object report. For integrations that call the Custom Object (Single-Instance) REST APIs, ensure that you have the correct scopes when you Register API Clients for Integrations. ## URL Base Path Workday API Gateway Base Path 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. Sample Workday Extend request URL (US region) for the `GET /customObjects/{customObjectAlias}/{customObjectID}` endpoint: ``` https://api.workday.com/customObjects/v2/stockGrants/Employee_ID=21001;grantName=New_Hire ``` Sample Workday Extend request URL (US region) for the `GET /{businessObjectResource}/{businessObjectID}/customObjects/{customObjectAlias}` endpoint: ``` https://api.workday.com/customObjects/v2/workers/Employee=21001/customObjects/stockGrants ``` Tenant Base Path For traditional Integrations using tenanted REST APIs calls: ``` https:///api/customObject// ``` Example: ``` https://yourTenantHostName.com/api/customObject/v1/gms ``` Note: The legacy `v1` version uses the base path format `https://yourTenantHostName.com/api/v1/yourTenant`. Starting with `v2`, the Custom Object REST service uses the base path format `https://yourTenantHostName.com/api/customObject/version/yourTenant` (where `version` is the current version.) ## Constructing the Request URL For the GET, PUT, and DELETE endpoints that operate on a specific instance of a multi-instance custom object, the request URL follows this format: ``` {basePath}/customObjects/{customObjectAlias}/{customObjectID} ``` Where: - {basePath} The tenant host, service version, and tenant name. ``` https://yourTenantHostName.com/api/customObject/{version}/yourTenant ``` Note: The legacy `v1` version uses the base path format `https://yourTenantHostName.com/api/v1/yourTenant`. - customObjects The Custom Objects service name, which is `customObjects`. - {customObjectAlias} The web service alias of the custom object. Example: `stockGrants` is the web service alias of the sample Stock Grants, which is a multi-instance custom object. To determine the web service alias of the custom object, access the View Custom Object task. - {customObjectID} A compound ID containing the business object ID and custom object Reference ID, separated by a semicolon (`;`). The business object ID can be the Workday ID or the Reference ID of the extended business object. A compound ID uses this format: ``` {businessObjectID};{referenceId}={referenceIdValue} ``` This sample compound ID uses the `Employee_ID` Reference ID of the business object and the `grantName` Reference ID of the custom object: ``` Employee_ID=21001;grantName=New_Hire ``` Note: The Reference ID of the multi-instance custom object is a setting in the custom object definition. If the custom object doesn't have a Reference ID, you can use the Workday ID of the custom object instance. The GET endpoint that returns the collection of custom object instances for the business object includes the Workday ID of the custom objects. These sample request URLs are for a GET endpoint that retrieves a specific Stock Grant for a specific worker. The web service alias of the Stock Grants custom object is stockGrants. Each example is a variation of the compound ID, which uses: - The Reference ID of the business object and custom object. v2 example: ``` https://account.tenant.com/api/customObject/v2/gms/customObjects/stockGrants/Employee_ID=21001;grantName=New_Hire ``` v1 example: ``` https://account.tenant.com/api/v1/gms/customObjects/stockGrants/Employee_ID=21001;grantName=New_Hire ``` - The Workday ID of the business object and the Reference ID of the custom object. v2 example: ``` https://account.tenant.com/api/customObject/v2/gms/customObjects/stockGrants/3aa5550b7fe348b98d7b5741afc65534;grantName=New_Hire ``` v1 example: ``` https://account.tenant.com/api/v1/gms/customObjects/stockGrants/3aa5550b7fe348b98d7b5741afc65534;grantName=New_Hire ``` - The Workday IDs of the business object and the custom object. v2 example: ``` https://account.tenant.com/api/customObject/v2/gms/customObjects/stockGrants/3aa5550b7fe348b98d7b5741afc65534;da117f20c8d7300026b797fd5f7b2541 ``` v1 example: ``` https://account.tenant.com/api/v1/gms/customObjects/stockGrants/3aa5550b7fe348b98d7b5741afc65534;da117f20c8d7300026b797fd5f7b2541 ``` The Custom Object (Multi-Instance) REST APIs include an additional GET endpoint whose root resource is the business object. This additional GET endpoint retrieves a collection of custom object instances for a specific business object, and the request URL follows this format: ``` {basePath}/{businessObjectResource}/{businessObjectId}/customObjects/{customObjectAlias} ``` Where: - {basePath} The tenant host, service version, and tenant name. ``` https://yourTenantHostName.com/api/customObject/version/yourTenant ``` Note: The legacy `v1` version uses the base path format `https://yourTenantHostName.com/api/v1/yourTenant`. - {businessObjectResource} The resource name of the extended Workday business object associated with the multi-instance custom object. Example: `workers` See the resource names in [Reference: Workday Object Resource Names and Object Keys](/wcp_docs/uvm1621884333680.html). - {businessObjectId} The Workday ID or Reference ID of the extended business object. Example: `Employee=21001` - customObjects The Custom Objects service name, which is `customObjects`. - {customObjectAlias} The web service alias of the custom object. Example: `stockGrants` To determine the web service alias of the custom object, access the View Custom Object task. This sample request URL is for a GET collection endpoint that retrieves all Stock Grant instances for a specific worker. v2 example: ``` https://account.tenant.com/api/customObject/v2/gms/workers/Employee=21001/customObjects/stockGrants ``` v1 example: ``` https://account.tenant.com/api/v1/gms/workers/Employee=21001/customObjects/stockGrants ``` ## Constructing the Request Body When you create or update custom object data with a POST or PUT endpoint, specify the required or optional custom fields in the request body. To determine the custom fields, you can use the response data model from the `GET /customObjects/{customObjectAlias}/{customObjectID}` endpoint on an existing custom object instance. You can also see the custom object definition in the View Custom Object task. Ensure that you specify the correct data type of the custom field: - Text Specify a quoted string. - Integer Specify an unquoted numeric value. - Boolean Specify an unquoted `true` or `false`. - Date Specify the `yyyy-mm-dd` date format. Example: ``` "grantDate": "2021-05-19" ``` - Currency Specify the currency as an object map containing the `currency` and `value` fields. Example: ``` "strikePrice": { "currency": "USD", "value": "170.50" } ``` - Single-instance custom list Specify the single-instance custom list as an object map. The `id` field in the object map specifies the list value. Use the web service alias of the list value, as defined in the custom list definition. Example: ``` "typeOfShares": { "id": "iso" } ``` - Multi-instance custom list Specify the multi-instance custom list as an array of object maps. The `id` field in each object map specifies the list value. Use the web service alias of the list value, as defined in the custom list definition. Example: ``` "stockAllocations": [ { "id": "psu" }, { "id": "rsu" } ] ``` Note: Ensure that the request body doesn't contain inactive custom list values. A request body that contains an inactive custom list value causes an error. To inactivate and reactivate a custom list value, access the Edit Custom List task. When you create custom object data with a POST endpoint, the request body must also contain the business object attached to the custom object. Specify an object map containing the Workday ID or Reference ID of the existing business object. The object key is the name that corresponds to the Workday object. For a list of valid object keys corresponding to the supported Workday objects, see the object keys in [Reference: Workday Object Resource Names and Object Keys](/wcp_docs/uvm1621884333680.html). This sample object map in the request body identifies a Worker business object. To attach the new custom object instance to the Worker, specify `worker` as the key of the object map. ``` "worker": { "id": "Employee_ID=21035" } ``` Validate-only requests When you set the HTTP header`x-validate-only` to 1, the Custom Object REST API only validates the request and doesn't persist data in the tenant. The `x-validate-only` header applies to the POST, PUT, DELETE endpoints. ## Creating a Custom Object Instance Creating a multi-instance custom object adds a row to the custom object table in Workday. To create a multi-instance custom object, use this endpoint: ``` POST /customObjects/{customObjectAlias} ``` To submit the endpoint, specify: - The `{customObjectAlias}` path parameter using the web service alias of the custom object. - Optionally, the `updateIfExists=true` query parameter to update the existing instance. The POST endpoint updates only the fields that you specify in the request body. Note that if you specify the `updateIfExists=true` query parameter, the business object in the request body must be the existing business object attached to the existing custom object. - In the request body: - The required object map containing the business object. - The required and optional custom field data. Sample request: Create a stock grant for the worker whose ID is Employee_ID=21035. ``` POST /customObjects/stockGrants ``` Request body: ``` { "worker": { "id": "Employee_ID=21035" }, "strikePrice": { "currency": "USD", "value": "170" }, "grantName": "Merit_Q22021", "numberOfShares": 1000, "typeOfShares": { "id": "iso" }, "grantDate": "2021-05-19" } ``` Sample response: ``` { "ok": "Created" } ``` ## Creating Custom Object Instances in Bulk Creating multi-instance custom objects in bulk adds multiple rows to the custom object table in a single request. You can create custom object instances for different business objects in the same request. To create a multi-instance custom object in bulk, use this endpoint: ``` POST /customObjects/{customObjectAlias}?bulk=true ``` To submit the endpoint, specify: - The `{customObjectAlias}` path parameter using the web service alias of the custom object. - The `bulk=true` query parameter. - Optionally, the `updateIfExists=true` query parameter to update the existing instance. The POST endpoint updates only the fields that you specify in the request body. Note that if you specify the `updateIfExists=true` query parameter, the business object in the request body must be the existing business object attached to the existing custom object. - In the request body, an array of custom object instances to create. The bulk request has a limit of 200 items. Example: `[{customObjectInstance1}, {customObjectInstance2}]` For each `{customObjectInstance}` in the array, specify: - The required object map containing the business object. - The required and optional custom field data. Sample request: Create a stock grant for 2 workers whose IDs are Employee_ID=21035 and a Workday ID, respectively. ``` POST /customObjects/stockGrants?bulk=true&updateIfExists=true ``` Request body: ``` [ { "typeOfShares": { "id": "rsu" }, "strikePrice": { "currency": "USD", "value": "24500" }, "grantName": "Merit_Q32020", "grantDate": "2021-09-15", "numberOfShares": 300, "worker": { "id": "Employee_ID=21035" } }, { "typeOfShares": { "id": "nqo" }, "strikePrice": { "currency": "USD", "value": "265" }, "grantName": "Merit_Q32020", "grantDate": "2021-09-15", "numberOfShares": 220, "worker": { "id": "989eafee6aa449679fe58caeead36b31" } } ] ``` Sample response: ``` { "ok": "OK" } ``` ## Retrieving a Custom Object Instance To retrieve an instance of a multi-instance custom object, use this endpoint: ``` GET /customObjects/{customObjectAlias}/{customObjectID} ``` To submit the endpoint, specify: - The `{customObjectAlias}` path parameter using the web service alias of the custom object. - The `{customObjectID}` path parameter using a compound ID that follows this format: ``` {businessObjectID};{customObjectReferenceId}={customObjectReferenceIdValue} ``` Sample request: Retrieve a specific stock grant for a specific worker. ``` GET /customObjects/stockGrants/Employee_ID=21035;grantName=Merit_Q12021 ``` Sample response: ``` { "id": "e960ff12fbf430002def34b5e6232ef2", "strikePrice": { "currency": "USD", "value": "167" }, "grantName": "Merit_Q12021", "numberOfShares": 100, "typeOfShares": { "id": "iso" }, "grantDate": "2021-03-19", "worker": { "id": "989eafee6aa449679fe58caeead36b31" } } ``` ## Retrieving a Custom Object Collection for a Business Object To retrieve all instances of a multi-instance custom object for a specific business object, use this endpoint: ``` GET /{businessObjectResource}/{businessObjectID}/customObjects/{customObjectAlias} ``` To submit the endpoint, specify: - The `{businessObjectResource}` path parameter using the resource name of the business object. - The `{businessObjectID}` path parameter using the Workday ID or Reference ID of the business object. - The `{customObjectAlias}` path parameter using the web service alias of the custom object. Sample request: Retrieve all stock grants for a specific worker: ``` GET /workers/Employee_ID=21035/customObjects/stockGrants ``` Sample response: ``` { "total": 3, "data": [ { "id": "e960ff12fbf430002e95089d1d722f90", "strikePrice": { "currency": "USD", "value": "170" }, "grantName": "Merit_Q32021", "numberOfShares": 1000, "typeOfShares": { "id": "iso" }, "grantDate": "2021-05-19", "worker": { "id": "989eafee6aa449679fe58caeead36b31" } }, { "id": "e960ff12fbf430002e829e6eb8cc2f8f", "strikePrice": { "currency": "USD", "value": "170" }, "grantName": "Merit_Q22021", "numberOfShares": 150, "typeOfShares": { "id": "iso" }, "grantDate": "2021-05-19", "worker": { "id": "989eafee6aa449679fe58caeead36b31" } }, { "id": "e960ff12fbf430002f2498d12ff02f92", "strikePrice": { "currency": "USD", "value": "24500" }, "grantName": "Merit_Q32020", "numberOfShares": 300, "typeOfShares": { "id": "rsu" }, "grantDate": "2021-09-15", "worker": { "id": "989eafee6aa449679fe58caeead36b31" } } ] } ``` ## Updating a Custom Object Instance To update an instance of a multi-instance custom object, use this endpoint: ``` PUT /customObjects/{customObjectAlias}/{customObjectID} ``` To submit the endpoint, specify: - The `{customObjectAlias}` path parameter using the web service alias of the custom object. - The `{customObjectID}` path parameter using a compound ID that follows this format: ``` {businessObjectID};{customObjectReferenceId}={customObjectReferenceIdValue} ``` - In the request body, specify the custom field data to update. Consider these guidelines: - Ensure that you specify the correct data type of the custom field data. - The PUT endpoint updates only the fields that you specify in the request body. If you don't include fields in the request body, the PUT endpoint doesn't replace those fields with null values. If you need to update a field to a null value, delete the custom object instance and recreate it without specifying the field in the request body. - You can't update the values of the business object ID and the custom object Reference ID in the request body. Sample request: Update the strike price of a stock grant for a specific worker. ``` PUT /customObjects/stockGrants/Employee_ID=21035;grantName=Merit_Q12021 ``` Request body: ``` { "strikePrice": { "currency": "USD", "value": "270" } } ``` Sample response: ``` { "ok": "OK" } ``` ## Deleting a Custom Object Instance To delete an instance of a multi-instance custom object, use this endpoint: ``` DELETE /customObjects/{customObjectAlias}/{customObjectID} ``` To submit the endpoint, specify: - The `{customObjectAlias}` path parameter using the web service alias of the custom object. - The `{customObjectID}` path parameter using a compound ID that follows this format: ``` {businessObjectID};{customObjectReferenceId}={customObjectReferenceIdValue} ``` Sample request: Delete a specific stock grant for a specific worker. ``` DELETE /customObjects/stockGrants/Employee_ID=21035;grantName=Merit_Q12021 ``` Sample response: ``` { "ok": "OK" } ``` ## Checking Validations The Custom Object REST APIs return these HTTP status codes. This list also includes common mistakes and error messages: - 404 If you specified an invalid custom object alias or business object ID as a path parameter, the endpoint returns a similar error message: ``` { "error": "not found: parkingSpacex", "code": "S21" } ``` If you specified a valid business object ID as a path parameter, the endpoint returns an error message with a valid object ID. In this case, the custom object instance doesn't exist. ``` { "error": "not found: Employee_ID=21035", "code": "S21" } ``` - 400 If you specified an invalid field value in the request body, the endpoint returns an error with a similar error message: ``` { "error": "invalid request: errors have occurred", "errors": [ { "error": "not found: norma", "code": "S5", "location": "Line: 25, column: 6" } ] } ``` If you incorrectly specified a data type in the request body, the endpoint returns an error with a similar error message: ``` { "error": "invalid request: errors have occurred", "errors": [ { "error": "Current token (VALUE_STRING) not of boolean type", "code": "S5", "location": "Line: 6, column: 19" } ] } ``` If you incorrectly formatted a custom field in the request body, the endpoint returns an error with a similar error message: ``` { "error": "invalid request: errors have occurred", "errors": [ { "error": "Can not instantiate value of type [map type; class java.util.LinkedHashMap, [simple type, class java.lang.String] -> [simple type, class java.lang.String]] from JSON String; no single-String constructor/factory method", "code": "S5", "location": "Line: 23, column: 33" } ] } ``` - 500 Possible errors: - Missing business object in the request body. - Missing required field. - Invalid currency. - Misformatted date. The date must use the yyyy-mm-dd format. Sample error: ``` { "error": "internal error", "code": "S24", "caseId": "ad0fc780-a4fd-43bb-80cf-524c5772b8a0" } ``` ## Limitations Custom objects and custom fields have limits. For details, see [Reference: Custom Object Limits and Field Limits](https://doc.workday.com/admin-guide/en-us/manage-workday/tenant-configuration/custom-objects-and-labels/jas1413487212409.html). ### Related Information [Concept: Custom Objects](/wcp_docs/fdy1529428780920.html) [Concept: Custom Objects in Solutions and Integrations](/wcp_docs/dan1370797810638.html) [Concept: Security for Custom Objects](/wcp_docs/dan1370797808826.html) [Create and Edit Custom Object Definitions](/wcp_docs/dan1370797402608.html) [Reference: Custom Object Limits and Field Limits](/wcp_docs/jas1413487212409.html) [Reference: Workday Object Resource Names and Object Keys](/wcp_docs/uvm1621884333680.html) [Workday Community: Custom Objects (Non-Effective Dated) EIB - Inbound](https://community.workday.com/articles/487822)