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.

API Integration

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 

North America Region
Cloud services	Tenant environment	End points
AWS	DEV Customer Sandbox (CS)	cs-auth.agilone.com/authentication
		cs-auth.agilone.com/token
	User Acceptance Testing (UAT)	auth.agilone.com/authentication
	Production (PROD)	auth.agilone.com/token
GCP	DEV Customer Sandbox (CS)	cs-gcp-auth.agilone.com/authentication
		cs-gcp-auth.agilone.com/token
	User Acceptance Testing (UAT)	auth8.agilone.com/authentication
	Production (PROD)	auth8.agilone.com/token

Europe Region
Cloud services	Tenant environment	End points
AWS	DEV Customer Sandbox (CS)	cs-auth.eu.agilone.com/authentication
		cs-auth.eu.agilone.com/token
	User Acceptance Testing (UAT)	auth.eu.agilone.com/authentication
	Production (PROD)	auth.eu.agilone.com/token

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.

North America Region
Cloud services	Tenant environment	End points
AWS	DEV Customer Sandbox (CS)	cs-api6-green.agilone.com/v2/
	User Acceptance Testing (UAT)	api7.agilone.com/v2/
	Production (PROD)
GCP	DEV Customer Sandbox (CS)	cs-gcp-api6.agilone.com/v2/
	User Acceptance Testing (UAT)	api8.agilone.com/v2/
	Production (PROD)

Europe Region
Cloud services	Tenant environment	End points
AWS	DEV Customer Sandbox (CS)	cs-api6.eu.agilone.com/v2/
	User Acceptance Testing (UAT)	api6.eu.agilone.com/v2/
	Production (PROD)

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. 

Paths
Path	Path value	Description
Tracker	/dw/tracker	Indicates the data warehouse (dw) that points to the service named tracker.
A360	/dw/a360	Indicates the data warehouse (dw) that points to the service named a360.
Authentication	/authentication	Directs the request to the authentication service on the server.
Token	/token	Directs the request to a service or resource on the server that deals with token generation and management.
Version	/v2	Indicates the API version.
TenantId	-	Indicates the numerical identifier correlating to the tenant ID for accessing the account. For example, 1111, 2222, 3333.

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. 

Action query string
Query string	Query string value	Description
Action	?action=login	The question mark ? indicates the beginning of the query string that contains the parameters. This request informs the server to initiate the login process.
	&action=extend	The ampersand & adds multiple key-value pairs to the query string. This action indicates a request to the server to extend the validity of the current token under the specified scheme a1user or a1webtag.
	&action=create	This action specifies a task that a server performs. For example, create a token.

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:

Schemes query string
Scheme	Query string value	Description
a1user	?scheme=a1user	The question mark ? indicates the beginning of the query string that contains the parameters. You can use this scheme exclusively for integration roles and to send server-to-server data. It is ideal for event-based data transmissions such as SMS, application notifications, store beacon interactions, and batch delta requests from source systems such as Enterprise Resource Planning (ERP), Email Service Provider (ESP), and SalesForceDotCom (SFDC).
a1webtag	?scheme=a1webtag	The question mark ? indicates the beginning of the query string that contains the parameters. You can use this scheme for client-side integrations and to to transmit data related to web events such as browsing, updating shopping carts, checkout processes and so on.

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.

Status code	Description
200 OK	This API success code indicates the successful creation of a token.
400 Bad Request	This API error code indicates that you have exceeded the token creation limit and you cannot create a new token. The response payload displays the message: Active sessions for user have reached the set threshold. You must delete the existing tokens to create a new token. For more information, see Deleting Tokens for more information.
401 Unauthorized	This API error code occurs when: Tokens have expired Tokens are inactive Incorrect tokens are used AccessKey is not properly Bcrypted The response payload contains the error code INVALID_TOKEN_ID and the message Invalid token identifier. The system automatically deletes inactive or expired tokens.
403 Forbidden	This API error code occurs when you enter wrong credentials multiple times.
404  Session information not found	This API error code occurs when a token does not exist. Acquia recommends that you use a POST call to generate a new token. Tokens expire by default after every 180 days.
500 Internal Server Error	This API status code indicates a generic server error. Acquia recommends to retry to push the data.