Getting Started

Use this section to understand the prerequisites required to get started with Data Cloud API libraries and SDKs.

Familiarize Yourself with Data Cloud

Explore the Data Cloud Online Help, if you're unfamiliar with the application.

Set Up Data Cloud

Before you can use Data Cloud APIs, you must configure the application. The steps for setting up the application are included within PDF Guide: Data Cloud Implementation Overview Guide. If you’re using an existing instance, then confirm with your admin that your user profile has permissions to use Data Cloud APIs.

Set Up Data Sources

After you create your Data Cloud instance, you can control the scope of data ingestion and activation from within the instance.

Set up your data sources by creating an app connector in the Data Cloud app. Configure data streams to ingest data for data mapping and segments.

Create a Connected App

Set up a connected app to authenticate and request access to Data Cloud APIs. The connected app enables standard OAuth protocols for authentication and authorization. Follow the instructions in Salesforce Help Create a Connected App, and configure the app as needed. In your connected app, make sure Enable OAuth Settings and necessary OAuth scopes are selected. The possible scopes are:

Perform ANSI SQL queries on Data Cloud data (cdp_query_api): The cdp_query_api scope allows ANSI SQL queries of Data Cloud data on behalf of the user.
Manage Data Cloud profile data (cdp_profile_api): The cdp_profile_api scope allows access to Data Cloud REST API data. Use this scope to manage profile records.
Perform requests at any time (refresh_token): This scope allows a refresh token to be returned when the requesting client is eligible to receive one. With a refresh token, the app can interact with the user’s data while the user is offline.
Manage user data via APIs (api): This scope allows access to the current, logged-in user’s account using APIs, such as REST API and Bulk API 2.0.

Your orgs must be provisioned with Data Cloud licenses and the users must be assigned to appropriate roles for having full access to objects in the Data Cloud. Refer to User Roles and Permission Sets in Data Cloud before setting up the Connected App.

Important

Acquire the Access Token

Send a request for acquiring the Salesforce access token. Here’s how the request is going to look like.

1POST https://login.salesforce.com/services/oauth2/token
2Content-Type : x-www-form-urlencoded
3grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
4&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiIzTVZHOUFPcDRrYnJpWk9JZmg0eWZPQVlQUjFpYzJqb1JDQkhwZFZtaXBXU05sbXNwT2Vib1VtcWdMdHJIcDlRVFRQMGpWc3g0SHlzUW4xLk1SazFyIiwic3ViIjoic3VkaGVlckBvcmdtYWluMi5jb20iLCJhdWQiOiJodHRwOi8vc3VrdW1hci1sdG0uaW50ZXJuYWwuc2FsZXNmb3JjZS5jb20iLCJleHAiOjE2MDQ2Mzc4MTkyNTd9.WkEcmaGj_jhJpyFqXwEUtw-bkeXYuxkqc2c3lkwbGjg3GDo7sStITht_O_dSNanS0xk2q9ARA6Uom-uaiyNw_GGGK5L3jBQjK-ytrGumuJAsujjfSmLdYStxPVnjU2zyuPSWMQJmeDegxDgmeht3UQyluj0q4lX3rayx0Ol-vZfTuzr4YlxmdOKTNrPJCQ8h26uMSPFrQmmqcssrSg1DRgm3kMh15VKM3yZyNAg43EPw1BfncPWIxOmsGt2JxUUclBER3enTLM2cJKr9fDx16Ssesj2UKqXGbwN68gCF5rZxD6yGN5B0VeZIZVJrY5cTtExqBp3Lj8UOcqUj6esyCQ

Refer to OAuth 2.0 JWT Bearer Flow for Server-to-Server Integration for creating a JWT assertion.

Note

Response Format

1{
2"access_token": "00Dxx0000006JFr!AQEAQL7SvQ1t..2yYtyM0jfXtMNriivdMpTYE3mThqATnm5YqPIX.xnzUC45zd0HEIU3tc9GdHLqWOFVprsgszWdYMPRUnOy",
3"scope": "cdpquery api cdpprofile",
4"instance_url": "http://orgmain2.localhost.internal.salesforce.com:6109",
5"id": "http://sukumar-ltm.internal.salesforce.com:6109/id/00Dxx0000006JFrEAM/005xx000001X9hBAAS",
6"token_type": "Bearer"
7}

Use the access token and instance_url to get a Data Cloud token. The instance_url is where you post to get a Data Cloud token.

Exchanging Access Token for Data Cloud Token

Now that you've acquired the Salesforce access token, use this request to get the access token to invoke the APIs.

1
2POST <instance_url>/services/a360/token
3Content-Type : x-www-form-urlencoded
4grant_type=urn:salesforce:grant-type:external:cdp
5&subject_token=<CORE ACCESS TOKEN>
6&subject_token_type=urn:ietf:params:oauth:token-type:access_token

Response Format

1{
2"access_token": "eyJraWQiOiJDT1JFLjAwRHh4MDAwMDAwNkpGci4xNjAzMjM5NzI2NjI5IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJodHRwOi8vc3VrdW1hci1sdG0uaW50ZXJuYWwuc2FsZXNmb3JjZS5jb206NjEwOS9pZC8wMER4eDAwMDAwMDZKRnJFQU0vMDA1eHgwMDAwMDFYOWhCQUFTIiwiYXVkIjoiYTM2MCIsInNjcCI6ImNkcHByb2ZpbGUgY2RwcXVlcnkiLCJuYmYiOjE2MDQ1NTE3NzYsInNmb2lkIjoiMDBEeHgwMDAwMDA2SkZyIiwiaXNzIjoiaHR0cDovL3N1a3VtYXItbHRtLmludGVybmFsLnNhbGVzZm9yY2UuY29tOjYxMDkvIiwic2Z1aWQiOiIwMDV4eDAwMDAwMVg5aEIiLCJleHAiOjE2MDQ1NTkwMjgsImlhdCI6MTYwNDU1MTgzNiwianRpIjoiYjk1ODA1ZDUtM2MzYS00MDNkLWJiNjgtNjBkNTJlNmM4OTBjIiwic2ZhcHBpZCI6IjNNVkc5QU9wNGticmlaT0lmaDR5Zk9BWVBSMWljMmpvUkNCSHBkVm1pcFdTTmxtc3BPZWJvVW1xZ0x0ckhwOVFUVFAwalZzeDRIeXNRbjEuTVJrMXIifQ.GAWqiPpVJoDig-adGtD4d5cO7L7JaIn2mOYH9GyDD7oO7Ayrsnv_k05QRPp-B1gSd4U8lqE_cuC0MTE9L6lzJA",
3"instance_url": "https://a360.cdp.cdp001.dev1-uswest2.aws.sfdc.cl",
4"token_type": "Bearer",
5"issued_token_type": "urn:ietf:params:oauth:token-type:jwt",
6"expires_in": 7191
7}

You need three values from the response:

access_token: The token used to access Data Cloud resources
instance_url: The tenant-specific endpoint where Data Cloud API requests are sent
expires_in: The number of seconds until the token expires and you must reauthenticate. Use this value as part of your access logic, so you can avoid having to repeat the access steps for each call.

Auto-Generated Endpoints

The Data Cloud application assigns a unique, system-generated endpoint to each of your organizations.

After you've acquired your endpoints in Data Cloud, use them for your organization's API calls. No other Data Cloud customer can use your endpoint for their API requests.

You can only use your endpoint with the c360a.salesforce.com endpoint structure.

Data Cloud Reference Guide