Prerequisites
- A Data Cloud tenant with an Ingestion API connector and a data stream for the target object. The data stream schema defines the fields the destination can write.
- A customer-managed Salesforce OAuth connection. See Allowing Integrate.io ETL access to my data on Salesforce using Customer-Managed OAuth.
- The connected app behind the connection must include the cdp_ingest_api scope (or the broader cdp_api scope) in its Selected OAuth Scopes.
Connection
Select an existing customer-managed Salesforce OAuth connection or create a new one. Standard Salesforce connections are not supported because Integrate.io’s shared connected app does not carry the Data Cloud ingestion scope. The destination exchanges the connection’s Salesforce token for a short-lived, tenant-scoped Data Cloud token at run time, so no Data Cloud credentials are stored. Salesforce fixes an app’s scopes when the connection is authorized. If your connected app was authorized without the cdp_ingest_api scope, the job fails with a missing-scope error. Add the scope to the app’s Selected OAuth Scopes in Salesforce, then reconnect the connection in Integrate.io.Destination properties
- Ingestion API connector - the name of the Ingestion API connector (data source) in Data Cloud that receives the records.
- Object - the name of the Data Cloud object within that connector to write to.
- Operation type - one of:
- Upsert - inserts new records and updates existing ones matched on the primary key defined in the data stream schema. This is the default.
- Delete - deletes records by primary key.
Field mapping
Map input fields to the field names defined in the target data stream schema.- For Upsert, map the primary key field and every field you want to write. Supported field types are string, number, integer, boolean, date, and date-time. Integrate.io converts date and date-time values to the ISO 8601 format Data Cloud expects.
- For Delete, map exactly one field: the primary key. Data Cloud deletes records by primary key value. Switching the operation type to Delete clears the existing mappings because a delete payload carries only the primary key.
Error handling
The Ingestion API reports a job state only, not per-record results, so this destination has no failed or successful record outputs. Data Cloud checks each value against the type in your uploaded schema. Rows that fail land in the data stream’s Problem Records objects rather than failing the job, so the job still succeeds and those rows do not arrive. Check Problem Records in your Data Cloud tenant after a run.How the job runs
The destination loads records as one bulk ingestion job per component run:- Integrate.io stages the records as CSV files.
- At the end of the run, Integrate.io creates one Data Cloud ingestion job, uploads the staged files, and closes the job.
- Data Cloud processes the closed job on its own schedule. The pipeline job completes without waiting for Data Cloud to finish processing.
A successful pipeline job means the records were handed over, not that they arrived. Integrate.io reports success once Data Cloud accepts the upload, which happens well before Data Cloud finishes processing it. If the ingestion job then fails, or if every row is rejected by schema validation, the pipeline job still shows as successful.To confirm a load actually landed, check the job in Data Cloud Setup > Data Streams, along with the data stream’s Problem Records.
Limits and concurrency
The destination works within the Data Cloud Ingestion API limits:- About 10 GB per run. Integrate.io splits the records into files of up to 100 MB, under Data Cloud’s 150 MB per-file cap, and a single ingestion job accepts at most 100 of them. The split happens automatically on row boundaries and there is nothing to configure, but a run that would exceed the limit fails at the end of the job, after the records have already been prepared. Split larger loads across separate runs.
- One ingestion job at a time per data source and object. If another ingestion job is already loading the same source and object, the run fails immediately, and the error reports how long the blocking job has been running. Data Cloud releases the object only when it finishes processing that job, and it decides when that is, independently of how much data was sent.
- At most 5 concurrent ingestion jobs per Data Cloud tenant. This budget is shared with your other integrations. If the tenant is at the limit, the run waits up to 60 seconds for a free slot, then proceeds and surfaces any error Data Cloud returns.
- At most 20 ingestion jobs created per hour per tenant, also shared with your other integrations.