--- 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 (Single-Instance) REST APIs layout: subsection --- This topic provides an overview and usage guidance on the Custom Object (Single-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 single-instance custom object is a set of custom fields attached to a Workday business object. In Workday, users can view or edit a custom object form on the Additional Data tab of the business object. Example: The Worker object can associate a custom object named Parking Space. Because a worker can only have 1 assigned parking space, the parking space is a single-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 false, the custom object is single-instance. For GET, PUT, and DELETE endpoints, the ID path parameter is the extended Workday object ID.

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 (Single-Instance) REST APIs, see the Custom Object Data (Single-Instance) service on 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/parkingSpaces/Employee_ID=21001 ``` Tenant Base Path For traditional Integrations using tenanted REST APIs calls: ``` https:///api/customObject// ``` Example: ``` https://yourTenantHostName.com/api/customObject/v1/gms ``` ## Constructing the Request URL For the GET, PUT, and DELETE endpoints that operate on a specific custom object instance, 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: `parkingSpaces` is the web service alias of the sample Parking Spaces, which is a single-instance custom object. To determine the web service alias of the custom object, access the View Custom Object task. - {customObjectID} The Workday ID or Reference ID of the extended business object. Example: `Employee=21001` These sample request URLs are for a GET endpoint that retrieves a specific parking space for a specific worker. The web service alias of the Parking Spaces custom object is parkingSpaces. Each example is a variation of the custom object ID, which uses: - The Reference ID of the business object. v2 example: ``` https://account.tenant.com/api/customObject/v2/gms/customObjects/parkingSpaces/Employee_ID=21001 ``` v1 example: ``` https://account.tenant.com/api/v1/gms/customObjects/parkingSpaces/Employee_ID=21001 ``` - The Workday ID of the business object. v2 example: ``` https://account.tenant.com/api/customObject/v2/gms/customObjects/parkingSpaces/3aa5550b7fe348b98d7b5741afc65534 ``` v1 example: ``` https://account.tenant.com/api/v1/gms/customObjects/parkingSpaces/3aa5550b7fe348b98d7b5741afc65534 ``` ## 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: ``` "paidUntilDate": "2021-05-19" ``` - Currency Specify the currency as an object map containing the `currency` and `value` fields. Example: ``` "suggestedFee": { "currency": "USD", "value": "10" } ``` - 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: ``` "parkingSpaceType": { "id": "normal" } ``` - 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: ``` "accomodatesParkingSpaceType": [ { "id": "normal" }, { "id": "employeeOfTheMonth" } ] ``` 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 an existing 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 single-instance custom object adds custom object data to a business object. To create a single-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 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 parking space for the worker whose ID is Employee_ID=21035. ``` POST /customObjects/parkingSpaces ``` Request body: ``` { "worker": { "id": "Employee_ID=21035" }, "suggestedFee": { "currency": "USD", "value": "10" }, "description": "A12345", "fieldWithValidation": "10", "customList": { "id": "myvalueone" }, "accomodatesParkingSpaceType": [ { "id": "normal" }, { "id": "employeeOfTheMonth" } ], "paidUntilDate": "2021-05-28", "parkingSpaceType": { "id": "normal" } } ``` Response: ``` { "ok": "Created" } ``` ## Creating Custom Object Instances in Bulk Creating a single-instance custom object in bulk enables you to add custom object data to multiple business objects in the same request. To create a single-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 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. 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 parking space for 2 workers whose IDs are Employee_ID=21035 and a Workday ID, respectively. ``` POST /customObjects/parkingSpaces?bulk=true&updateIfExists=true ``` Request body ``` [ { "suggestedFee": { "currency": "USD", "value": "5" }, "available": true, "parkingSpaceNumber": 100, "description": "parking garage first floor", "worker": { "id": "Employee_ID=21035" } }, { "suggestedFee": { "currency": "USD", "value": "5" }, "available": true, "parkingSpaceNumber": 200, "description": "parking garage second floor", "worker": { "id": "3aa5550b7fe348b98d7b5741afc65534" } } ] ``` Sample response: ``` { "ok": "OK" } ``` ## Retrieving a Custom Object Instance To retrieve a single-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 the Workday ID or Reference ID of the business object that the custom object is attached to. Sample request: Retrieve the parking space for a specific worker: ``` GET /customObjects/parkingSpaces/Employee_ID=21035 ``` Sample response: ``` { "id": "e960ff12fbf430002851430d67162a92", "suggestedFee": { "currency": "USD", "value": "10" }, "currentFee": "10", "parkingSpaceNumber": 10, "description": "A123", "customList": { "id": "myvalueone" }, "accomodatesParkingSpaceType": [ { "id": "guest" } ], "parkingSpaceType": { "id": "normal" }, "worker": { "id": "989eafee6aa449679fe58caeead36b31" } } ``` ## Updating a Custom Object Instance To update a single-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 the Workday ID or Reference ID of the business object that the custom object is attached to. - 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 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. This sample request updates the suggested fee and description of a parking space for a specific worker. ``` PUT /customObjects/parkingSpaces/Employee_ID=21035 ``` ``` { "suggestedFee": { "currency": "USD", "value": "8.50" }, "description": "AA12345" } ``` Response: ``` { "ok": "OK" } ``` ## Deleting a Custom Object Instance To delete a single-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 the Workday ID or Reference ID of the business object that the custom object is attached to. This sample request deletes the parking space for a specific worker. ``` DELETE /customObjects/parkingSpaces/Employee_ID=21035 ``` 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)