--- schema_version: "1" id: 24597549761df627dfa4546ddbde5e24aa9e14551141bee9792a7aec4fec9d51 title: Data Extension Rows (Asynchronous) collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/marketing-cloud/references/generated-api-specs/mc-data_extension_rows_async.md canonical_url: https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc-data_extension_rows_async source_site: developer.salesforce.com content_type: documentation content_hash: e099100e9b6e7f13503c1c4e7c06b2af00bcdc8f3ed1ccf57569c8f49288c4b7 products: - Marketing Cloud Engagement APIs and Programmatic Languages - Marketing Cloud --- Data Extension Rows (Asynchronous) # Data Extension Rows (Asynchronous) Manage rows in a data extension asynchronously. > **NOTE** > > There are several APIs related to data extensions: > > * Use this API or the [Data Extension Rows (Synchronous)](/docs/marketing/marketing-cloud/references/mc-data_extension_rows_sync) API to add or update rows of data in a data extension. > * Use the [Data Extensions](/docs/marketing/marketing-cloud/references/mc-custom_objects) API to create, modify, and manage data extension objects. > * 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 the Data Extension Rows Asynchronous API supports. | Use Case | HTTP Verb | Endpoint | | --- | --- | --- | | [Get the results of an asynchronous insert or upsert request](/docs/marketing/marketing-cloud/references/mc-data_extension_rows_async?meta=getRequestResults) | GET | /data/v1/async/{requestId}/results | | [Get the status of an asynchronous insert or upsert request](/docs/marketing/marketing-cloud/references/mc-data_extension_rows_async?meta=getRequestStatus) | GET | /data/v1/async/{requestId}/status | | [Insert data extension rows asynchronously](/docs/marketing/marketing-cloud/references/mc-data_extension_rows_async?meta=insertRows) | POST | /data/v1/async/dataextensions/key:{externalKey}/rows | | [Upsert data extension rows asynchronously](/docs/marketing/marketing-cloud/references/mc-data_extension_rows_async?meta=upsertRows) | PUT | /data/v1/async/dataextensions/key:{externalKey}/rows | For information about the limits that apply to this API, see _Salesforce Help_: [Limits and Guidelines](https://help.salesforce.com/s/articleView?id=mktg.mc_overview_limits.htm). Append the operation endpoint addresses to this base URL, replacing `{subdomain}` with the unique subdomain for your Marketing Cloud Engagement tenant: **Version:** 1 ## Servers * `https://{subdomain}.rest.marketingcloudapis.com` * `subdomain (default None) 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 Retrieve the results of a request to asynchronously insert rows into a data extension. `GET /data/v1/async/{requestId}/results` Operation ID: `getRequestResults`. For information about the limits that apply to this API, see _Salesforce Help_: [Limits and Guidelines](https://help.salesforce.com/s/articleView?id=mktg.mc_overview_limits.htm). #### 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 ``` * `requestId` (path, string (uuid), required) A unique ID for an asynchronous request. Use this ID to retrieve the status and results of the request. #### Responses * **200** This response includes the results of a request to asynchronously insert or update data in a data extension. The API also returns this response if it's unable to find the specified `requestId`. If the API fails to retrieve the specified `requestId`, the `status` object is omitted in the response, and the `resultMessages` array contains details of the issue. This example shows a successful request. Media type: `application/json`. Schema: `insertUpdateResultsGetResponseBody`. _Example_ ``` { "page": 1, "pageSize": 2, "count": 2, "items": [ { "message": "Created DataExtensionObject", "status": "OK" }, { "errorCode": 71003, "message": "Cannot insert the value NULL into column 'RewardsPoints', table 'ExactTarget.C67709.MembershipRewardsProgramme2'; column does not allow nulls. INSERT fails.\r\nThe statement has been terminated.", "status": "Error" } ], "requestId": "5a67f73d-801d-4b5f-bee7-8b6acf34743a", "resultMessages": [] } ``` * **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." } ``` * **500** Indicates that the API encountered an error when processing the request. When you receive a 500 response, verify that the request uses the correct syntax. 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": "Internal Server Error" } ``` ### GET Retrieve the status of a request to asynchronously insert rows into a data extension. `GET /data/v1/async/{requestId}/status` Operation ID: `getRequestStatus`. For information about the limits that apply to this API, see _Salesforce Help_: [Limits and Guidelines](https://help.salesforce.com/s/articleView?id=mktg.mc_overview_limits.htm). #### 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 ``` * `requestId` (path, string (uuid), required) A unique ID for an asynchronous request. Use this ID to retrieve the status and results of the request. #### Responses * **200** This response describes the status of a request to asynchronously insert or update data in a data extension. In some cases, it can take several seconds for results to be available after you submit a request. The API also returns this response if it's unable to find the specified `requestId`. If the API fails to retrieve the specified `requestId`, the `status` object is omitted in the response, and the `resultMessages` array contains details of the issue. This example shows a successful request. Media type: `application/json`. Schema: `insertUpdateStatusGetResponseBody`. _Example_ ``` { "status": { "callDateTime": "2024-07-11T22:19:02.04", "completionDateTime": "2024-07-11T22:19:03.97", "hasErrors": false, "pickupDateTime": "2024-07-11T22:19:03.567", "requestStatus": "Complete", "resultStatus": "OK", "requestId": "12260e92-b8cb-41ec-8c5a-116fb9d23eb4" }, "requestId": "615f178b-d380-440c-a650-defd99b1efde", "resultMessages": [] } ``` * **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." } ``` * **500** Indicates that the API encountered an error when processing the request. When you receive a 500 response, verify that the request uses the correct syntax. 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": "Internal Server Error" } ``` ### PUT Asynchronously update rows in a data extension if the primary key exists, or create rows if the primary key doesn't exist. `PUT /data/v1/async/dataextensions/key:{externalKey}/rows` Operation ID: `upsertRows`. For information about the limits that apply to this API, see _Salesforce Help_: [Limits and Guidelines](https://help.salesforce.com/s/articleView?id=mktg.mc_overview_limits.htm). #### 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 ``` * `externalKey` (path, string (uuid), required) The external ID, also known as the customer key, for the data extension to insert or upsert data into. #### Request body (required) Media type: `application/json`. Schema: `dataExtensionInsertUpdateRequestBody`. #### Responses * **202** This response indicates that the API accepted the request to add data to a data extension asynchronously. Media type: `application/json`. Schema: `dataExtensionInsertUpdateResponseBody`. _Example_ ``` { "requestId": "399d1e33-9beb-4192-b915-3925b0e1a00c", "resultMessages": [] } ``` * **400** This response indicates that the API couldn't process the request. This response typically indicates that the request body is invalid. Media type: `application/json`. Schema: `dataExtensionInsertUpdateResponseBody`. _Example_ ``` { "requestId": "a35d08b3-9b56-4d79-8347-3dee55f76a77", "resultMessages": [ { "resultType": "Validation", "resultClass": "Error", "resultCode": "NullOrEmptyRows", "message": "Invalid request, Items cannot be null or empty." } ] } ``` * **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." } ``` * **500** Indicates that the API encountered an error when processing the request. When you receive a 500 response, verify that the request uses the correct syntax. 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": "Internal Server Error" } ``` ### POST Add rows to a data extension asynchronously. `POST /data/v1/async/dataextensions/key:{externalKey}/rows` Operation ID: `insertRows`. For information about the limits that apply to this API, see _Salesforce Help_: [Limits and Guidelines](https://help.salesforce.com/s/articleView?id=mktg.mc_overview_limits.htm). #### 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 ``` * `externalKey` (path, string (uuid), required) The external ID, also known as the customer key, for the data extension to insert or upsert data into. #### Request body (required) Media type: `application/json`. Schema: `dataExtensionInsertUpdateRequestBody`. #### Responses * **202** This response indicates that the API accepted the request to add data to a data extension asynchronously. Media type: `application/json`. Schema: `dataExtensionInsertUpdateResponseBody`. _Example_ ``` { "requestId": "399d1e33-9beb-4192-b915-3925b0e1a00c", "resultMessages": [] } ``` * **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." } ``` * **500** Indicates that the API encountered an error when processing the request. When you receive a 500 response, verify that the request uses the correct syntax. 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": "Internal Server Error" } ``` ## Schemas ### insertUpdateResultsGetResponseBody * `page` (_number (integer)_) The current page of results. * `pageSize` (_number (integer)_) The number of results per page. By default, there are 50 results per page. * `count` (_number (integer)_) The total number of results. * `items` (_array of object_) * `message` (_string_) A description of the result. Possible values for items that were created or updated successfully: * `Created DataExtensionObject`—The record was created. * `Upserted DataExtensionObject`—The record was updated if the primary key was found or created if the primary key wasn't found. If the item wasn't inserted or updated, this property contains a description of the issue that caused the operation to fail. * `status` (_string_) The status of the request. Possible values: * `OK` * `Error` * `errorCode` (_number (integer)_) This property isn't included in records that were successfully created or upserted. * `requestId` (_string_) The request ID for the original request. * `resultMessages` (_array of object_) An array that contains information about issues that caused the request to fail. If the API successfully retrieved the status, this array is included in the result but contains no items. * `message` (_string_) A description of the error that prevented the API from retrieving the status. Example: `Unable to locate an Async Request Status Record for the provided RequestId: efd98722-5826-418f-849e-c13a06ad3622.`. * `resultType` (_string_) Example: `Operational`. * `resultClass` (_string_) Example: `Error`. * `resultCode` (_string_) Example: `AsyncRequestStatusNotFound`. ### 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. ### 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. ### insertUpdateStatusGetResponseBody * `status` (_object_) An object that provides metadata related to the request. If the API wasn't able to retrieve the status for the specified `requestId`, this object isn't included in the response. * `callDateTime` (_string (date-time)_) The date and time when the insert or upsert request was received. * `completionDateTime` (_string (date-time)_) The date and time when the insert or upsert operation finished. * `hasErrors` (_boolean_) Indicates whether there were errors in the request. If the value is `true`, there was at least one error in the request. However, a value of `true` doesn't indicate that the entire request failed. * `pickupDateTime` (_string (date-time)_) The date and time when the request was retrieved from the asynchronous queue for processing. * `requestStatus` (_string_) The status of the request. Possible values: * `Complete`—The request completed successfully. This value is returned even if individual records in the request failed to process. * `Error`—The request failed. * `Executing`–The request is being executed. * `Pending`—The request hasn’t been processed yet or is in progress. * `resultStatus` (_string_) The status of the individual records in the request. If the status is `OK`, all records in the request were processed without errors. If the status is `Has Errors`, there was at least one record with an error. * `requestId` (_string_) The request ID for the original request. * `requestId` (_string_) A unique ID for the status retrieval request. * `resultMessages` (_array of object_) An array that contains information about issues that caused the request to fail. If the API successfully retrieved the status, this array is included in the result but contains no items. * `message` (_string_) A description of the error that prevented the API from retrieving the status. Example: `Unable to locate an Async Request Status Record for the provided RequestId: efd98722-5826-418f-849e-c13a06ad3622.`. * `resultType` (_string_) Example: `Operational`. * `resultClass` (_string_) Example: `Error`. * `resultCode` (_string_) Example: `AsyncRequestStatusNotFound`. ### dataExtensionInsertUpdateRequestBody * `items` (_array of object_) An array that contains the data to insert into the data extension. Each object in the array contains the data to insert into a single row in the data extension. * `{fieldName}` (_string_) The data to insert or update in the data extension. Replace `{fieldName}` with the name of the column. The data type must match the data type in the corresponding column of the data extension. In some cases, the API converts data to the correct data type. For example, if a request passes a string value of "123", but the data extension expects an integer for that column, the data is converted to an integer automatically. _Example_ ``` { "items": [ { "MemberId": "f284db27-e840-4e17-bcb6-537f7f1b54ad", "FirstName": "Raul", "Surname": "Nieto", "RewardsPoints": 23456, "RewardsTier": 3, "Area": "Enfield" }, { "MemberId": "cc6298da-159a-4a3e-b841-3f1048b3fd3c", "FirstName": "Foua", "Surname": "Khang", "RewardsPoints": 666777, "RewardsTier": 4, "Area": "West Ham" }, { "MemberId": "9dfc9341-d9d3-44f3-8624-f4c2dc87b4b3", "FirstName": "Mary", "Surname": "Evans", "RewardsPoints": 7849, "RewardsTier": 1, "Area": "Islington" }, { "MemberId": "9dfc9341-d9d3-44f3-8624-f4c2dc87b4b3", "FirstName": "Vijay", "Surname": "Lahiri", "RewardsPoints": 7742, "RewardsTier": 1, "Area": "Haringey" } ] } ``` ### dataExtensionInsertUpdateResponseBody * `requestId` (_string_) The request ID for the request. Use this ID to retrieve the status and results of the request. * `resultMessages` (_array of object_) An array of objects that contain information about the results of the request. In a successful response, this array is typically empty. * `resultType` (_string_) The step that failed while processing the request, such as `Validation`. * `resultClass` (_string_) The type of issue that occurred, such as `Error`. * `resultCode` (_string_) An error code that indicates the type of error that occurred. * `message` (_string_) A message that describes the issue indicated by the `resultCode` property.