Direct API Integration

The most flexible integration approach. Instead of relying on browser-based tracking, your systems send event data directly to rCDP using REST APIs. This gives you full control over what data is captured, when it is sent, and how it is structured — making it ideal for backend, mobile, and non-web environments.

Note: Direct API integration requires development effort but provides maximum control and accuracy.

Direct API integration shifts event tracking from the browser to your backend systems. Instead of capturing user behavior through JavaScript, your application explicitly generates and sends events to rCDP.

Your system becomes the source of truth for tracking data. You define the event, construct the payload, and decide exactly when it is triggered.

Tip: Use Direct API for critical events such as transactions where accuracy is essential.

When to Use Direct API

Backend or server-side event tracking
Mobile or non-browser environments
Precise control over event timing
Custom or headless architectures
Strict data validation requirements

How It Works

Capture Event: Your system detects a business action such as purchase or login
Build Payload: Construct structured JSON with metadata and eventData
Send API Request: POST the payload to the rCDP endpoint
Processing: rCDP validates and ingests the event

API Endpoint

All clickstream events are sent via HTTP POST to the following REST endpoint:

POST https://sandbox.algonomy.com/callback/rest/events/<TENANT_HASH>/<EVENT_NAME>

<TENANT_HASH>

Your unique tenant identifier — provided during Algonomy onboarding

<EVENT_NAME>

The event type string (e.g., eventProduct, eventAddToCart, eventCheckout)

Method

This is a POST API. All event data is sent in the JSON request body. The event name is part of the URL path.

Payload Structure

Each request contains context data and event-specific data.

Context → User, session, device, page
eventData → Business-specific event information

{
"srcId": "WBSTR",
"srcType": "Website",
"clientCorrelatorId": "5DEF0BF530F749AD46F652BDF3",
"requestTime": 1710000000000,
"siteHash": "ASADD5DEF0BF530F749AD46F652BDF3",
"sdkVersion": "2020R3",
"eventType": "eventHomePage",
"userAgent": {
"browserType": "Mozilla/5.0",
"browserVersion": "Firefox/32.0",
"customerDeviceOs": "IOS",
"customerDeviceType": "Mobile",
"timezone": "IST",
"isMobileDevice": "true",
"language": "us-en"
},
"session": {
"sessionKey": "SCBBD2244",
"customerIPAddress": "172.20.0.198",
"referrerSourceURL": "www.google.com",
"referrerName": "google",
"referrerType": "Search Engine",
"city": "Chicago",
"state": "IL",
"country": "US",
"cookieId": "5DEF0BF530F749AD46F652BDF3",
"sessionStartTime": "2015-02-02 23:14 UTC",
"locale": "en_US"
},
"customer": {
"customerCode": 12223433,
"mobile": 9876543211,
"email": "john.smith@example.com",
"uuid": "5DEF0BF530F749AD46F652BDF3"
},
"page": {
"pageKey": 12222,
"pageName": "Category",
"pageUrl": "www.example.com/category.html"
},
"utm": {
"source": "utm_src value",
"medium": "utm_med value",
"campaign": "utm_camp value",
"urlId": "t1_urlid value"
},
"storeId": "1222",
"eventDateTime": "2015-02-02 23:14 UTC",
"eventData": {}
}

Common Fields

Root-level fields provide system-level context. These are common across all event types:

Parameter	Type	Required	Description
srcId	String	Required	Source identifier — e.g., WBSTR (Web Store), MobileApp
srcType	String	Required	Source type — e.g., Shopify, Website Name, App Name
clientCorrelatorId	String	Optional	Unique identifier to correlate events across systems
requestTime	Number	Required	Unix epoch timestamp in milliseconds
userAgent	Object	Optional	Device/browser info — browserType, customerDeviceType, timezone, language, etc.
session	Object	Optional	Session context — sessionKey, customerIPAddress, referrerSourceURL, city, state, country, cookieId, locale
customer	Object	Required	Customer identity — customerCode, email, mobile, uuid
page	Object	Optional	Page context — pageKey, pageName, pageUrl
utm	Object	Optional	UTM tracking — source, medium, campaign, urlId
eventData	Object	Required	Event-specific business data (varies per event type)
eventDateTime	String	Optional	Event date/time in yyyy-MM-dd HH:mm:ss (UTC)
storeId	String	Optional	Physical store identifier (for POS/omnichannel)
siteHash	String	Optional	Site hash provided during onboarding
sdkVersion	String	Optional	SDK version string (e.g., 2020R3)

What This Enables

Full control over event data
Accurate server-side tracking
Cross-platform integration
Improved data reliability
Scalable architecture

Complete API Event Reference

Full examples for every supported event. For the complete official API documentation, see API Reference Guide.

Supported events:

Home - eventHomePage
Search - eventSearch
Category View - eventCategory
Product View - eventProduct
Add to Cart - eventAddToCart
Edit Cart Item - eventCartItemEdit
Checkout - eventCheckout
Transaction Complete - eventTransactionComplete
Transaction Failure - eventTransactionFailure
Customer Create - eventCustomerCreate
Login - eventLogin
Update Profile - eventUpdateProfile
Logout - eventLogout
Forgot Password - eventForgotPassword
Share Wishlist - eventShareWishlist

Home - eventHomePage

Fires when the user lands on the home page.

curl -X POST "https://sandbox.algonomy.com/callback/rest/events/<TENANT_HASH>/eventHomePage" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"srcId": "WBSTR",
"srcType": "Website",
"requestTime": 1710000000000,
"customer": { "email": "user@mail.com", "customerCode": "100" },
"session": { "sessionId": "sess-abc123" },
"page": { "url": "https://example.com", "title": "Home" },
"eventData": {}
}'

Search - eventSearch

Fires when the user performsa search.

Field	Type	Required	Description
searchFacet	string	Yes	Search category or facet
searchString	string	Yes	The search query entered by the user
searchResults	string	Yes	Number of results returned
searchResponseTime	string	No	Response time in milliseconds

curl -X POST "https://sandbox.algonomy.com/callback/rest/events/<TENANT_HASH>/eventSearch" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"srcId": "WBSTR",
"srcType": "Website",
"requestTime": 1710000000000,
"customer": { "email": "user@mail.com" },
"session": { "sessionId": "sess-abc123" },
"page": { "url": "https://example.com/search?q=blue+shoes" },
"eventData": {
"searchFacet": "shoes",
"searchString": "blue shoes",
"searchResults": "42",
"searchResponseTime": "120"
}
}'

Category View - eventCategory

Fires when the user views a product category page.

Field	Type	Required	Description
categoryId	string	Yes	Category ID
parentCategoryId	string	No	Parent category

curl -X POST "https://sandbox.algonomy.com/callback/rest/events/<TENANT_HASH>/eventCategory" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"srcId": "WBSTR",
"srcType": "Website",
"requestTime": 1710000000000,
"customer": { "email": "user@mail.com" },
"session": { "sessionId": "sess-abc123" },
"page": { "url": "https://example.com/category/shoes" },
"eventData": {
"categoryId": "cat001",
"parentCategoryId": "parent001"
}
}'

Product

Product View - eventProduct

Fires when the user views a product detail page.

Field	Type	Required	Description
productId	string	Yes	Unique product identifier
categoryId	string	No	Product category
price	string	Yes	Product price
brandId	string	No	Brand identifier

curl -X POST "https://sandbox.algonomy.com/callback/rest/events/<TENANT_HASH>/eventProduct" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"srcId": "WBSTR",
"srcType": "Website",
"requestTime": 1710000000000,
"customer": { "email": "user@mail.com" },
"session": { "sessionId": "sess-abc123" },
"page": { "url": "https://example.com/product/prod001" },
"eventData": {
"productId": "prod001",
"categoryId": "cat001",
"price": "160.00",
"brandId": "brd001"
}
}'

Cart

Add to Cart - eventAddToCart

Fires when the user adds a product to the cart.

Field	Type	Required	Description
productId	string	Yes	Product identifier
sku	string	No	SKU identifier
categoryId	string	No	Product category
price	string	Yes	Unit price
quantity	string	Yes	Quantity added
totalQuantity	string	No	Total quantity in cart

curl -X POST "https://sandbox.algonomy.com/callback/rest/events/<TENANT_HASH>/eventAddToCart" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"srcId": "WBSTR",
"srcType": "Website",
"requestTime": 1710000000000,
"customer": { "email": "user@mail.com" },
"session": { "sessionId": "sess-abc123" },
"page": { "url": "https://example.com/product/prod001" },
"eventData": {
"productId": "prod001",
"sku": "sku001",
"categoryId": "cat001",
"price": "160.00",
"quantity": "1",
"totalQuantity": "2"
}
}'

Edit Cart Item - eventCartItemEdit

Fires when the user modifies cart item quantity, removes an item, or applies a coupon.

Field	Type	Required	Description
cartId	string	Yes	Cart identifier
cartProducts	array	Yes	Array of cart product objects
cartProducts[].productId	string	Yes	Product identifier
cartProducts[].categoryId	string	No	Category
cartProducts[].productPosition	string	No	Position context (e.g., 'Cart')
cartProducts[].action	string	Yes	Action performed
cartProducts[].quantity	number	Yes	Updated quantity
cartProducts[].productBasePrice	number	Yes	Base price of the product
cartProducts[].tax	number	No	Tax amount
cartProducts[].sku	number	No	SKU identifier
cartProducts[].discount	number	No	Discount applied
cartProducts[].couponCode	string	No	Coupon code if applied

curl -X POST "https://sandbox.algonomy.com/callback/rest/events/<TENANT_HASH>/eventCartItemEdit" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"srcId": "WBSTR",
"srcType": "Website",
"requestTime": 1710000000000,
"customer": { "email": "user@mail.com" },
"session": { "sessionId": "sess-abc123" },
"page": { "url": "https://example.com/cart" },
"eventData": {
"cartId": "cart123",
"cartProducts": [
{
"productId": "814",
"categoryId": "222",
"productPosition": "Cart",
"action": "Edit Cart",
"quantity": 1,
"productBasePrice": 210.00,
"tax": 17.33,
"sku": "sku123",
"discount": 5.00,
"couponCode": "DISCOUNT2024"
}
]
}
}'

Transaction

Checkout - eventCheckout

Fires when the user initiates the checkout process.

Field	Type	Required	Description
transactionId	string	Yes	Transaction identifier
tenderType	string	Yes	Payment method
checkoutType	number	No	Checkout type flag
totalPrice	number	Yes	Total order price
shippingCost	number	No	Shipping cost
discount	number	No	Total discount applied
couponCode	string	No	Coupon code
cartId	string	No	Cart identifier
cartProducts	array	Yes	Cart products
billingInfo	object	Yes	Billing address
shippingInfo	object	Yes	Shipping address

curl -X POST "https://sandbox.algonomy.com/callback/rest/events/<TENANT_HASH>/eventCheckout" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"srcId": "WBSTR",
"srcType": "Website",
"requestTime": 1710000000000,
"customer": { "email": "user@mail.com", "customerCode": "100" },
"session": { "sessionId": "sess-abc123" },
"page": { "url": "https://example.com/checkout" },
"eventData": {
"transactionId": "727",
"tenderType": "cash",
"checkoutType": 0,
"totalPrice": 227.33,
"shippingCost": 0.00,
"discount": 0,
"couponCode": null,
"cartId": "cart123",
"cartProducts": [
{
"productId": "814",
"productPosition": 1,
"action": "Checkout",
"quantity": 1,
"productBasePrice": 210.00,
"tax": 17.33,
"sku": "sku",
"discount": 0.00,
"couponCode": null
}
],
"billingInfo": {
"firstName": "John",
"lastName": "Smith",
"line1": "4/40",
"cityCode": "Chicago",
"stateCode": "IL",
"zip": "60001",
"countryCode": "IN",
"emailAddress": "john.smith@example.com",
"phoneNumber": "1234567890"
},
"shippingInfo": {
"firstName": "John",
"lastName": "Smith",
"line1": "4/40",
"cityCode": "Chicago",
"stateCode": "IL",
"zip": "60001",
"countryCode": "IN",
"emailAddress": "john.smith@example.com",
"phoneNumber": "1234567890"
}
}
}'

Transaction Complete - eventTransactionComplete

Fires when the transaction is successfully completed.

Field	Type	Required	Description
transactionId	string	Yes	Transaction identifier
orderId	string	Yes	Order identifier
tenderType	string	Yes	Payment method
checkoutType	number	No	Checkout type flag
totalPrice	number	Yes	Total order price
shippingCost	number	No	Shipping cost
discount	number	No	Total discount
couponCode	string	No	Coupon code
totalItemCount	number	No	Total number of items
cartProducts	array	Yes	Array of cart product objects
billingInfo	object	Yes	Billing address object
shippingInfo	object	Yes	Shipping address object

curl -X POST "https://sandbox.algonomy.com/callback/rest/events/<TENANT_HASH>/eventTransactionComplete" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"srcId": "WBSTR",
"srcType": "Website",
"requestTime": 1710000000000,
"customer": { "email": "user@mail.com", "customerCode": "100" },
"session": { "sessionId": "sess-abc123" },
"page": { "url": "https://example.com/order-confirmation" },
"eventData": {
"transactionId": "727",
"orderId": "123",
"tenderType": "cash",
"checkoutType": 0,
"totalPrice": 227.33,
"shippingCost": 0.00,
"discount": 0,
"couponCode": null,
"totalItemCount": 1,
"cartProducts": [
{
"productId": "814",
"quantity": 1,
"productBasePrice": 210.00,
"tax": 17.33,
"sku": "sku",
"discount": 0.00,
"couponCode": null
}
],
"billingInfo": {
"firstName": "John",
"lastName": "Smith",
"line1": "4/40",
"cityCode": "Chicago",
"stateCode": "IL",
"zip": "60001",
"countryCode": "IN",
"emailAddress": "john.smith@example.com",
"phoneNumber": "1234567890"
},
"shippingInfo": {
"firstName": "John",
"lastName": "Smith",
"line1": "4/40",
"cityCode": "Chicago",
"stateCode": "IL",
"zip": "60001",
"countryCode": "IN",
"emailAddress": "john.smith@example.com",
"phoneNumber": "1234567890"
}
}
}'

Transaction Failure - eventTransactionFailure

Fires when a transaction fails.

Field	Type	Required	Description
orderId	string	Yes	Order identifier
errorCode	string	Yes	Error code from the payment provider
errorMessage	string	No	Human-readable error message


					curl -X POST "https://sandbox.algonomy.com/callback/rest/events/<TENANT_HASH>/eventTransactionFailure" \
					-H "Authorization: Bearer <ACCESS_TOKEN>" \
					-H "Content-Type: application/json" \
					-d '{
					"srcId": "WBSTR",
					"srcType": "Website",
xxx"totalPrice": 199.99,
xx}
					}'

Identity

Customer Create - eventCustomerCreate

Fires when a new customer registers.

Field	Type	Required	Description
customerCode	string	Yes	Internal customer ID
customerEmailId	string	Yes	Email address
mobileNo	string	No	Mobile number
firstName	string	Yes	First name
lastName	string	Yes	Last name
gender	string	No	Gender (Male/Female/Other)
dob	string	No	Date of birth (MM-DD-YYYY)
joiningDate	string	No	Registration date (MM-DD-YYYY)

curl -X POST "https://sandbox.algonomy.com/callback/rest/events/<TENANT_HASH>/eventCustomerCreate" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"srcId": "WBSTR",
"srcType": "Website",
"requestTime": 1710000000000,
"customer": { "email": "user@mail.com", "customerCode": "100" },
"session": { "sessionId": "sess-abc123" },
"page": { "url": "https://example.com/register" },
"eventData": {
"customerCode": "100",
"customerEmailId": "user@mail.com",
"mobileNo": "9000000000",
"firstName": "John",
"lastName": "Smith",
"gender": "Male",
"dob": "12-30-2000",
"joiningDate": "01-15-2024"
}
}'

Login - eventLogin

Fires when the user logs in.

Field	Type	Required	Description
customerCode	string	Yes	Internal customer ID

curl -X POST "https://sandbox.algonomy.com/callback/rest/events/<TENANT_HASH>/eventLogin" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"srcId": "WBSTR",
"srcType": "Website",
"requestTime": 1710000000000,
"customer": { "email": "user@mail.com", "customerCode": "100" },
"session": { "sessionId": "sess-abc123" },
"page": { "url": "https://example.com/login" },
"eventData": {
"customerCode": "100"
}
}'

Update Profile - eventUpdateProfile

Fires when the user updates their profile.

Field	Type	Required	Description
customerCode	string	Yes	Internal customer ID
firstName	string	No	Updated first name
lastName	string	No	Updated last name
customerEmailId	string	No	Updated email
gender	string	No	Updated gender
dob	string	No	Updated date of birth

curl -X POST "https://sandbox.algonomy.com/callback/rest/events/<TENANT_HASH>/eventUpdateProfile" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"srcId": "WBSTR",
"srcType": "Website",
"requestTime": 1710000000000,
"customer": { "email": "user@mail.com", "customerCode": "100" },
"session": { "sessionId": "sess-abc123" },
"page": { "url": "https://example.com/profile" },
"eventData": {
"customerCode": "100",
"firstName": "Jane",
"lastName": "Smith",
"customerEmailId": "jane@mail.com",
"gender": "Female",
"dob": "05-15-1990"
}
}'

Logout - eventLogout

Fires when the user logs out.

curl -X POST "https://sandbox.algonomy.com/callback/rest/events/<TENANT_HASH>/eventLogout" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"srcId": "WBSTR",
"srcType": "Website",
"requestTime": 1710000000000,
"customer": { "email": "user@mail.com", "customerCode": "100" },
"session": { "sessionId": "sess-abc123" },
"page": { "url": "https://example.com/logout" },
"eventData": {}
}'

Forgot Password - eventForgotPassword

Fires when the user initiates a forgot password request.

Field	Type	Required	Description
customerEmailId	string	Yes	Email address used for password reset

curl -X POST "https://sandbox.algonomy.com/callback/rest/events/<TENANT_HASH>/eventForgotPassword" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"srcId": "WBSTR",
"srcType": "Website",
"requestTime": 1710000000000,
"customer": { "email": "user@mail.com" },
"session": { "sessionId": "sess-abc123" },
"page": { "url": "https://example.com/forgot-password" },
"eventData": {
"customerEmailId": "user@mail.com"
}
}'

Engagement

Share Wishlist - eventShareWishlist

Fires when the user shares a wishlist.

Field	Type	Required	Description
wishlistId	string	Yes	Wishlist identifier
shareMethod	string	No	Sharing method (email, social, etc.)

curl -X POST "https://sandbox.algonomy.com/callback/rest/events/<TENANT_HASH>/eventShareWishlist" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"srcId": "WBSTR",
"srcType": "Website",
"requestTime": 1710000000000,
"customer": { "email": "user@mail.com" },
"session": { "sessionId": "sess-abc123" },
"page": { "url": "https://example.com/wishlist" },
"eventData": {
"wishlistId": "wl001",
"shareMethod": "email"
}
}'

Response Codes

The API returns standard HTTP status codes to indicate the outcome of each request:

Status Code	Meaning	Description
202 Accepted	Success	Event was accepted and queued for processing.
400 Bad Request	Validation Error	The request payload is malformed, missing required fields, or contains invalid data.
401 Unauthorized	Auth Failed	The access token is missing, expired, or invalid. Re-authenticate via OAuth.
403 Forbidden	Access Denied	The token does not have permission for this tenant or resource.
404 Not Found	Invalid Endpoint	The tenant hash or event name in the URL is incorrect.
429 Too Many Requests	Rate Limited	You have exceeded the API rate limit. Implement exponential backoff and retry.
500 Internal Server Error	Server Error	An unexpected error occurred on the server. Retry with backoff.

Best Practices

Validate payload before sending
Use consistent event naming
Retry failed requests with backoff
Ensure consent compliance
Log API responses for debugging

Tip: Use server-side retries to avoid data loss during transient failures.

Troubleshooting

Verify endpoint URL and tenant hash
Check payload structure
Ensure network connectivity
Review API response codes

Note: Most issues occur due to malformed payloads or incorrect event names.

Direct API integration provides maximum flexibility and control over event tracking. It is best suited for backend-driven systems and advanced use cases where precision and scalability are required.

OAuth 2.0 Authentication

The rCDP Clickstream API uses OAuth 2.0 Client Credentials flow. You must obtain an access token before making any API calls.

Obtain an Access Token

Token Request

curl -X POST https://rcdp-us.algonomy.com/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=<YOUR_CLIENT_ID>" \
-d "client_secret=<YOUR_CLIENT_SECRET>"

Token Response

{
"access_token": "eyJhbGciOiJSUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 3600
}

Use the Token in API Calls

Include the token as a Bearer token in the Authorization header of every API call.

client_id: Provided during Algonomy onboarding
client_secret: Provided during Algonomy onboarding
grant_type: Always client_credentials
expires_in: Token validity in seconds (typically 3600)

Token management
Access tokens expire. Cache the token and refresh it before expiry. Never embed client secrets in client-side code — OAuth-based API integration is intended for server-side use only.