Tue Jul 16 2024 17:21:40 GMT+0000 (Coordinated Universal Time)
Customer Data Platform (CDP) APIs facilitate the Create, Read, Update, Delete (CRUD) operations model with specific considerations for each operation.
The following are the CRUD operations:
Create: Create new authorization access to improve service usage and facilitate data flow into the API.
Read: Get access to retrieve existing authorizations. API does not support reading of records and information stored in CDP.
Update: API does not support the Update operation.
Delete: Delete the authorization access. API does not support the requests for record deletion.
Before performing any action, you must authenticate and authorize the API request. This process ensures that the request is valid and the requester possesses the necessary permissions to execute the intended operation. The authorization mechanism inspects the request against security policies and access controls, safeguarding against unauthorized access and modifications.
Authorization tokens secure access and ensure the integrity of interactions across the Customer Staging (CS), User Acceptance Testing (UAT) and PROD (Production) environments within CDP. These tokens are in compliance with security requirements and specific nature of each environment, with all requests characterized by "userType": "CLIENT"
.
Within the CS, UAT, and PROD environments, bearer tokens are essential for securing three primary types of accounts:
The lifespan of these tokens is set as 180 days, which is explicitly reflected in the "expires_in"
attribute as 15599999 seconds in the JSON response from a GET request to verify authentication access. As tokens approach expiration, you must perform token maintenance through one of following methods:
Extend tokens: Prolongs token's validity beyond the initial expiration.
Delete tokens: Deletes a token to end its validity.
Wipe all tokens: Removes all tokens associated with an account.
Acquia does not prescribe a singular methodology for managing bearer token lifecycles. Instead, we furnish the mechanisms to align with your organization's policies. While some companies prefer an annual bearer token cycle, extending the validity well beyond the default 180 days, others opt for a more accelerated approach, choosing to cycle new bearer tokens every 90 days, which falls short of our recommended limit.
Each environment has a limit on active bearer tokens. When you create a new token, it replaces and invalidates the old ones, with only the newest token being valid in the system.
The following table lists the number of tokens in each environment:
Environment | Token |
---|---|
Customer Staging (CS) | 5 |
User Acceptance Testing (UAT) and Production (PROD) | 3 |
This helps you to manage the token consumption and invocation, particularly within the UAT and PROD environments, where the allocation is more restrictive. Ensure a rotation cycle of bearer tokens to maintain secure access to system resources.
The following scenarios demonstrate a flexible token management strategy with varying short-term and long-term validity to meet operational and security requirements, illustrating adaptability in token rotation and renewal.
Create an extended bearer token cycle of 180 days, which involves consuming three bearer tokens over 3 years.
The following are the steps of this scenario:
POST request: Create the first bearer token and set it for 180 days.
POST request: Extend the first bearer token's validity by another 180 days.
DELETE request: Delete the first bearer token after 360 days.
POST request: Invoke creation of the second bearer token and set it for 180 days.
POST request: Extend the second bearer token's validity by another 180 days.
DELETE request: Delete the second bearer token after 360 days.
POST request: Invoke creation of the third bearer token and set for 180 days.
POST request: Extend the third bearer token's validity by another 180 days.
DELETE request: Wipe all the three bearer tokens after 180 days.
Restart the bearer token cycle.
Create an accelerated bearer token cycle with rotations on every 90 days, which involves consuming three bearer tokens over 1 year.
The following are the steps of this scenario:
Implement a combined approach that involves accelerated and extended bearer token cycles, with rotations at 90 and 180 days and three bearer tokens over 1.5 years.
The following are the steps of this scenario:
You can use a hash access key to send a payload from your site to the CDP webtag service endpoint. This key is essential for integration with the webtag service. When the website accesses the DW tracker, the key encrypts your token using Bcrypt, with a 24-hour expiration limit. It also ensures that CDP accepts POST requests. Failure in encryption or exceeding the 24-hour time limit can result in an access block, and multiple attempts can result in a complete block. For more information, see Webtag Service User.
REST API does not support nested JSON structures and must adhere to standardized schemas. You must define each entity, such as customers
, transactions
, transactionItems
, or events
, as a separate object. If you attempt to nest the entities within an object such as a Customer
object, the system displays errors due to incompatibility with the API structure.
{
"customers": [{...}],
"transactions": [{...}]
"transactionItems": [{...}],
"events": [{...}]
}
Acceptable payload | Unacceptable payload |
---|---|
Non-nested JSON | Nested JSON |
API returns one of the following error responses for nested JSON input:
400 Bad Request: The JSON structure is malformed or improperly formatted.
422 Unprocessable Entity: The JSON structure is syntactically correct but semantically incorrect.
415 Unsupported Media Type: The payload format is correct but the schema is not supported.
500 Internal Server Error: The server encountered an unexpected condition that prevented it from completing the request.
When creating a payload, you must define the Source Systems ID
object with the value corresponding to the name of your source system integrated with CDP. This assists CDP to identify the origin of the API calls and ensures that this object is consistently replicated across entities.
If you do not define the source system ID
object, the policy automatically assigns a default name, KFK_0
. This can result in confusion when identifying the source system, particularly when multiple sources are assigned the same default name.
For example:
{
"events": [
{
"SourceSystemID": "YourSourceSystemName"
}
],
"Customers": [
{
"SourceSystemID": "YourSourceSystemName"
}
]
}
Each payload that contains a system timestamp must be formatted as an epoch value. Epoch time, also known as Unix time, represents time as the number of seconds that have elapsed in Coordinated Universal Time (UTC). If a timestamp is a 13-digit number, it likely represents epoch time in milliseconds. For example, epoch time: 16189320000.
{
"events": [
{
"Timestamp": "16189320000"
}
]
}
This represents the number of seconds that have elapsed since the Unix epoch, which is January 1, 1970, at 00:00:00 UTC.
If you need to test or check an epoch value, see Epoch Converter.
You can remove records from CDP with assistance. You can perform a soft delete, which can be processed into a full deletion based on records' updates that need to be removed from the data model.
{
"customers": [
{
"DeleteFlag": false // Set 'true' in this boolean column to mark a record in the Customers table for soft deletion.
}
]
}
The following are the functions of Delete flag:
false
. If you set it to true
, the affected records are marked for soft deletion in the base tables (DW). Following the refresh, the records are removed from the summary tables, known as Business Intelligence (BI), as part of the compaction workflow. This workflow is responsible for the actual deletion of soft deleted records.This functionality takes effect as soon as the base tables (DW) receive the record. To ensure that the record is fully deleted, you must wait for the full refresh to see the record removed from the summary tables.
The Event entity does not include a DeleteFlag
as it is constant.
If the SourceSystemID
is not present in the API payload, the system assigns a default value of KFK_0
. This could lead to accidental removals of customers if multiple client sources submit data through Tracker API to CDP.
When removing a customer from CDP, you must retain their transactional data to preserve historical sales records. Instead of complete deletion, you can label these transactions as Anonymous and Unidentified. Deleting such transactions can affect historical sales figures. Acquia recommends you to retain them and categorize them as "Unidentified" if they are not linked to a customer.
You can only delete records associated with customers having a SourceCustomerNumber or Universally Unique Identifier (UUID) in CDP.
This functionality is effective only when combined with the Customer entity for deletion of associated sub-entities.
You can delete customer addresses only by including Address
or CustomerAddressXref
.
For custom entities such as PetInfo, deletion requires the provision of specific SourceEntityNumbers. Each entity in CDP has its unique SourceEntityNumber column.
Help
If you can't find what you're looking for, then you can reach out to our Support team for further assistance.