Get Started

Before you can start loading data into your Salesforce CDP org via the API, you must complete the prerequisites, set up authentication, know the API limits that apply to Ingestion API, and more.

Prerequisites

Setup Ingestion API connector: defines the endpoint and payload to consume the data.
Create and Deploy Data Stream: configures ingestion jobs and exposes the API for external consumption.
Configure Connected App: enables external applications to integrate with Salesforce using OAuth.
Request Salesforce CDP access token from Salesforce OAuth Authorization Flows: implement OAuth dance to obtain and refresh access token required for making API requests.

Authentication

The Salesforce CDP Ingestion APIs are a set of RESTful APIs that support all OAuth 2.0 flows supported by other Salesforce REST APIs. In order to load data via the APIs, your connected app requires these scopes:

Access and manage your Salesforce CDP Ingestion API data (cdp_ingest_api).
Access and manage your data (api).
Perform requests on your behalf at any time (refresh_token, offline_access).

After your connected app has the proper scopes, request an access token from Salesforce and exchange it for a Salesforce CDP access token.

Valid Date Format in Records

Use the yyyy-MM-ddTHH:mm:ss.SSSZ format to specify dateTime fields. For example, 2021-07-05T09:31:44.457Z

yyyy is the four-digit year
MM is the two-digit month (01-12)
dd is the two-digit day (01-31)
'T' is a separator indicating that time-of-day follows
HH is the two-digit hour (00-23)
mm is the two-digit minute (00-59)
ss is the two-digit seconds (00-59)
SSS is the optional three-digit milliseconds (000-999)
'Z' is the reference UTC timezone

Ingestion API Limits

Item	Description
API Usage Limits	After each request, your app should check the response code. The HTTP 429 Too Many Requests status code indicates the app should reduce its request frequency.
Bulk lifespan	Any open bulk jobs, state = Open/UploadComplete, older than 7 days are deleted from the ingestion queue.
Files per Job	You can upload one file at a time per bulk job. A job can have a maximum of 100 files.
Payload size	CSV files uploaded via Bulk API have a maximum size of 150 MB. JSON data uploaded via Streaming API have a maximum body size of 200 KB per request

Status Codes and Error Responses

HTTP Response Code	Description
200 OK	Request succeeded.
201 Created	Indicates that the resource was successfully created.
202 Accepted	The request was accepted and the data will be processed asynchronously.
204 No Content	Job was successfully deleted.
400 Bad Request	Server can’t process the request due to client error. Possible causes are a malformed request syntax or invalid request body.
401 Unauthorized	Authentication failed because the JWT is invalid or expired. Refresh the token.
404 Not Found	Client error: the requested resource doesn’t exist.
409 Conflict	Client error: unable to update the job state given its status.
429 Conflict	The user has sent too many requests in a given amount of time. Implement a back-off policy to reduce the number of requests.
500 Internal Server Error	Internal server error. Retry the request.