Cordial

Datafly Signal delivers your first-party events to Cordial as contact activities — Cordial’s term for behavioural events such as browse, cart, order, and search. Events are sent server-to-server to the Cordial v2 REST API, keyed on the contact’s email address, so they can power cross-channel journeys, browse- and cart-abandonment messaging, and audience segmentation without a client-side Cordial listener on your site.

Prerequisites

• A Cordial account with API access (your account host is typically admin.cordial.io).
• A Cordial API key with permission to write contact activities. Create one under Settings > API Keys in the Cordial platform.
• The IP address of your Signal delivery layer must be added to the API key’s IP allow-list. Cordial binds each API key to specific source IPs at creation time; requests from other IPs are rejected.
• Your contact records keyed by email (Signal sends email as the primary contact identifier).

Configuration

Authentication

Cordial uses HTTP Basic authentication. Signal sends your API key as the username with a blank password, producing an Authorization: Basic <base64("api_key:")> header on every request. You do not configure the header manually — only paste the API key into the API Key field.

Configure in Signal

1. In Signal, open Integrations and add Cordial.
2. Paste your API Key and confirm the API Base URL.
3. Choose a preset:
   • Retail — e-commerce funnel mapped to Cordial’s standard browse, cart, and order activities plus search.
   • B2B / SaaS — lifecycle activities (sign_up, login, browse, search, subscription order).
4. Attach the integration to the pipeline that should deliver to Cordial and publish.

Unmapped events are dropped by default, so only the events in the preset are sent to Cordial.

API Endpoint

Events are delivered as single contact activities:

POST https://api.cordial.io/v2/contactactivities

Each request creates one contact activity. If a contact is found for the supplied identifier it is associated with the activity; otherwise Cordial can create it.

Identity Signals

Signal sends the contact identifier at the payload root:

• email — the primary identifier. Signal trims and lowercases it before sending (Cordial matches contacts by email; no hashing is required — Cordial needs the plaintext email to resolve and message the contact).
• cID — Cordial’s internal contact ID, sent as a fallback identifier when available.

The activity timestamp is sent as ats in ISO 8601 format.

Event Mapping

Signal’s GA4-style event names map to Cordial actions (the a field):

Example

A Product Viewed event from Datafly.js:

datafly.track('Product Viewed', {
  product_id: 'SKU-123',
  product_name: 'Khaki Shirt',
  category: 'Shirts',
  brand: 'Acme',
  price: 9.99
});

is delivered to Cordial as:

{
  "a": "browse",
  "email": "msmith@example.com",
  "ats": "2026-06-06T17:47:43Z",
  "properties": {
    "productID": "SKU-123",
    "name": "Khaki Shirt",
    "category": "Shirts",
    "brand": "Acme",
    "price": 9.99,
    "url": "https://example.com/products/khaki-shirt"
  }
}

An Order Completed event is delivered as an order activity:

{
  "a": "order",
  "email": "msmith@example.com",
  "ats": "2026-06-06T18:02:10Z",
  "properties": {
    "orderID": "ORD-9001",
    "amount": 49.95,
    "currency": "USD",
    "tax": 4.0,
    "shipping": 5.0,
    "items": [
      { "productID": "SKU-123", "name": "Khaki Shirt", "qty": 1, "itemPrice": 9.99 }
    ]
  }
}

Testing

1. Trigger a mapped event on your site (e.g. view a product or complete a test order).
2. In the Cordial platform, open the contact for the test email and view its Contact Activities — the browse / order activity should appear with the timestamp and properties.
3. In Signal’s Event Debugger, confirm the outbound payload shape and a 2xx response from api.cordial.io.

Troubleshooting

• 401 / 403 Unauthorized — the API key is wrong, lacks contact-activity write permission, or the Signal egress IP is not on the key’s IP allow-list. Add the IP under Settings > API Keys.
• 404 Not Found — wrong API Base URL for your account’s pod. Confirm the host in the Cordial platform.
• 400 Bad Request — missing required field (a, the email/cID identifier, or for orders the orderID/amount). Check the event has an email trait and the required properties.
• Activity not on the contact — Cordial could not resolve the email to a contact and contact auto-creation may be disabled for your account; confirm the contact exists or enable creation on activity.