Customer Data Platform (CDP) APIs facilitate the Create, Read, Update, Delete (CRUD) operations model with specific considerations for each operation.
CRUD operations
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.
Authorization
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.
Token requests
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".
Bearer token validity
Within the CS, UAT, and PROD environments, bearer tokens are essential for securing three primary types of accounts:
Integration user accounts
WebTag service user accounts
360 Profiles user 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.
Note
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.
Bearer token invocation quantity
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.
Scenario 1
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.
Scenario 2
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:
POST request: Create the first bearer token and set it for 90 days.
DELETE request: Delete the first bearer token after 90 days.
POST request: Invoke creation of the second bearer token and set it for 90 days.
DELETE request: Delete the second bearer token after 90 days.
POST request: Invoke creation of the third bearer token and set it for 90 days.
DELETE request: Wipe all the three bearer tokens after 90 days.
Restart the bearer token cycle.
Scenario 3
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:
POST request: Create the first bearer token and set it for 90 days.
DELETE request: Delete the first bearer token after 90 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 it for 90 days.
DELETE request: Wipe all the three bearer tokens after 90 days.
Restart the bearer token cycle.
Hash access key
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.
Building API requests
JSON development guidelines:
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.
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.
Managing APIs across various source systems
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.
Important
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.
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.
Delete flag
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.
}
]
}
Functions
The following are the functions of Delete flag:
Soft deleted records are automatically removed from the base tables, also known as Data Warehouse (DW). This function is enabled by a standard attribute present in most entities, except for events. The flag attribute is designed to facilitate the soft deletion of records at the initial stage of the data pipeline.
By default, the flag attribute is set to 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.
Soft deleted records are automatically excluded from the tables and views of Persistent Views (PV).
Important
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.
Considerations when using the Deletion functionality
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.
API Policy
Customer Data Platform (CDP) APIs facilitate the Create, Read, Update, Delete (CRUD) operations model with specific considerations for each operation.
CRUD operations
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.
Authorization
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.
Token requests
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".
Bearer token validity
Within the CS, UAT, and PROD environments, bearer tokens are essential for securing three primary types of accounts:
Integration user accounts
WebTag service user accounts
360 Profiles user 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.
Note
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.
Bearer token invocation quantity
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.
Scenario 1
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.
Scenario 2
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:
POST request: Create the first bearer token and set it for 90 days.
DELETE request: Delete the first bearer token after 90 days.
POST request: Invoke creation of the second bearer token and set it for 90 days.
DELETE request: Delete the second bearer token after 90 days.
POST request: Invoke creation of the third bearer token and set it for 90 days.
DELETE request: Wipe all the three bearer tokens after 90 days.
Restart the bearer token cycle.
Scenario 3
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:
POST request: Create the first bearer token and set it for 90 days.
DELETE request: Delete the first bearer token after 90 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 it for 90 days.
DELETE request: Wipe all the three bearer tokens after 90 days.
Restart the bearer token cycle.
Hash access key
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.
Building API requests
JSON development guidelines:
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.
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.
Managing APIs across various source systems
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.
Important
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.
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.
Delete flag
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.
}
]
}
Functions
The following are the functions of Delete flag:
Soft deleted records are automatically removed from the base tables, also known as Data Warehouse (DW). This function is enabled by a standard attribute present in most entities, except for events. The flag attribute is designed to facilitate the soft deletion of records at the initial stage of the data pipeline.
By default, the flag attribute is set to 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.
Soft deleted records are automatically excluded from the tables and views of Persistent Views (PV).
Important
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.
Considerations when using the Deletion functionality
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.
Did not find what you were looking for?
If this content did not answer your questions, try searching or contacting our support team for further assistance.
Did not find what you were looking for?
If this content did not answer your questions, try searching or contacting our support team for further assistance.
Acquia CDP