--- schema_version: "1" id: 3dc084a588523943adc15575c49cf016f3eefd00e4d863e0b7e1305e14697ab5 title: Data Extensions collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/marketing-cloud/references/generated-api-specs/mc-custom_objects.md canonical_url: https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc-custom_objects source_site: developer.salesforce.com content_type: documentation content_hash: 31f560e8c372bd8a14a778d1ca706615e7cc275bcdff31c1e967c79e7bf74ab0 products: - Marketing Cloud Engagement APIs and Programmatic Languages - Marketing Cloud --- Data Extensions # Data Extensions Create, modify, and manage data extensions (also called custom objects). > **NOTE** > > There are several APIs related to data extensions: > > * Use this API to create, modify, and manage data extension objects. > * Use the [Data Extension Rows (Asynchronous)](/docs/marketing/marketing-cloud/references/mc-data_extension_rows_async) and [Data Extension Rows (Synchronous)](/docs/marketing/marketing-cloud/references/mc-data_extension_rows_sync) APIs to add or update rows of data in a data extension. > * Use the [Data Extension Data](/docs/marketing/marketing-cloud/references/mc-custom_object_data) API to query data in a data extension. > * Use the [Data Extension Imports](https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc-import_job_api) API to manage data import jobs. This table lists the use cases that this API supports. | Use Case | HTTP Verb | Endpoint | | --- | --- | --- | | [Get data extensions](/docs/marketing/marketing-cloud/references/mc-custom_objects?meta=getDataExtensions) | GET | /data/v1/customobjects | | [Create data extension](/docs/marketing/marketing-cloud/references/mc-custom_objects?meta=createDataExtension) | POST | /data/v1/customobjects | | [Delete data extension](/docs/marketing/marketing-cloud/references/mc-custom_objects?meta=deleteDataExtension) | DELETE | /data/v1/customobjects/{id} | | [Get data extension](/docs/marketing/marketing-cloud/references/mc-custom_objects?meta=getDataExtension) | GET | /data/v1/customobjects/{id} | | [Update data extension](/docs/marketing/marketing-cloud/references/mc-custom_objects?meta=updateDataExtension) | PATCH | /data/v1/customobjects/{id} | | [Clear data extension data](/docs/marketing/marketing-cloud/references/mc-custom_objects?meta=clearDataExtensionData) | POST | /data/v1/customobjects/{id}/cleardata | | [Get data extension fields](/docs/marketing/marketing-cloud/references/mc-custom_objects?meta=getDataExtensionFields) | GET | /data/v1/customobjects/{id}/fields | | [Get data extensions by category ID](/docs/marketing/marketing-cloud/references/mc-custom_objects?meta=getDataExtensionsByCategoryId) | GET | /data/v1/customobjects/category/{categoryId} | | [Update data extension field](/docs/marketing/marketing-cloud/references/mc-custom_objects?meta=updateDataExtensionField) | PATCH | /data/v1/customobjectsasync/{id}/fields | | [Create data extension field](/docs/marketing/marketing-cloud/references/mc-custom_objects?meta=createDataExtensionField) | POST | /data/v1/customobjectsasync/{id}/fields | Append the operation endpoint addresses to this base URL, replacing `{subdomain}` with the unique subdomain for your Marketing Cloud Engagement tenant. **Version:** 1.0 ## Servers * `https://{subdomain}.rest.marketingcloudapis.com` * `subdomain (default N/A) The unique API subdomain for your Marketing Cloud Engagement tenant. You can find this value in the Installed Packages section of Marketing Cloud Engagement Setup.` ## Operations ### GET Retrieves a list of data extensions that match a search string. `GET /data/v1/customobjects` Operation ID: `getDataExtensions`. ### Required Scopes To retrieve data extensions in your account, your API user must have this permission: * Data | Data Extensions | Read (`data_extensions_read`) #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `$search` (query, string, required) A string to search for in the name of the custom object. * `$page` (query, number) The page of results to retrieve. Each page includes the number of records specified by the $pagesize parameter. You can retrieve additional pages by incrementing this number in subsequent calls. The default value is `1`. * `$pagesize` (query, number) The number of records to return on each page of results. The default value is `2500`. #### Responses * **200** This response indicates that the API accepted the request to retrieve a list of custom objects. Media type: `application/json`. Schema: `getCustomObjectsResponseBody`. _Example_ ``` { "count": 1, "page": 1, "pageSize": 25, "links": {}, "items": [ { "id": "36e73253-16a9-ee11-ac6c-0abc489251b9", "name": "facb9d48d7c44486a7b0715ef0b2f7a2", "key": "facb9d48d7c44486a7b0715ef0b2f7a2", "description": "", "isActive": true, "isSendable": true, "sendableCustomObjectField": "SubscriberKey", "sendableSubscriberField": "_SubscriberKey", "isTestable": true, "categoryId": 152631, "ownerId": 712000003, "isObjectDeletable": true, "isFieldAdditionAllowed": true, "isFieldModificationAllowed": true, "createdDate": "2024-01-01T20:26:31.07", "createdById": 712000003, "createdByName": "TestUser", "modifiedDate": "2024-01-01T20:26:31.07", "modifiedById": 712000003, "modifiedByName": "TestUser", "ownerName": "TestUser", "partnerApiObjectTypeId": 310, "partnerApiObjectTypeName": "DataExtension", "rowCount": 100000, "dataRetentionProperties": { "isDeleteAtEndOfRetentionPeriod": false, "isRowBasedRetention": false, "isResetRetentionPeriodOnImport": false }, "fieldCount": 5 } ] } ``` * **400** This response indicates that the API couldn’t retrieve a list of custom objects because there was a problem with the request. For example, the API returns this response when your request doesn’t include a `$search` query parameter. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "$search is a required parameter", "errorcode": 10005, "documentation": "" } ``` * **401** Indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "documentation": "", "errorcode": 20002, "message": "Insufficient privileges to complete this action." } ``` ### POST Creates a data extension. `POST /data/v1/customobjects` Operation ID: `createDataExtension`. ### Required Scopes To retrieve data extensions in your account, your API user must have this permission: * Data | Data Extensions | Write (`data_extensions_write`) #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` #### Request body (required) Media type: `application/json`. Schema: `createCustomObjectRequestBody`. #### Responses * **201** Indicates that the API accepted the request to create a data extension. Media type: `application/json`. Schema: `getCustomObjectResponseBody`. _Example_ ``` { "id": "36e73253-16a9-ee11-ac6c-0abc489251b9", "name": "facb9d48d7c44486a7b0715ef0b2f7a2", "key": "facb9d48d7c44486a7b0715ef0b2f7a2", "description": "", "isActive": true, "isSendable": true, "sendableCustomObjectField": "SubscriberKey", "sendableSubscriberField": "_SubscriberKey", "isTestable": true, "categoryId": 152631, "ownerId": 712000003, "isObjectDeletable": true, "isFieldAdditionAllowed": true, "isFieldModificationAllowed": true, "createdDate": "2024-01-01T20:26:31.07", "createdById": 712000003, "createdByName": "TestUser", "modifiedDate": "2024-01-01T20:26:31.07", "modifiedById": 712000003, "modifiedByName": "TestUser", "ownerName": "TestUser", "partnerApiObjectTypeId": 310, "partnerApiObjectTypeName": "DataExtension", "rowCount": 100000, "dataRetentionProperties": { "isDeleteAtEndOfRetentionPeriod": false, "isRowBasedRetention": false, "isResetRetentionPeriodOnImport": false }, "fieldCount": 5 } ``` * **400** This response indicates that the API couldn’t create the custom object because there was a problem with the request. For example, the API returns this response when your request references an invalid category ID. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "A valid categoryId must be provided", "errorcode": 10005, "documentation": "" } ``` * **401** Indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "documentation": "", "errorcode": 20002, "message": "Insufficient privileges to complete this action." } ``` ### GET Retrieves information about the specified data extension by providing its ID. `GET /data/v1/customobjects/{id}` Operation ID: `getDataExtension`. ### Required Scopes To retrieve data extensions in your account, your API user must have this permission: * Data | Data Extensions | Read (`data_extensions_read`) #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `id` (path, string, required) The unique ID of the data extension. #### Responses * **200** This response indicates that the API accepted the request to retrieve a list of custom objects. Media type: `application/json`. Schema: `getCustomObjectResponseBody`. _Example: same as POST /data/v1/customobjects 201 response._ * **401** Indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "documentation": "", "errorcode": 20002, "message": "Insufficient privileges to complete this action." } ``` * **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that the request contains the correct endpoint URI. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 404, "message": "Not Found" } ``` ### DELETE Deletes a data extension. `DELETE /data/v1/customobjects/{id}` Operation ID: `deleteDataExtension`. ### Required Scopes To retrieve data extensions in your account, your API user must have this permission: * Data | Data Extensions | Write (`data_extensions_write`) #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `id` (path, string, required) The unique ID of the data extension. #### Responses * **200** Indicates that the API accepted the request to delete the data extension. The response doesn’t contain any additional information. * **401** Indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "documentation": "", "errorcode": 20002, "message": "Insufficient privileges to complete this action." } ``` * **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that the request contains the correct endpoint URI. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 404, "message": "Not Found" } ``` ### PATCH Update the fields in a data extension. `PATCH /data/v1/customobjects/{id}` Operation ID: `updateDataExtension`. ### Required Scopes To retrieve data extensions in your account, your API user must have this permission: * Data | Data Extensions | Write (`data_extensions_write`) #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `id` (path, string, required) The unique ID of the data extension. #### Request body (required) Media type: `application/json`. Schema: `createCustomObjectRequestBody`. #### Responses * **200** Indicates that the API accepted the request to update a data extension. Media type: `application/json`. Schema: `getCustomObjectResponseBody`. _Example: same as POST /data/v1/customobjects 201 response._ * **400** This response indicates that the API couldn’t create the custom object because there was a problem with the request. For example, the API returns this response when your request references an invalid category ID. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "A valid categoryId must be provided", "errorcode": 10005, "documentation": "" } ``` * **401** Indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "documentation": "", "errorcode": 20002, "message": "Insufficient privileges to complete this action." } ``` ### POST Deletes all of the data in a data extension. `POST /data/v1/customobjects/{id}/cleardata` Operation ID: `clearDataExtensionData`. ### Required Scopes To retrieve data extensions in your account, your API user must have this permission: * Data | Data Extensions | Write (`data_extensions_write`) #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `id` (path, string, required) The unique ID of the data extension. #### Responses * **200** Indicates that the API accepted the request to remove all of the data in the data extension. The response doesn’t contain any additional information. * **401** Indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "documentation": "", "errorcode": 20002, "message": "Insufficient privileges to complete this action." } ``` * **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that the request contains the correct endpoint URI. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "There was no Custom Object found", "errorcode": 30003, "documentation": "" } ``` ### GET Retrieves a list of fields in a data extension. `GET /data/v1/customobjects/{id}/fields` Operation ID: `getDataExtensionFields`. ### Required Scopes To retrieve data extensions in your account, your API user must have this permission: * Data | Data Extensions | Read (`data_extensions_read`) #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `id` (path, string, required) The unique ID of the data extension. #### Responses * **200** Indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `getCustomObjectFieldsResponseBody`. _Example_ ``` { "id": "f9e59b85-f353-ee11-ba4e-d4f5ef3d54c9", "fields": [ { "name": "MemberId", "id": "fd526c4d-d5c5-4601-9849-53839857960c", "type": "Number", "maskType": "None", "storageType": "Plain", "description": "", "ordinal": 0, "isNullable": false, "isPrimaryKey": true, "isTemplateField": false, "isInheritable": false, "isOverridable": false, "isHidden": false, "isReadOnly": false, "mustOverride": false }, { "name": "FirstName", "id": "67180103-7235-41c9-ad59-8b18a76a02d5", "type": "Text", "maskType": "None", "storageType": "Plain", "length": 50, "description": "", "ordinal": 1, "isNullable": true, "isPrimaryKey": false, "isTemplateField": false, "isInheritable": false, "isOverridable": false, "isHidden": false, "isReadOnly": false, "mustOverride": false }, { "name": "Surname", "id": "54d4fd6a-2a00-4439-9162-e08569d6feb6", "type": "Text", "maskType": "None", "storageType": "Plain", "length": 50, "description": "", "ordinal": 2, "isNullable": true, "isPrimaryKey": false, "isTemplateField": false, "isInheritable": false, "isOverridable": false, "isHidden": false, "isReadOnly": false, "mustOverride": false }, { "name": "RewardsPoints", "id": "98023ae7-e04f-4d19-9a5c-a0bace805f87", "type": "Number", "maskType": "None", "storageType": "Plain", "description": "", "ordinal": 3, "isNullable": true, "isPrimaryKey": false, "isTemplateField": false, "isInheritable": false, "isOverridable": false, "isHidden": false, "isReadOnly": false, "mustOverride": false }, { "name": "RewardsTier", "id": "39126457-a060-4eef-a37c-cd23fc5a8c9d", "type": "Number", "maskType": "None", "storageType": "Plain", "description": "", "ordinal": 4, "isNullable": true, "isPrimaryKey": false, "isTemplateField": false, "isInheritable": false, "isOverridable": false, "isHidden": false, "isReadOnly": false, "mustOverride": false }, { "name": "Area", "id": "b0de5f86-6602-4937-904e-07c63d7fb0e8", "type": "Text", "maskType": "None", "storageType": "Plain", "length": 50, "description": "", "ordinal": 5, "isNullable": true, "isPrimaryKey": false, "isTemplateField": false, "isInheritable": false, "isOverridable": false, "isHidden": false, "isReadOnly": false, "mustOverride": false } ], "fieldCount": 6 } ``` * **401** Indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "documentation": "", "errorcode": 20002, "message": "Insufficient privileges to complete this action." } ``` * **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that the request contains the correct endpoint URI. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 404, "message": "Not Found" } ``` ### GET Retrieves a list of data extensions based on the ID of the parent category. `GET /data/v1/customobjects/category/{categoryId}` Operation ID: `getDataExtensionsByCategoryId`. ### Required Scopes To retrieve data extensions in your account, your API user must have this permission: * Data | Data Extensions | Read (`data_extensions_read`) #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `categoryId` (path, string, required) The ID of the data extension folder. #### Responses * **200** This response indicates that the API accepted the request to retrieve a list of custom objects. Media type: `application/json`. Schema: `getCustomObjectsResponseBody`. _Example: same as GET /data/v1/customobjects 200 response._ * **401** Indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "documentation": "", "errorcode": 20002, "message": "Insufficient privileges to complete this action." } ``` * **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that the request contains the correct endpoint URI. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 404, "message": "Not Found" } ``` ### POST Inserts a new field into a data extension. `POST /data/v1/customobjectsasync/{id}/fields` Operation ID: `createDataExtensionField`. ### Required Scopes To retrieve data extensions in your account, your API user must have this permission: * Data | Data Extensions | Write (`data_extensions_write`) #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `id` (path, string, required) The unique ID of the data extension. #### Request body (required) Media type: `application/json`. Schema: `customObjectsFieldObject`. #### Responses * **202** Indicates that the API accepted the request to insert a field into a data extension. The response includes the request ID. Media type: `text/plain`. Schema: `string`. Type: `string`. _Example_ ``` c90b71a2-660e-4f70-b017-40d22c3d5f3b ``` * **400** This response indicates that the API couldn’t create the custom object because there was a problem with the request. For example, the API returns this response when your request references an invalid category ID. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "A valid categoryId must be provided", "errorcode": 10005, "documentation": "" } ``` * **401** Indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "documentation": "", "errorcode": 20002, "message": "Insufficient privileges to complete this action." } ``` * **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that the request contains the correct endpoint URI. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "There was no Custom Object found", "errorcode": 30003, "documentation": "" } ``` ### PATCH Updates a field in a data extension. `PATCH /data/v1/customobjectsasync/{id}/fields` Operation ID: `updateDataExtensionField`. Required Permission Scope To execute this operation, you must have the `Data Extensions | Write` permission. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `id` (path, string, required) The unique ID of the data extension. #### Request body (required) Media type: `application/json`. Schema: `updateCustomObjectFieldRequestBody`. #### Responses * **202** Indicates that the API accepted the request to insert a field into a data extension. The response includes the request ID. Media type: `text/plain`. Schema: `string`. Type: `string`. _Example_ ``` c90b71a2-660e-4f70-b017-40d22c3d5f3b ``` * **400** This response indicates that the API couldn’t create the custom object because there was a problem with the request. For example, the API returns this response when your request references an invalid category ID. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "A valid categoryId must be provided", "errorcode": 10005, "documentation": "" } ``` * **401** Indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "documentation": "", "errorcode": 20002, "message": "Insufficient privileges to complete this action." } ``` * **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that the request contains the correct endpoint URI. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "There was no Custom Object found", "errorcode": 30003, "documentation": "" } ``` ## Schemas ### getCustomObjectsResponseBody * `count` (_number (integer)_) The total number of custom objects that match the search string. * `page` (_number (integer)_) The current page of results. Each page includes the number of records specified by the `$pagesize` parameter in the request. You can retrieve additional pages by incrementing this number in subsequent calls. * `pageSize` (_number (integer)_) The maximum number of results returned in a page of results. * `links` (_object_) * `items` (_array of customObjectDetailsObject_) An array that contains details of the custom objects that matched the search string. ### mceErrorResponseBody * `documentation` (_string_) An empty string. * `errorcode` (_integer_) An internal error code. For a complete list of error codes, see [Handle Errors in REST API](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/error-handling.html). * `message` (_string_) The error message. ### httpErrorResponseBody * `documentation` (_string_) Contains a link to the [Marketing Cloud Engagement developer documentation page about handling REST API errors](https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm). * `errorcode` (_integer_) The error code. In some situations, this value can be 0. * `message` (_string_) The error message. ### createCustomObjectRequestBody * `name` (_string_) The name of the custom object. * `key` (_string_) A unique key for the custom object. * `description` (_string_) A description of the custom object. * `isActive` (_boolean_) Indicates whether the custom object is active. If the value of this property is `true`, then the custom object is active. * `isSendable` (_boolean_) Indicates whether the custom object can be used to send messages. If the value of this property is `true`, then the custom object is sendable. * `sendableCustomObjectField` (_string_) * `sendableSubscriberField` (_string_) * `isTestable` (_boolean_) Indicates whether the custom object can be used to send test messages. If the value of this property is `true`, then the custom object can be used for testing. * `categoryId` (_number (integer)_) The ID of the category that the custom object belongs to. * `isObjectDeletable` (_boolean_) Indicates whether the object can be deleted. If the value of this property is `true`, then the object is deletable. * `isFieldAdditionAllowed` (_boolean_) * `isFieldModificationAllowed` (_boolean_) * `dataRetentionProperties` (_object_) An object that describes the data retention policy that applies to the object. * `isDeleteAtEndOfRetentionPeriod` (_boolean_) Indicates whether data in the object is deleted when the end of the retention period is reached. If the value of this property is `true`, data is deleted at the end of the retention period. * `isRowBasedRetention` (_boolean_) Indicates whether the custom object includes row-based data retention policies. If the value of this property is `true`, the object includes row-based retention policies. * `isResetRetentionPeriodOnImport` (_boolean_) Indicates whether the retention period is reset when data is imported into the custom object. If the value of this property is `true`, then the retention period is reset during an import. * `fields` (_array of customObjectsFieldObject_) An array that contains details of each field in the data extension. _Example_ ``` { "name": "mynewde", "key": "mynewde", "description": "", "isActive": true, "isSendable": true, "sendableCustomObjectField": "SubscriberKey", "sendableSubscriberField": "_SubscriberKey", "isTestable": true, "categoryId": 1760804, "isObjectDeletable": true, "isFieldAdditionAllowed": true, "isFieldModificationAllowed": true, "dataRetentionProperties": { "isDeleteAtEndOfRetentionPeriod": false, "isRowBasedRetention": false, "isResetRetentionPeriodOnImport": false, "rowBasedThreshold": 500000000 }, "fields": [ { "name": "SubscriberKey", "type": "Text", "maskType": "None", "storageType": "Plain", "length": 50, "description": "", "ordinal": 0, "isNullable": false, "isPrimaryKey": true, "isTemplateField": false, "isInheritable": true, "isOverridable": true, "isHidden": false, "isReadOnly": false, "mustOverride": false }, { "name": "Name", "type": "Text", "maskType": "None", "storageType": "Plain", "description": "", "ordinal": 1, "isNullable": true, "isPrimaryKey": false, "isTemplateField": false, "isInheritable": true, "isOverridable": true, "isHidden": false, "isReadOnly": false, "mustOverride": false }, { "name": "EmailAddress", "type": "EmailAddress", "maskType": "None", "storageType": "Plain", "length": 254, "description": "", "ordinal": 2, "isNullable": true, "isPrimaryKey": false, "isTemplateField": false, "isInheritable": true, "isOverridable": true, "isHidden": false, "isReadOnly": false, "mustOverride": false }, { "name": "ContactID", "type": "Number", "maskType": "None", "storageType": "Plain", "description": "", "ordinal": 3, "isNullable": true, "isPrimaryKey": false, "isTemplateField": false, "isInheritable": true, "isOverridable": true, "isHidden": false, "isReadOnly": false, "mustOverride": false }, { "name": "ContactKey", "type": "Text", "maskType": "None", "storageType": "Plain", "description": "", "ordinal": 4, "isNullable": true, "isPrimaryKey": false, "isTemplateField": false, "isInheritable": true, "isOverridable": true, "isHidden": false, "isReadOnly": false, "mustOverride": false } ] } ``` ### getCustomObjectResponseBody ### getCustomObjectFieldsResponseBody * `id` (_string_) The unique ID of the data extension field. * `fields` (_array of customObjectsFieldObject_) An array that contains details of each field in the data extension. ### customObjectsFieldObject * `name` (_string_) The name of the data extension field. * `id` (_string_) The unique ID of the data extension field. * `type` (_string_) The data type of the field. * `maskType` (_string_) * `storageType` (_string_) * `length` (_number (integer)_) For text fields, the maximum number of characters that the field can contain. * `description` (_string_) A description of the field. * `isNullable` (_boolean_) Indicates whether the field can contain a null value. If the value of this property is `true`, the field can contain null values. * `isPrimaryKey` (_boolean_) Indicates whether the field is a primary key. If the value of this property is `true`, the field is a primary key. * `isTemplateField` (_boolean_) Indicates whether the field is used in a template. If the value of this property is `true`, the field is a template field. * `isInheritable` (_boolean_) * `isOverridable` (_boolean_) Indicates whether the field can be overridden. If the value of this property is `true`, the field can be overridden. * `isHidden` (_boolean_) Indicates whether the field is hidden. If the value of this property is `true`, the field is hidden. * `isReadOnly` (_boolean_) Indicates whether the field is read-only. If the value of this property is `true`, the field is read-only. * `mustOverride` (_boolean_) _Example_ ``` { "fields": [ { "description": "The mobile phone number of the contact.", "isActive": true, "isHidden": false, "isInheritable": false, "isNullable": true, "isOverridable": false, "isPrimaryKey": false, "isReadOnly": false, "isTemplateField": false, "length": 50, "maskType": "None", "mustOverride": false, "name": "PhoneNumber", "storageType": "Plain", "type": "Text" } ] } ``` ### updateCustomObjectFieldRequestBody * `name` (_string_) The name of the data extension field. * `id` (_string_) The ID of the data extension field to update. * `type` (_string_) The data type of the field. * `maskType` (_string_) * `storageType` (_string_) * `length` (_number (integer)_) For text fields, the maximum number of characters that the field can contain. * `description` (_string_) A description of the field. * `isNullable` (_boolean_) Indicates whether the field can contain a null value. If the value of this property is `true`, the field can contain null values. * `isPrimaryKey` (_boolean_) Indicates whether the field is a primary key. If the value of this property is `true`, the field is a primary key. * `isTemplateField` (_boolean_) Indicates whether the field is used in a template. If the value of this property is `true`, the field is a template field. * `isInheritable` (_boolean_) * `isOverridable` (_boolean_) Indicates whether the field can be overridden. If the value of this property is `true`, the field can be overridden. * `isHidden` (_boolean_) Indicates whether the field is hidden. If the value of this property is `true`, the field is hidden. * `isReadOnly` (_boolean_) Indicates whether the field is read-only. If the value of this property is `true`, the field is read-only. * `mustOverride` (_boolean_) _Example_ ``` { "fields": [ { "id": "b849a568-f729-49f5-9d21-65a4d98311f1", "description": "The mobile phone number of the contact.", "isActive": true, "isHidden": false, "isInheritable": false, "isNullable": true, "isOverridable": false, "isPrimaryKey": false, "isReadOnly": false, "isTemplateField": false, "length": 50, "maskType": "None", "mustOverride": false, "name": "MobileNumber", "storageType": "Plain", "type": "Text" } ] } ``` ### customObjectDetailsObject * `id` (_string_) The unique ID of the custom object. * `name` (_string_) The name of the custom object. * `key` (_string_) A unique key for the custom object. * `description` (_string_) A description of the custom object. * `isActive` (_boolean_) Indicates whether the custom object is active. If the value of this property is `true`, then the custom object is active. * `isSendable` (_boolean_) Indicates whether the custom object can be used to send messages. If the value of this property is `true`, then the custom object is sendable. * `sendableCustomObjectField` (_string_) * `sendableSubscriberField` (_string_) * `isTestable` (_boolean_) Indicates whether the custom object can be used to send test messages. If the value of this property is `true`, then the custom object can be used for testing. * `categoryId` (_number (integer)_) The ID of the category that the custom object belongs to. * `isObjectDeletable` (_boolean_) Indicates whether the object can be deleted. If the value of this property is `true`, then the object is deletable. * `isFieldAdditionAllowed` (_boolean_) * `isFieldModificationAllowed` (_boolean_) * `createdDate` (_string (date-time)_) The date and time when the custom object was created. This property is shown in ISO 8601 format. * `createdById` (_number (integer)_) The unique ID of the user who created the custom object. * `createdByName` (_string_) The name of the user who created the custom object. * `modifiedDate` (_string (date-time)_) The date and time when the custom object was last modified. This property is shown in ISO 8601 format. * `modifiedById` (_number (integer)_) The unique ID of the user who last modified the custom object. * `modifiedByName` (_string_) The name of the user who last modified the custom object. * `ownerId` (_number (integer)_) The unique ID of the user who owns the custom object. * `ownerName` (_string_) The name of the user who owns the custom object. * `partnerApiObjectTypeId` (_number (integer)_) * `partnerApiObjectTypeName` (_string_) * `rowCount` (_number (integer)_) The number of rows in the custom object. * `dataRetentionProperties` (_object_) An object that describes the data retention policy that applies to the object. * `isDeleteAtEndOfRetentionPeriod` (_boolean_) Indicates whether data in the object is deleted when the end of the retention period is reached. If the value of this property is `true`, data is deleted at the end of the retention period. * `isRowBasedRetention` (_boolean_) Indicates whether the custom object includes row-based data retention policies. If the value of this property is `true`, the object includes row-based retention policies. * `isResetRetentionPeriodOnImport` (_boolean_) Indicates whether the retention period is reset when data is imported into the custom object. If the value of this property is `true`, then the retention period is reset during an import. * `fieldCount` (_number (integer)_) The number of fields in the custom object.