REST APIs provide seamless integration between upstream data transmission to Customer Data Platform (CDP) and downstream data retrieval. This integration enables efficient data management and accessibility.

Overview¶

To create user roles, tokens, and other elements through the REST API authentication, you must get access to the Integrations user interface by contacting your CDP administrator.

REST APIs provide an authentication mechanism to securely transmit data to the CDP Tracker API (DWTracker), which is a service endpoint within CDP. The authentication mechanism ensures comprehensive management of user access authorization and streamlines the ingestion of data upstream and reception of processed information downstream. 

Data transmission methods¶

The following are the methods to transfer data to and from CDP:

• Upstream: Use the following methods to transmit data requests to CDP using the /dw/tracker path value:

  • Through a server-side request to facilitate near real-time events based captures or daily data batches from source systems.

  • Through a client-side request to facilitate near real-time web capture through Acquia's proprietary web tracking SDK.

• Downstream: Use the Tracker API (DWTracker) with the /dw/A360 path value to execute a backend request to fetch reconciled unified records from CDP for analysis and decision-making in other source systems.

The following diagram illustrates source systems pushing upstream data to CDP:

The following diagram illustrates source systems pulling downstream data from CDP:

Features ¶

The following are the features of API integration:

• Batch request from source systems: Capture data in batch processes from source systems such as customers, transactions, and transaction items data. 

  You can process the data in the following ways:

  • Bulk processing

  • Incremental processing

  • Event-based incremental processing

    For example, developing API integrations and processing data in intermediate batches rather than sending daily flat files through SFTP. This implementation enhances flexibility, minimizes manual effort, and enables on-demand consulting from the CDP Professional Services team.

• Near real-time customer website activity using the tracking script and SDK: Get a script solution to capture your customer's website activities in real-time. As a first-party cookie, you can integrate with the tracking script that captures customer activities on your website.

  For example, browsing, updating carts, and checkout.

• Export and reconcile profile views: Export reconciled profile views that provide a cohesive and unified view of customer profiles. This is crucial for businesses that focus on personalized marketing strategies and customer relationship management.

  For example, extracting records from the post-processed and consolidated data into a unified customer view to any source system's strategic integration, aiding store vendors, call center operations, Salesforce support, and other customer database systems.

Cloud Service environments¶

Based on your CDP contract, your CDP team provisions different environments, each with URLs that grant access to a variety of API services.

The API Framework provides a structured approach to utilize APIs across cloud and host environments. This approach ensures that each service endpoint is distinct and optimized for specific functions.

The following tables list the endpoints and environments for the APIs for various regions.

Service Authentication Endpoint 

Upstream and Downstream Service Endpoint

The upstream and downstream service endpoints are services that either receive (upstream) or send (downstream) requests for data and operations. 

The endpoints describe the direction of data flow and dependencies in service interactions, which is crucial for system design and optimization.

Endpoint parameters¶

The following are the parameters of API endpoints:

• Path
• Action query string
• Schemes query string

Path¶

Path parameters are easily readable parameters to create clear and concise URLs that indicate the resources they point to and the functions they perform. 

Action query string ¶

The action query string embedded in URLs sends commands to the server. Based on the commands, the server performs specific operations on a resource and modifies the response accordingly. It uses a key-value pair structure, with Action as the key and values as login, extend, and create. The value parameters are introduced by a question mark ? or an ampersand &, depending on their placement within the URL. This action parameter specifies the action that the API performs. 

Schemes query string¶

The Tracker API routes the payload requests through the following schemas:

• a1user
• a1webtag 

These schemas act as the foundational template. The payload is separated into a designated query string for a target landing zone. Subsequently, the payload is transformed to fill the data warehouse entities. By default, the following entities are available:

• Customers
• Event
• Transaction
• Transaction Item

CDP provides the following additional entities. To configure the additional entities, contact Acquia support:

• Address
• Campaign
• Customer Address Xref
• Dispatch
• Message
• Organization
• Product
• Product Category
• Product Category Xref

The following table lists the schemes:

Key points to consider¶

• Not recommended as a standard connector: The API is not designed as a standard connector. You must not use it for universal integration solutions with platforms such as Google Analytics 4, Adobe Analytics, and Meta. It is tailored for specific use cases and might not meet the extensive data integration needs of these platforms. 
• Structured data requirement to upstream data: The upstream data push must adhere to the CDP-specific schema database structure. You must follow the Extract, Load, Transform (ELT) processes to format the data appropriately. This prerequisite ensures data compatibility and effective integration with CDP.
• Pixel authentication mechanism requirements: To utilize the pixel for tracking website events, you need a bycrpt side-server authentication mechanism. This is essential for securely sharing your website's data events. You must ensure that the systems are compatible with this authentication protocol to leverage the real-time activity tracking capabilities.
• Throttling process for data batches: To upload data in batches, CDP provides a throttling process to manage the flow of data. You must adhere to these guidelines to ensure data integration.

Status Response Code¶

The following table outlines the status response code and key scenarios that you might encounter while interacting with the REST API. These include successful token creation, prompt errors from exceeding the maximum number of allowed tokens, handling expired and invalid tokens, addressing login issues, and navigating general server errors.