--- schema_version: "1" id: e947cfc19b05419367458f7cb6d68393bbabd47bcd7fab79b03b972475b6dcb5 title: Data Extension Rows (Synchronous) 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_sync.md canonical_url: https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc-data_extension_rows_sync source_site: developer.salesforce.com content_type: documentation content_hash: 7302e178e5a2a07f03e4b89d2f3cb0977f2a14916efc7a29c4ec35cdbc1ad7c6 products: - Marketing Cloud Engagement APIs and Programmatic Languages - Marketing Cloud --- Data Extension Rows (Synchronous) # Data Extension Rows (Synchronous) To modify individual rows or groups of rows (rowsets) in a data extension, use the `/hub/v1/dataevents/` endpoints. Requests that you send to these endpoints are executed synchronously. > **NOTE** > > There are several APIs related to data extensions: > > * Use this API or the [Data Extension Rows (Asynchronous)](/docs/marketing/marketing-cloud/references/mc-data_extension_rows_async) 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 Synchronous API supports. | Use Case | HTTP Verb | Endpoint | | --- | --- | --- | | [Upsert a row](/docs/marketing/marketing-cloud/references/mc-data_extension_rows_sync?meta=upsertRow) | PUT | /hub/v1/dataevents/{dataExtensionId}/rows/{primaryKey}:{PrimaryKeyValue} | | [Upsert a row by data extension external key](/docs/marketing/marketing-cloud/references/mc-data_extension_rows_sync?meta=upsertRowByKey) | PUT | /hub/v1/dataevents/key:{externalKey}/rows/{primaryKey}:{PrimaryKeyValue} | | [Increment column value](/docs/marketing/marketing-cloud/references/mc-data_extension_rows_sync?meta=incrementColumnValue) | PUT | /hub/v1/dataevents/{dataExtensionId}/rows/{primaryKey}:{primaryKeyValue}/column/{column}/increment | | [Increment column value by data extension external key](/docs/marketing/marketing-cloud/references/mc-data_extension_rows_sync?meta=incrementColumnValueByKey) | PUT | /hub/v1/dataevents/key:{externalKey}/rows/{primaryKey}:{primaryKeyValue}/column/{column}/increment | | [Upsert a rowset by using a data extension ID](/docs/marketing/marketing-cloud/references/mc-data_extension_rows_sync?meta=upsertRowset) | POST | /hub/v1/dataevents/{dataExtensionId}/rowset | | [Upsert a rowset by using a data extension external key](/docs/marketing/marketing-cloud/references/mc-data_extension_rows_sync?meta=upsertRowsetByKey) | POST | /hub/v1/dataevents/key:{externalKey}/rowset | 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 ### PUT Upsert one row in a data extension synchronously by specifying the ID of the target data extension. `PUT /hub/v1/dataevents/{dataExtensionId}/rows/{primaryKey}:{primaryKeyValue}` Operation ID: `upsertRow`. Specify the primary key and value in the URL path. If the target data extension has more than one primary key, specify all the primary keys and values in this format: `{primaryKey1}:{primaryKeyValue1},{primaryKey2}:{primaryKeyValue2}...`. The API doesn’t accept URLs that contain more than 260 characters. Because character-encoding changes can make URLs longer than expected, we recommend that you limit the length of URLs to 200 characters. If your URL exceeds this recommended limit, use [Upsert a Rowset by Using a Data Extension External Key](/docs/marketing/marketing-cloud/references/mc-data_extension_rows_sync?meta=Upsert%2Ba%2BRowset%2Bby%2BUsing%2Ba%2BData%2BExtension%2BExternal%2BKey) or [Upsert a Rowset by Using a Data Extension ID](/docs/marketing/marketing-cloud/references/mc-data_extension_rows_sync?meta=Upsert%2Ba%2BRowset%2Bby%2BData%2BExtension%2BID) instead. These operations include the primary key in the request body rather than the URL path, making the URL shorter so it stays within the limit. #### 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 ``` * `dataExtensionId` (path, string (uuid), required) The unique, system-generated ID for the data extension. * `primaryKey` (path, string, required) The name of a primary key column in the specified data extension. * `primaryKeyValue` (path, string, required) The value of the primary key field in the row to update. #### Request body (required) Media type: `application/json`. Schema: `upsertDataExtensionRowRequestBody`. #### Responses * **200** This response indicates that the request to upsert a row into the data extension succeeded. Media type: `application/json`. Schema: `upsertDataExtensionRowResponseBody`. _Example_ ``` { "keys": { "memberId": "54ce45e4-bd37-4284-bffe-593256ea5bd4" }, "values": { "FirstName": "Mary", "Surname": "Evans-Smythe", "RewardsPoints": 7849, "RewardsTier": 1, "Area": "Islington" } } ``` * **400** This response indicates that there was a problem with the request. Verify that the ID or external key of the data extension is correct, the name and value of the primary key are valid, and the data types of all fields in the request are correct. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "documentation": "", "errorcode": 400, "message": "Primary key 'MemberId' does not exist." } ``` * **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." } ``` ### PUT Upsert one row in a data extension synchronously by specifying the external key of the target data extension. `PUT /hub/v1/dataevents/key:{externalKey}/rows/{primaryKey}:{primaryKeyValue}` Operation ID: `upsertRowByKey`. The API doesn’t accept URLs that contain more than 260 characters. Because character-encoding changes can make URLs longer than expected, we recommend that you limit the length of URLs to 200 characters. If your URL exceeds this recommended limit, use [Upsert a Rowset by Using a Data Extension External Key](/docs/marketing/marketing-cloud/references/mc-data_extension_rows_sync?meta=Upsert%2Ba%2BRowset%2Bby%2BData%2BExtension%2BExternal%2BKey) or [Upsert a Rowset by Using a Data Extension ID](/docs/marketing/marketing-cloud/references/mc-data_extension_rows_sync?meta=Upsert%2Ba%2BRowset%2Bby%2BData%2BExtension%2BID) instead. These operations include the primary key in the request body rather than the URL path, making the URL shorter so it stays within the limit. #### 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, required) The external ID, also known as the customer key, for the data extension. * `primaryKey` (path, string, required) The name of a primary key column in the specified data extension. * `primaryKeyValue` (path, string, required) The value of the primary key field in the row to update. #### Request body (required) Media type: `application/json`. Schema: `upsertDataExtensionRowRequestBody`. #### Responses * **200** This response indicates that the request to upsert a row into the data extension succeeded. Media type: `application/json`. Schema: `upsertDataExtensionRowResponseBody`. _Example: same as PUT /hub/v1/dataevents/{dataExtensionId}/rows/{primaryKey}:{primaryKeyValue} 200 response._ * **400** This response indicates that there was a problem with the request. Verify that the ID or external key of the data extension is correct, the name and value of the primary key are valid, and the data types of all fields in the request are correct. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "documentation": "", "errorcode": 400, "message": "Primary key 'MemberId' does not exist." } ``` * **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." } ``` ### PUT Increase or decrease the value of a data extension column synchronously. For example, you can use this operation to update a customer’s loyalty reward point value after they make a purchase. `PUT /hub/v1/dataevents/{dataExtensionId}/rows/{primaryKey}:{primaryKeyValue}/column/{column}/increment` Operation ID: `incrementColumnValue`. #### 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 ``` * `dataExtensionId` (path, string (uuid), required) The unique, system-generated ID for the data extension. * `primaryKey` (path, string, required) The name of a primary key column in the specified data extension. * `primaryKeyValue` (path, string, required) The value of the primary key field in the row to update. * `column` (path, string, required) The name of the column to increment the value of. * `step` (query, number, required) The amount to increase the value of the specified column by. The default value is `1`. #### Responses * **200** This response indicates that the request to increment the specified column succeeded. Media type: `text/plain`. Schema: `integer`. The response body contains the updated value of the specified field. Type: `integer`. _Example_ ``` 12345 ``` * **400** This response indicates that there was a problem with the request. Verify that the ID or external key of the data extension is correct, the name and value of the primary key are valid, and the data types of all fields in the request are correct. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "documentation": "", "errorcode": 400, "message": "Primary key 'MemberId' does not exist." } ``` * **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." } ``` ### PUT Increase or decrease the value of a data extension column synchronously. For example, you can use this operation to update a customer’s loyalty reward point value after they make a purchase. `PUT /hub/v1/dataevents/key:{externalKey}/rows/{primaryKey}:{primaryKeyValue}/column/{column}/increment` Operation ID: `incrementColumnValueByKey`. #### 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, required) The external ID, also known as the customer key, for the data extension. * `primaryKey` (path, string, required) The name of a primary key column in the specified data extension. * `primaryKeyValue` (path, string, required) The value of the primary key field in the row to update. * `column` (path, string, required) The name of the column to increment the value of. * `step` (query, number, required) The amount to increase the value of the specified column by. The default value is `1`. #### Responses * **200** This response indicates that the request to increment the specified column succeeded. Media type: `text/plain`. Schema: `integer`. The response body contains the updated value of the specified field. Type: `integer`. _Example_ ``` 12345 ``` * **400** This response indicates that there was a problem with the request. Verify that the ID or external key of the data extension is correct, the name and value of the primary key are valid, and the data types of all fields in the request are correct. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "documentation": "", "errorcode": 400, "message": "Primary key 'MemberId' does not exist." } ``` * **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 Upsert one or more rows in a data extension synchronously by specifying the ID of the target data extension. `POST /hub/v1/dataevents/{dataExtensionId}/rowset` Operation ID: `upsertRowset`. #### 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 ``` * `dataExtensionId` (path, string (uuid), required) The unique, system-generated ID for the data extension. #### Request body (required) Media type: `application/json`. Schema: `upsertDataExtensionRowsRequestBody`. #### Responses * **200** This response indicates that the request to upsert one or more rows into the data extension succeeded. Media type: `application/json`. Schema: `upsertDataExtensionRowsResponseBody`. _Example_ ``` [ { "keys": { "MemberId": "38bed58c-9b97-4e95-90bf-8f39e8f539e1" }, "values": { "FirstName": "Raul", "Surname": "Nieto", "RewardsPoints": 23456, "RewardsTier": 3, "Area": "Enfield" } }, { "keys": { "MemberId": "54ce45e4-bd37-4284-bffe-593256ea5bd4" }, "values": { "FirstName": "Mary", "Surname": "Evans", "RewardsPoints": 7849, "RewardsTier": 1, "Area": "Islington" } } ] ``` * **400** This response indicates that there was a problem with the request. Verify that the ID or external key of the data extension is correct, the name and value of the primary key are valid, and the data types of all fields in the request are correct. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "documentation": "", "errorcode": 400, "message": "Primary key 'MemberId' does not exist." } ``` * **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 Upsert one or more rows in a data extension synchronously by specifying the external key of the target data extension. `POST /hub/v1/dataevents/key:{externalKey}/rowset` Operation ID: `upsertRowsetByKey`. #### 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, required) The external ID, also known as the customer key, for the data extension. #### Request body (required) Media type: `application/json`. Schema: `upsertDataExtensionRowsRequestBody`. #### Responses * **200** This response indicates that the request to upsert one or more rows into the data extension succeeded. Media type: `application/json`. Schema: `upsertDataExtensionRowsResponseBody`. _Example: same as POST /hub/v1/dataevents/{dataExtensionId}/rowset 200 response._ * **400** This response indicates that there was a problem with the request. Verify that the ID or external key of the data extension is correct, the name and value of the primary key are valid, and the data types of all fields in the request are correct. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "documentation": "", "errorcode": 400, "message": "Primary key 'MemberId' does not exist." } ``` * **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." } ``` ## Schemas ### upsertDataExtensionRowRequestBody * `values` (_object_) * `{fieldName}` (_string_) The data to update in the data extension. Replace `{fieldName}` with the name of the column. The request can include multiple fields. The data type of each value 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_ ``` { "values": { "FirstName": "Mary", "Surname": "Evans-Smythe", "RewardsPoints": 7849, "RewardsTier": 1, "Area": "Islington" } } ``` ### upsertDataExtensionRowResponseBody * `keys` (_object_) * `{keyName}` (_string_) The primary key field name and value to upsert in the data extension. Replace `{keyName}` with the name of the primary key field. * `values` (_object_) * `{fieldName}` (_string_) The data to update in the data extension. Replace `{fieldName}` with the name of the column. The request can include multiple fields. The data type of each value 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. ### 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. * `message` (_string_) The error message. ### upsertDataExtensionRowsRequestBody Array of `object`. * `keys` (_object_) * `{keyName}` (_string_) The primary key field name and value to upsert in the data extension. Replace `{keyName}` with the name of the primary key field. * `values` (_object_) * `{fieldName}` (_string_) The data to update in the data extension. Replace `{fieldName}` with the name of the column. The request can include multiple fields. The data type of each value 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_ ``` [ { "keys": { "MemberId": "38bed58c-9b97-4e95-90bf-8f39e8f539e1" }, "values": { "FirstName": "Raul", "Surname": "Nieto", "RewardsPoints": 23456, "RewardsTier": 3, "Area": "Enfield" } }, { "keys": { "MemberId": "54ce45e4-bd37-4284-bffe-593256ea5bd4" }, "values": { "FirstName": "Mary", "Surname": "Evans", "RewardsPoints": 7849, "RewardsTier": 1, "Area": "Islington" } } ] ``` ### upsertDataExtensionRowsResponseBody Array of `object`. * `keys` (_object_) * `{keyName}` (_string_) The primary key field name and value to upsert in the data extension. Replace `{keyName}` with the name of the primary key field. * `values` (_object_) * `{fieldName}` (_string_) The data to update in the data extension. Replace `{fieldName}` with the name of the column. The request can include multiple fields. The data type of each value 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.