---
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 Definition REST APIs
layout: subsection
---

This topic provides an overview and usage guidance on the Custom Object Definition REST APIs.

## <a id="section_umd_41s_qpb"></a>Overview

The Custom Object Definition service provides access to information about the custom objects defined in your Workday tenant. Use the Custom Object Definition REST APIs primarily for getting custom object definitions. To create, update, or delete custom object definitions, we recommend that you use the Workday UI for convenience.

Custom object definitions specify the properties and types of data stored as custom objects, which are extensions of Workday business objects. Examples of custom objects:

-   Parking space - A Parking Space custom object can be an extension of the Worker object that has information about a worker parking space. If a worker can only have 1 assigned parking space, it is a single-instance custom object.
-   Apparel - An Apparel custom object can be an extension of the Worker object that contains information about articles of clothing. If a single worker can have more than 1 assigned item of clothing, it is a multi-instance custom object.


For reference documentation about the Custom Object Definition REST APIs, see the <i>Custom Object Definition</i> 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).

## <a id="section_securityConsiderations"></a>Security Considerations

The <i>Custom Object Management</i> security domain secures the Custom Object Definition REST APIs.

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 <b>View Custom Object</b> report.

## <a id="section_1"></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.

Sample Workday Extend request URL (US region) for the `GET /definitions` endpoint:

```
https://api.workday.com/customObjectDefinition/v1/definitions
```

<b>Tenant Base Path</b>

For traditional Integrations using tenanted REST APIs calls:

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

Example:

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

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

<b>Tenant Base Path</b>

```
https://{tenantHostname}/api/customObjectDefinition/{version}/{tenantName}
```

Example:

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

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

Workday Extend is a separately licensed Workday product that provides developer tools and more flexible model components for storing custom data. If your business needs require that you use the legacy Custom Object REST APIs with Workday Extend, note the difference in the URL base path.

For Workday Extend apps, use the API Gateway URL for the Extend region of your account. See <i>Reference: Workday Extend API Gateways and Authorization Base URLs</i> on the Workday Developer Site.

Sample Workday Extend request URL (US region) for the `GET /definitions` endpoint:

```
https://api.workday.com/customObjectDefinition/v1/definitions
```

## <a id="section_equivalentWorkdayTasks"></a>Equivalent Workday Tasks

-   Create Custom Field Type.
-   Create Custom Object.
-   Create Custom Object Validations.
-   Edit Custom Object.


## <a id="section_retrievingCustomObjectDefinitions"></a>Retrieving Custom Object Definitions

To retrieve all custom object definitions available to the current user, use this endpoint:

```
GET /customObjectDefinitions
```

In addition to the `id` and `descriptor` of the custom object definitions, this method returns this information:

-   `customObjectAlias` - The resource name of the custom object. Use the customObjectAlias in the URL path when you call a Custom Object API. Example: GET /customObjects/{customObjectAlias}/{customObjectID}.
-   `multiInstance` - If true, the definition is for a multi-instance custom object. If false, the custom object is single-instance.
-   `businessObject` - The business object that the custom object extends.


Sample request:

```
GET /customObjectDefinitions
```

Sample response with 2 multi-instance and 1 single-instance custom object definitions. These custom object definitions specify that an individual worker can have more that 1 item of Apparel, more than 1 item of Shoes, and only 1 item of Worker Shoes.

```

```

```
{
   "total": 3,
   "data":    [
            {
         "descriptor": "Apparel",
         "id": "8da46c229b0842ec89f0860cba174da0",
         "customObjectName": "Apparel",
         "multiInstance": true,
         "customObjectAlias": "apparel",
         "businessObject":          {
            "descriptor": "Worker",
            "id": "766f3df40606431e8229445f1fe283c3"
         }
      },
            {
         "descriptor": "Shoes",
         "id": "e2b6ebfab5da412ea518f1a684cf730f",
         "customObjectName": "Shoes",
         "multiInstance": true,
         "customObjectAlias": "shoes",
         "businessObject":          {
            "descriptor": "Worker",
            "id": "766f3df40606431e8229445f1fe283c3"
         }
      },
            {
         "descriptor": "Worker Shoes",
         "id": "bae237b94ae9421daaa3799df6f6e3c5",
         "customObjectName": "Worker Shoes",
         "multiInstance": false,
         "customObjectAlias": "workerShoes",
         "businessObject":          {
            "descriptor": "Worker",
            "id": "766f3df40606431e8229445f1fe283c3"
         }
      }
   ]
}
```

This next sample request retrieves the custom object definition for Shoes.

```
GET /customObjectDefinitions/e2b6ebfab5da412ea518f1a684cf730f
```

Sample response:

```
{
   "descriptor": "Shoes",
   "id": "e2b6ebfab5da412ea518f1a684cf730f",
   "customObjectName": "Shoes",
   "multiInstance": true,
   "customObjectAlias": "shoes",
   "businessObject":    {
      "descriptor": "Worker",
      "id": "766f3df40606431e8229445f1fe283c3"
   }
}
```

## <a id="section_Limitations"></a>Limitations

Custom objects and custom fields have limits.