REST API

This document provides detailed technical guidance on integrating the HCL CDP REST API to send website or app data to your configured destinations. Use this document alongside an Event Tracking Plan provided by your HCL CDP Customer Success contact to ensure proper and complete implementation.

The HCL CDP REST API serves as a data collection source, enabling you to track customer events across any platform (web, Android, or iOS). Each API request processes your data and routes it to the destinations configured in your HCL CDP Dashboard.

Configure REST API as Source

  1. Navigate to Data Pipeline > Sources, and click +Create New Source.
  2. Select the source type as REST API, and click Proceed.

  3. In the Source name field, add a unique name to the source, and click Create.
  4. Every request must include two headers, x-api-key and x-api-passkey. These keys are displayed in a pop-up when creating the source.
    Note: Copy the keys immediately as they will not be shown again.

Testing the Integration

To test the integration, configure the REST API credentials and click TEST to validate the integration. A success message will confirm the correct configuration.

Payload Testing: A sample payload format for events is provided during the setup process. You can copy the payload and use it while sending API requests.

Making a Request

Supported event types

The REST API source only supports identify and track event types.

Supported HTTP methods

The REST API supports the following HTTP methods:

  • POST: To create or update profiles.
  • DELETE: To remove objects or delete profiles entirely.

Endpoint

Base Endpoint: https://crux.dev.hxcb.now.hclsoftware.cloud/v3/data

POST Request Specifications

Request Structure

A sample payload for ingesting 1 record is given below.

{
    "properties": {
        "param1": "data1",
        "param2": "data2",
        "param3": "data3",
        "paramX": "datax"
    },
    "userid": "CXOOOOOO",
    "eventname": "event name",
    "type": "identify/track"
}

The parameter definition for accepted fields is provided below:

Parameter Type Description
properties Object Event-specific attributes (key-value).
userid required String Mandatory User ID or Anonymous ID.
eventname String Name of the event being tracked.
type String Event type: "identify" or "track".

PII Data handling

For personally identifiable information (PII), include email (lowercase) and mobile (E.164 format) within the properties object.

Example Request

curl --location 'https://crux.dev.hxcb.now.hclsoftware.cloud/v3/data' \
--header 'Content-Type: application/json' \
--header 'x-api-key: xxxx' \
--header 'x-api-passkey: xxxx' \
--data '[
    {
        "properties": {
            "CUSTOMER_ID": "ID000001",
            "CITY": "New York",
            "STATE": "NY",
            "COUNTRY": "USA"
        },
        "eventname": "Account Created",
        "type": "track"
    }
]'
Response Structure
[
    {
        "message": "Data Processed successfully",
        "id": "2510c39011c5be704182423e3a695e91"
    },
    {
        "message": "Invalid input request. Incorrect userid.",
        "id": ""
    }
]
Parameter Type Description
message Object Status of the event processing.
id String User ID or object identifier.

DELETE Request Specifications

Request Structure

A sample payload to delete 3 records is given below:

[
    {
        "properties": {
            "id": "someid"
        },
        "object": "Segment"
    },
    {
        "properties": {
            "id": "anotherid"
        },
        "object": "__profile"
    }
]
Parameter Type Description
properties Object Key-value pair used to identify the target object.
id String Object type (e.g., "Segment", "Lead", "__profile").
  1. Use __profile to delete the entire user profile.
  2. The id parameter must uniquely identify the object.
Example
curl --location --request DELETE 'https://crux.dev.hxcb.now.hclsoftware.cloud/v3/data' \
--header 'Content-Type: application/json' \
--header 'x-api-key: xxxx' \
--header 'x-api-passkey: xxxx' \
--data '[
    {
        "properties": {
            "id": "23423"
        },
        "object": "Segment"
    }
]'
Example Response 
[
    {
        "message": "Segment object deleted successfully",
        "id": "2510c39011c5be704182423e3a695e91"
    },
    {
        "message": "Profile not found.",
        "id": ""
    }
]

Response Code

Status Code Description
200 Success Data processed successfully.
400 Bad Request Payload format is incorrect.
401 Unauthorized Missing or invalid x-api-key or x-api-passkey.
500 Server Error Issue occurred while processing the request.

FAQs

Q1. Which event types are supported with the HCL CDP REST API?

The HCL CDP REST API supports identify and track event types.

Q2. Why am I receiving a 400 Bad Request error?

  1. Verify your payload matches the provided schema.
  2. Ensure userid and other mandatory fields are correctly populated.
  3. Validate your JSON payload using tools like Postman.

Q3. How do I obtain x-api-key and x-api-pass-key?

The API keys are displayed when you create a REST API source. Ensure you save them securely as they will not be displayed again.