--- schema_version: "1" id: a1785d05914098781995a29444ab164b137a236c0839171edf81b36363b47a0b title: Bulk Data Ingest collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/marketing-cloud/references/generated-api-specs/mc_rest_bulk_ingest.md canonical_url: https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc_rest_bulk_ingest source_site: developer.salesforce.com content_type: documentation content_hash: 3227e19ebee2e5cee682a3d1db834c07a745b1ac6b62f214f6728a170c6d952b products: - Marketing Cloud Engagement APIs and Programmatic Languages - Marketing Cloud --- Bulk Data Ingest # Bulk Data Ingest Create and manage bulk data ingest jobs to import large volumes of data without compromising performance. To use this API, start by [creating a bulk data ingest job](/docs/marketing/marketing-cloud/references/mc_rest_bulk_ingest?meta=createBulkIngestJob). Next, format the data that you want to ingest in JSON format, with each row in the data extension represented as a JSON object. After that, send your data to API by [staging it](/docs/marketing/marketing-cloud/references/mc_rest_bulk_ingest?meta=stageDataForBulkIngestJob). Finally, [complete data staging](/docs/marketing/marketing-cloud/references/mc_rest_bulk_ingest?meta=completeDataStaging) to add the job to the ingestion queue. When the job is complete, you can [retrieve a summary of the job](/docs/marketing/marketing-cloud/references/mc_rest_bulk_ingest?meta=getBulkDataIngestJobSummary) and the [validation results](/docs/marketing/marketing-cloud/references/mc_rest_bulk_ingest?meta=getBulkDataIngestJobValidationResults). This table lists the use cases that the Bulk Data Ingest API supports. | Supported Use Case | HTTP Verb | URI | | --- | --- | --- | | [Create a bulk ingest job](/docs/marketing/marketing-cloud/references/mc_rest_bulk_ingest?meta=createBulkIngestJob) | POST | /data/v1/bulk/ingest | | [Get the job definition of a bulk data ingest job](/docs/marketing/marketing-cloud/references/mc_rest_bulk_ingest?meta=getBulkIngestJobDefinition) | GET | /data/v1/bulk/ingest/{bulkApiDefinitionId} | | [Update the job definition of an existing bulk data ingest job](/docs/marketing/marketing-cloud/references/mc_rest_bulk_ingest?meta=updateBulkIngestJobDefinition) | PATCH | /data/v1/bulk/ingest/{bulkApiDefinitionId} | | [Delete the job definition of a bulk data ingest job](/docs/marketing/marketing-cloud/references/mc_rest_bulk_ingest?meta=deleteBulkIngestJobDefinition) | DELETE | /data/v1/bulk/ingest/{bulkApiDefinitionId} | | [Stage data for a bulk data ingest job](/docs/marketing/marketing-cloud/references/mc_rest_bulk_ingest?meta=stageDataForBulkIngestJob) | PUT | /data/v1/bulk/ingest/{bulkApiDefinitionId}/batches | | [Complete data staging](/docs/marketing/marketing-cloud/references/mc_rest_bulk_ingest?meta=completeDataStaging) | POST | /data/v1/bulk/ingest/{bulkApiDefinitionId}/batches/complete | | [Get bulk data ingest job summary](/docs/marketing/marketing-cloud/references/mc_rest_bulk_ingest?meta=getBulkDataIngestJobSummary) | GET | /data/v1/bulk/ingest/{bulkApiDefinitionId}/summary | | [Get bulk data ingest job validation summary](/docs/marketing/marketing-cloud/references/mc_rest_bulk_ingest?meta=getBulkDataIngestJobValidationSummary) | GET | /data/v1/bulk/ingest/{bulkApiDefinitionId}/validation/summary | | [Get bulk data ingest job validation results](/docs/marketing/marketing-cloud/references/mc_rest_bulk_ingest?meta=getBulkDataIngestJobValidationResults) | GET | /data/v1/bulk/ingest/{bulkApiDefinitionId}/validation/result | **Version:** v1 ## 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 ### POST Create a bulk data ingestion job. `POST /data/v1/bulk/ingest` Operation ID: `createBulkIngestJob`. Create a bulk data ingestion job. You can create up to 100 jobs in 24 hours. When you create a job, the `jobStatus` is set to `New`, and changes to `Staging` when you [stage data](/docs/marketing/marketing-cloud/references/mc_rest_bulk_ingest?meta=stageDataForBulkIngestJob) for the job. ### Required Scopes To create a bulk data ingest job, your API user must have this permission: * Automation | Automations | Execute (`automations_execute`) #### Request body Media type: `application/json`. Schema: `createBulkIngestJobRequestBody`. #### Responses * **201** The bulk data ingest job was created successfully. Media type: `application/json`. Schema: `createBulkIngestJobResponseBody`. _Example_ ``` { "bulkApiDefinitionId": "e4715e41-7c81-4a9c-a1ce-3dea172f1d3d", "requestId": "03725dd2-cf1e-420d-bd1f-1460244b828e", "resultMessages": [] } ``` * **400** Indicates that the request is invalid. This error can occur when the data extension that you specify in the request body doesn’t exist. Media type: `application/json`. Schema: `bulkIngestErrorResponseBody`. _Example_ ``` { "bulkApiDefinitionId": "00000000-0000-0000-0000-000000000000", "requestId": "20e336d5-ac70-481d-a82e-91cdb0e9a073", "resultMessages": [ { "resultType": "Validation", "resultClass": "Error", "message": "Destination type with the given customer key 'Fake_DE' cannot be found." } ] } ``` * **401** 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: `string`. Type: `string`. _Example_ ``` Account / User not authorized for operation. ``` * **403** 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: `string`. Type: `string`. _Example_ ``` Account / User not authorized for operation. ``` * **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 Get the job definition of a bulk data ingest job. `GET /data/v1/bulk/ingest/{bulkApiDefinitionId}` Operation ID: `getBulkIngestJobDefinition`. Get the job definition of a bulk data ingest job. The response includes the status of the job and its creation and expiration dates. ### Required Scopes To get the job definition of a bulk data ingest job, your API user must have this permission: * Automation | Automations | Execute (`automations_execute`) #### 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 ``` * `bulkApiDefinitionId` (path, string, required) The unique ID of the bulk data ingest job definition. The API returns this ID when you create a bulk data ingest job. #### Responses * **200** The API accepted the request to retrieve the job definition. The API returns this response regardless of whether the job definition exists. Media type: `application/json`. Schema: `getBulkIngestJobDefinitionResponseBody`. _Example: Success_ ``` { "jobDefinition": { "destinationCustomerKey": "34D0A78F-205C-489E-A249-CE83D019C106", "updateType": "Overwrite", "jobExpirationHours": 8, "jobStatus": "New", "jobExpirationDateTime": "2025-08-01T21:57:10", "jobCreateDateTime": "2025-08-01T13:57:10" }, "requestId": "34a259de-d923-4903-b282-b27460f2a62b", "resultMessages": [] } ``` _Example: Failure_ ``` { "requestId": "97ca1c01-4295-4a2c-af78-dbe7ecc83afc", "resultMessages": [ { "resultType": "Operational", "resultClass": "Error", "resultCode": "NotAbleToLocateJobDefinition", "message": "Cannot locate Job Definition for the given Job definition Id : 18a95a80-2535-4dfd-81b0-54cae05fb12b" } ] } ``` * **401** 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: `string`. Type: `string`. _Example_ ``` Account / User not authorized for operation. ``` * **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_ ``` { "message": "Insufficient Privileges to complete this action.", "errorcode": 20002, "documentation": "" } ``` * **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" } ``` ### DELETE Delete the job definition of a bulk data ingest job. `DELETE /data/v1/bulk/ingest/{bulkApiDefinitionId}` Operation ID: `deleteBulkIngestJobDefinition`. Deletes an active bulk data ingest job. When you delete a bulk data ingest job, all of the staged data for the job is deleted. You can only delete a job that has a status of `New` or `Staging`. ### Required Scopes To delete a bulk data ingest job definition, your API user must have this permission: * Automation | Automations | Execute (`automations_execute`) #### 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 ``` * `bulkApiDefinitionId` (path, string, required) The unique ID of the bulk data ingest job definition. The API returns this ID when you create a bulk data ingest job. #### Responses * **200** The API accepted the request to delete the job definition. The API returns this response regardless of whether the job definition exists. Media type: `application/json`. Schema: `deleteBulkIngestJobDefinitionResponseBody`. _Example: Success_ ``` { "requestId": "34a259de-d923-4903-b282-b27460f2a62b", "resultMessages": [] } ``` _Example: Failure_ ``` { "requestId": "fb046802-b101-4897-b37d-f57c5565ccb3", "resultMessages": [ { "resultType": "Operational", "resultClass": "Error", "resultCode": "NotAbleToLocateJobDefinition", "message": "Cannot locate Job Definition for the given Job definition Id : f3fdb1f2-dc75-4dd1-bf5e-ea73cfc8f786" }, { "resultType": "Validation", "resultClass": "Error", "resultCode": "No Job Definition found" } ] } ``` * **400** Indicates that the request is invalid. This error can occur when the job definition that you specify in the request body has a status other than `New` or `Staging`. Media type: `application/json`. Schema: `bulkIngestErrorResponseBody`. _Example_ ``` { "requestId": "4ce7cd47-fcb3-4ee6-b1a2-a05fbf1597d6", "resultMessages": [ { "resultType": "Validation", "resultClass": "Error", "resultCode": "Job Definition cannot be deleted" } ] } ``` * **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_ ``` { "message": "Insufficient Privileges to complete this action.", "errorcode": 20002, "documentation": "" } ``` * **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" } ``` ### PATCH Update the job definition of an existing bulk data ingest job. `PATCH /data/v1/bulk/ingest/{bulkApiDefinitionId}` Operation ID: `updateBulkIngestJobDefinition`. Update the job definition of a bulk data ingest job. You can change the data extension or the update type. Updating the job definition doesn’t reset the expiration time. ### Required Scopes To update the job definition of an existing bulk data ingest job, your API user must have this permission: * Automation | Automations | Execute (`automations_execute`) #### 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 ``` * `bulkApiDefinitionId` (path, string, required) The unique ID of the bulk data ingest job definition. The API returns this ID when you create a bulk data ingest job. #### Request body Media type: `application/json`. Schema: `updateBulkIngestJobDefinitionRequestBody`. #### Responses * **200** The API accepted the request to update the job definition. The API returns this response regardless of whether the job definition exists. Media type: `application/json`. Schema: `getBulkIngestJobDefinitionResponseBody`. _Example: Success_ ``` { "jobDefinition": { "destinationCustomerKey": "34D0A78F-205C-489E-A249-CE83D019C106", "updateType": "AddAndUpdate", "jobExpirationHours": 8, "jobStatus": "New", "jobExpirationDateTime": "2025-08-01T22:50:55", "jobCreateDateTime": "2025-08-01T14:50:55" }, "requestId": "67b97e24-5a5c-4468-9137-5a397bd5dec8", "resultMessages": [] } ``` _Example: Failure_ ``` { "bulkApiDefinitionId": "00000000-0000-0000-0000-000000000000", "requestId": "ae1f0ea2-fb81-4939-b105-65e22b1efee2", "resultMessages": [ { "resultType": "Operational", "resultClass": "Error", "resultCode": "NotAbleToLocateJobDefinition", "message": "Cannot locate Job Definition for the given Job definition Id : 3c875453-7724-447a-b29d-8799efde1f60" } ] } ``` * **401** 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: `string`. Type: `string`. _Example_ ``` Account / User not authorized for operation. ``` * **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_ ``` { "message": "Insufficient Privileges to complete this action.", "errorcode": 20002, "documentation": "" } ``` * **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 Stage data for a bulk data ingest job. `PUT /data/v1/bulk/ingest/{bulkApiDefinitionId}/batches` Operation ID: `stageDataForBulkIngestJob`. Stage data to import in a bulk job. To complete a bulk ingestion job, you must use this resource to stage data at least one time. A data ingestionjob can include up to 1,000 staging requests. The maximum size for a staging payload is 6MB, and requests that are larger than this size are rejected. For best performance, use a payload size between 2MB and 4MB. If the payload contains invalid column names, the entire row is rejected. ### Required Scopes To stage data for a bulk data ingest job, your API user must have this permission: * Automation | Automations | Execute (`automations_execute`) #### 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 ``` * `bulkApiDefinitionId` (path, string, required) The unique ID of the bulk data ingest job definition. The API returns this ID when you create a bulk data ingest job. #### Request body Media type: `application/json`. Schema: `putBulkIngestJobBatchesRequestBody`. #### Responses * **201** The API accepted the request to stage the data. Media type: `application/json`. Schema: `deleteBulkIngestJobDefinitionResponseBody`. _Example_ ``` { "requestId": "bb651230-cfd8-4313-956e-fa444c034489", "resultMessages": [] } ``` * **400** Indicates that the request is invalid. This error can occur if you try to stage data for a job that has a status other than `New` or `Staging`. Media type: `application/json`. Schema: `bulkIngestErrorResponseBody`. _Example_ ``` { "requestId": "94266610-1575-4de1-a851-3d1e276bd6c2", "resultMessages": [ { "resultType": "Validation", "resultClass": "Error", "message": "Invalid Job Definition status for staging data." } ] } ``` * **401** 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: `string`. Type: `string`. _Example_ ``` Account / User not authorized for operation. ``` * **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_ ``` { "message": "Insufficient Privileges to complete this action.", "errorcode": 20002, "documentation": "" } ``` * **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 Complete data staging for a bulk data ingest job. `POST /data/v1/bulk/ingest/{bulkApiDefinitionId}/batches/complete` Operation ID: `completeDataStaging`. ### Required Scopes To complete data staging for a bulk data ingest job, your API user must have this permission: * Automation | Automations | Execute (`automations_execute`) #### 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 ``` * `bulkApiDefinitionId` (path, string, required) The unique ID of the bulk data ingest job definition. The API returns this ID when you create a bulk data ingest job. #### Responses * **200** The API accepted the request to complete the data staging. Media type: `application/json`. Schema: `getBulkIngestJobDefinitionResponseBody`. _Example_ ``` { "jobDefinition": { "destinationCustomerKey": "34D0A78F-205C-489E-A249-CE83D019C106", "updateType": "Overwrite", "jobExpirationHours": 1, "jobStatus": "Queued", "jobExpirationDateTime": "2025-08-04T13:30:33", "jobCreateDateTime": "2025-08-04T12:30:33" }, "requestId": "9e9092e8-8fe9-4929-bb47-2ee3a819cb54", "resultMessages": [] } ``` * **400** Indicates that the request is invalid. This error can occur if you try to complete a job that is expired or has a status other than `Staging`. Media type: `application/json`. Schema: `bulkIngestErrorResponseBody`. _Example_ ``` { "requestId": "2ae85d0e-fffa-4b1b-a8e5-08dcd2f919d9", "resultMessages": [ { "resultType": "Validation", "resultClass": "Error", "message": "Job expired at 8/1/2025 5:07:03 PM server time, cannot accept more data under this job." } ] } ``` * **401** 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: `string`. Type: `string`. _Example_ ``` Account / User not authorized for operation. ``` * **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_ ``` { "message": "Insufficient Privileges to complete this action.", "errorcode": 20002, "documentation": "" } ``` * **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 Get a summary for a completed bulk data ingestion job. `GET /data/v1/bulk/ingest/{bulkApiDefinitionId}/summary` Operation ID: `getBulkDataIngestJobSummary`. View a summary of a completed bulk data ingest job. ### Required Scopes To get the summary of a bulk data ingest job, your API user must have this permission: * Automation | Automations | Read (`automations_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 ``` * `bulkApiDefinitionId` (path, string, required) The unique ID of the bulk data ingest job definition. The API returns this ID when you create a bulk data ingest job. #### Responses * **200** The API accepted the request to retrieve the validation summary. The API returns this response regardless of whether the validation summary exists. Media type: `application/json`. Schema: `getBulkDataIngestJobSummaryResponseBody`. _Example: Success_ ``` { "bulkApiJobSummary": { "duplicateRows": 1053, "restrictedRows": 0, "endDate": "2025-08-01T22:50:55", "errors": 0, "jobStatus": "Completed", "startDate": "2025-08-01T22:50:55", "successfulRows": 123447, "targetKey": "", "importType": "Data Extension", "totalRows": 124500 }, "requestId": "90f96a34-73c0-46f4-9afb-ff6a712b453b", "resultMessages": [] } ``` _Example: Failure_ ``` { "requestId": "2c082b23-f4f6-4c54-a2cc-362ef27b96eb", "resultMessages": [ { "resultType": "Operational", "resultClass": "Error", "resultCode": "NotAbleToLocateJobDefinition", "message": "Cannot locate Job Definition for the given Job definition Id : bfd0ae25-55f5-4d23-a472-335b56c2d229" } ] } ``` * **400** Indicates that the request is invalid. This error can occur if you try to get a summary for a job that is expired or has a status other than `Completed`. Media type: `application/json`. Schema: `bulkIngestErrorResponseBody`. _Example_ ``` { "requestId": "c8f93759-fab7-4d2d-b75a-72072d281e8f", "resultMessages": [ { "resultType": "Validation", "resultClass": "Error", "message": "Invalid job status to retrieve bulk data job Result Summary. Current job status : New" } ] } ``` * **401** 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: `string`. Type: `string`. _Example_ ``` Account / User not authorized for operation. ``` * **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_ ``` { "message": "Insufficient Privileges to complete this action.", "errorcode": 20002, "documentation": "" } ``` * **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 Get the validation summary of a bulk data ingest job. `GET /data/v1/bulk/ingest/{bulkApiDefinitionId}/validation/summary` Operation ID: `getBulkDataIngestJobValidationSummary`. Get a validation summary for a completed bulk data ingest job. ### Required Scopes To get the validation summary of a bulk data ingest job, your API user must have this permission: * Automation | Automations | Read (`automations_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 ``` * `bulkApiDefinitionId` (path, string, required) The unique ID of the bulk data ingest job definition. The API returns this ID when you create a bulk data ingest job. #### Responses * **200** The API accepted the request to retrieve the validation summary. The API returns this response regardless of whether the validation summary exists. Media type: `application/json`. Schema: `getBulkDataIngestJobValidationSummaryResponseBody`. _Example: Success_ ``` { "bulkApiDefinitionId": "4d3644b1-5584-4ca8-8f45-b0b915ddeb05", "jobValidationSummary": [ { "validationErrorType": "InvalidDate", "validationErrorCodeId": 30, "errorsCount": 1 }, { "validationErrorType": "InvalidEmailAddress", "validationErrorCodeId": 18, "errorsCount": 2 } ], "requestId": "b66cb19b-a079-44a8-82f9-a61304837610", "resultMessages": [] } ``` _Example: Failure_ ``` { "bulkApiDefinitionId": "00000000-0000-0000-0000-000000000000", "requestId": "abf6a951-585d-4c94-8136-49b366ea3c53", "resultMessages": [ { "resultType": "Operational", "resultClass": "Error", "resultCode": "NotAbleToLocateJobDefinition", "message": "Cannot locate Job Definition for the given Job definition Id : 733341bd-a88c-4842-9bc9-d648bdd14e57" } ] } ``` * **400** Indicates that the request is invalid. This error can occur if you try to get a validation summary for a job that is expired or has a status other than `Completed`. Media type: `application/json`. Schema: `bulkIngestErrorResponseBody`. _Example_ ``` { "bulkApiDefinitionId": "00000000-0000-0000-0000-000000000000", "requestId": "793cb816-c26f-403c-8449-5e15a8d85738", "resultMessages": [ { "resultType": "Validation", "resultClass": "Error", "message": "Invalid job status to retrieve bulk data job Validation Summary. Current job status : New" } ] } ``` * **401** 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: `string`. Type: `string`. _Example_ ``` Account / User not authorized for operation. ``` * **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_ ``` { "message": "Insufficient Privileges to complete this action.", "errorcode": 20002, "documentation": "" } ``` * **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 Get the validation results of a bulk data ingest job. `GET /data/v1/bulk/ingest/{bulkApiDefinitionId}/validation/result` Operation ID: `getBulkDataIngestJobValidationResults`. Get the validation results for a completed bulk data ingest job. ### Required Scopes To get the validation results of a bulk data ingest job, your API user must have this permission: * Automation | Automations | Read (`automations_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 ``` * `bulkApiDefinitionId` (path, string, required) The unique ID of the bulk data ingest job definition. The API returns this ID when you create a bulk data ingest job. * `page` (query, integer) The page number of the results. If the number of results is greater than the page size, use this parameter to view subsequent pages of results. * `pageSize` (query, integer) The number of results to return on each page of results. #### Responses * **200** The API accepted the request to retrieve the validation results. The API returns this response regardless of whether the validation results exist. Media type: `application/json`. Schema: `getBulkDataIngestJobValidationResultsResponseBody`. _Example: Success_ ``` { "bulkApiDefinitionId": "4d3644b1-5584-4ca8-8f45-b0b915ddeb05", "page": 1, "pageSize": 50, "count": 3, "items": [ { "itemIndex": 0, "validationErrorType": "InvalidEmailAddress", "validationErrorCodeId": 18, "validationErrorDetails": "Invalid Email Address" }, { "itemIndex": 4, "validationErrorType": "InvalidEmailAddress", "validationErrorCodeId": 18, "validationErrorDetails": "Invalid Email Address" }, { "itemIndex": 8, "validationErrorType": "InvalidDate", "validationErrorCodeId": 30, "validationErrorDetails": "Invalid Date" } ], "requestId": "b6bd74ec-e4fd-410b-a3af-848bab7fd60a", "resultMessages": [] } ``` _Example: Failure_ ``` { "bulkApiDefinitionId": "00000000-0000-0000-0000-000000000000", "page": 0, "pageSize": 0, "count": 0, "requestId": "5043a7a5-831d-48d9-bae8-6e94626246c3", "resultMessages": [ { "resultType": "Operational", "resultClass": "Error", "resultCode": "NotAbleToLocateJobDefinition", "message": "Cannot locate Job Definition for the given Job definition Id : 733341bd-a88c-4842-9bc9-d648bdd14e57" } ] } ``` * **400** Indicates that the request is invalid. This error can occur if you try to get validation results for a job that is expired or has a status other than `Completed`. Media type: `application/json`. Schema: `getBulkDataIngestJobValidationResultsResponseBody`. _Example_ ``` { "bulkApiDefinitionId": "00000000-0000-0000-0000-000000000000", "page": 0, "pageSize": 0, "count": 0, "requestId": "47aeea62-15c7-4212-a5e7-220ce4ee0e82", "resultMessages": [ { "resultType": "Validation", "resultClass": "Error", "message": "Invalid job status to retrieve bulk data job Validation Result. Current job status : New" } ] } ``` * **401** 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: `string`. Type: `string`. _Example_ ``` Account / User not authorized for operation. ``` * **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_ ``` { "message": "Insufficient Privileges to complete this action.", "errorcode": 20002, "documentation": "" } ``` * **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 ### createBulkIngestJobRequestBody * `jobDefinition` (_object_) An object that contains information about the job definition. * `destinationCustomerKey` (_string_, required) An external key that you can use to identify the job. * `updateType` (_string_, required) The update type for the job. Allowed values: `AddAndUpdate`, `AddAndDoNotUpdate`, `Overwrite`, `UpdateButDoNotAdd`. * `jobExpirationHours` (_integer_, required) The number of hours to allow data to be staged before the job starts. Maximum: 8. ### createBulkIngestJobResponseBody * `bulkApiDefinitionId` (_string_) The unique ID of the bulk data ingest job definition. * `requestId` (_string_) The unique ID of the request. * `resultMessages` (_bulkIngestionJobResultMessages_) ### bulkIngestErrorResponseBody * `bulkApiDefinitionId` (_string_) The unique ID of the bulk data ingest job definition. * `requestId` (_string_) The unique ID of the request. * `resultMessages` (_bulkIngestionJobResultMessages_) ### 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. ### getBulkIngestJobDefinitionResponseBody * `bulkApiDefinitionId` (_string_) The unique ID of the bulk data ingest job definition. * `jobDefinition` (_object_) An object that contains information about the job definition. * `destinationCustomerKey` (_string_) An external key that you can use to identify the job. * `jobCreateDateTime` (_string (date-time)_) The date and time when the job was created. * `jobExpirationDateTime` (_string (date-time)_) The date and time when the job expires. * `jobExpirationHours` (_integer_) The number of hours to use to stage the data before the job starts. * `jobStatus` (_string_) The status of the job. Allowed values: `Complete`, `Error`, `New`, `Processing`, `Queued`. * `updateType` (_string_) The update type for the job. * `requestId` (_string_) The unique ID of the request. * `resultMessages` (_bulkIngestionJobResultMessages_) ### 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. ### deleteBulkIngestJobDefinitionResponseBody * `requestId` (_string_) The unique ID of the request. * `resultMessages` (_bulkIngestionJobResultMessages_) ### updateBulkIngestJobDefinitionRequestBody * `jobDefinition` (_object_) An object that contains information about the job definition. * `destinationCustomerKey` (_string_, required) An external key that you can use to identify the job. * `updateType` (_string_, required) The update type for the job. Allowed values: `AddAndUpdate`, `AddAndDoNotUpdate`, `Overwrite`, `UpdateButDoNotAdd`. ### putBulkIngestJobBatchesRequestBody * `data` (_array of object_) An array of objects. Each object contains a row of data to stage in the bulk ingestion job. The fields that you specify in the request body must match the fields in the data extension that you’re importing data into. _Example_ ``` { "items": [ { "FirstName": "D’Angelo", "LastName": "Cunningham", "Email": "dcunningham@example.com", "Phone": "+447700123456", "Country": "United Kingdom", "Title": "Salesforce Administrator" }, { "FirstName": "Yasmin", "LastName": "Ahmad", "Email": "yahmad@example.com", "Phone": "+46701740612", "Country": "Sweden", "Title": "Digital Marketer" }, { "FirstName": "Alex", "LastName": "Park", "Email": "apark@example.com", "Phone": "+821033481234", "Country": "South Korea", "Title": "Technical Staff, Government Office" }, { "FirstName": "Salome", "LastName": "Ofudu", "Email": "sofudu@example.com", "Phone": "+14255551234", "Country": "United States", "Title": "Sales Manager" } ] } ``` ### getBulkDataIngestJobSummaryResponseBody * `bulkApiJobSummary` (_object_) * `duplicateRows` (_integer_) The number of duplicate rows in the job. * `restrictedRows` (_integer_) The number of restricted rows in the job. * `endDate` (_string (date-time)_) The date and time when the job ended. * `errors` (_integer_) The number of errors in the job. * `jobStatus` (_string_) The status of the job. Allowed values: `Completed`, `Error`, `New`, `Processing`, `Queued`, `Staging`. * `startDate` (_string (date-time)_) The date and time when the job started. * `successfulRows` (_integer_) The number of successful rows in the job. * `targetKey` (_string_) The key of the target data extension. * `importType` (_string_) The type of data being imported. * `totalRows` (_integer_) The total number of rows in the job. * `requestId` (_string_) The unique ID of the request. * `resultMessages` (_bulkIngestionJobResultMessages_) ### getBulkDataIngestJobValidationSummaryResponseBody * `bulkApiDefinitionId` (_string_) The unique ID of the bulk data ingest job definition. * `jobValidationSummary` (_array of object_) An array of objects. Each object contains information about a category of validation errors. * `validationErrorType` (_string_) The type of validation error. * `validationErrorCodeId` (_integer_) The ID of the validation error. * `errorsCount` (_integer_) The number of errors for the validation error. * `requestId` (_string_) The unique ID of the request. * `resultMessages` (_bulkIngestionJobResultMessages_) ### getBulkDataIngestJobValidationResultsResponseBody * `bulkApiDefinitionId` (_string_) The unique ID of the bulk data ingest job definition. * `page` (_integer_) The page number of the results. * `pageSize` (_integer_) The number of results per page. * `count` (_integer_) The total number of results. * `items` (_array of object_) An array of objects. Each object contains information about a validation error. * `itemIndex` (_integer_) The index of the item in the job. * `validationErrorType` (_string_) The type of validation error. * `validationErrorCodeId` (_integer_) The ID of the validation error. * `validationErrorDetails` (_string_) The details of the validation error. * `requestId` (_string_) The unique ID of the request. * `resultMessages` (_bulkIngestionJobResultMessages_) ### bulkIngestionJobResultMessages An array of result messages. Array of `object`. * `message` (_string_) A description of the result. * `resultClass` (_string_) The class of the result message. Allowed values: `Error`, `Validation`, `Warning`. * `resultType` (_string_) The type of result message. Allowed values: `Error`, `Operational`, `Validation`, `Warning`. * `resultCode` (_string_) A code that indicates the type of error.