Cordial REST API — Direct HTTP access to the platform

The Cordial platform, over plain HTTPS.

106 endpoints across 24 resources. HTTPS, HTTP Basic auth, JSON in and out. Build in any language — curl, Go, Python, Ruby, Java, anything that speaks HTTP works on day one.

Quickstart

Copy

# HTTP Basic over HTTPS — your API key as the username, blank password.
curl -u "$CORDIAL_API_KEY:" https://api.cordial.io/v2/contacts/jane@brand.com

# Or use the Authorization header directly:
curl https://api.cordial.io/v2/contacts/jane@brand.com \
  -H "Authorization: Basic $(echo -n "$CORDIAL_API_KEY:" | base64)"

Endpoints

106

Resources

24

Integration

Any language

Format

JSON

Integrate

Live in any stack on day one.

There's nothing to install and nothing to learn. Generate an API key, drop it in the header, and you're talking to the platform from curl, Go, Python, Ruby, Java, or whatever your team already ships — no SDK to vendor, no client library to keep in sync, no version lock-in.

Quickstart

Three patterns power most integrations.

Upsert a contact, log an event, send a message. Every Cordial integration eventually maps to some combination of these three calls.

1. Upsert a contact

Your source of truth pushes a contact in. Cordial merges by primary key.

upsert-contact.ts

// Upsert a contact and trigger downstream automations
const resp = await fetch("https://api.cordial.io/v2/contacts", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Basic ${btoa(`${process.env.CORDIAL_API_KEY}:`)}`,
  },
  body: JSON.stringify({
    channels: { email: { address: "jane@brand.com", subscribeStatus: "subscribed" } },
    attributes: {
      first_name:   "Jane",
      lifetime_val: 2480.5,
      loyalty_tier: "gold",
    },
  }),
});

const contact = await resp.json();
// → { cID: "65a2…", channels: { … }, attributes: { … } }

2. Log a custom event

Behavioral signals flow into the contact's activity stream, where they drive audiences and triggers.

log-event.ts

// Log a custom event — used as orchestration triggers and audience criteria
await fetch("https://api.cordial.io/v2/contactactivities", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Basic ${btoa(`${process.env.CORDIAL_API_KEY}:`)}`,
  },
  body: JSON.stringify({
    email: "jane@brand.com",
    action: "browse",
    properties: {
      product_id: "p_8421",
      category:   "denim",
      price:      78.0,
    },
  }),
});

3. Send a message

Trigger an automation template with per-contact merge data. Cordial handles delivery, tracking, and analytics.

send-message.ts

// Trigger a send from an automation template
await fetch(
  "https://api.cordial.io/v2/automationtemplates/welcome_series/send",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Basic ${btoa(`${process.env.CORDIAL_API_KEY}:`)}`,
    },
    body: JSON.stringify({
      to: { email: "jane@brand.com" },
      mergeData: { firstName: "Jane", couponCode: "WELCOME10" },
    }),
  }
);

Every concept in your Cordial account.

Each resource maps to a tag in the OpenAPI spec. Click through to the Swagger reference for the full payload shape, query params, and error responses.

Contacts

14 endpoints

Create, update, lookup, unsubscribe, and search contacts.

Batch Messages

13 endpoints

Campaign send lifecycle — create, schedule, send, cancel.

Automation Templates

11 endpoints

Send transactional and lifecycle messages from saved templates.

Orchestrations

4 endpoints

List, inspect, and trigger journey orchestrations.

Audiences

1 endpoint

Count contacts matching a criteria object on demand.

Contact Activities

2 endpoints

Capture and read event-stream activity for contacts.

Contact Lists

7 endpoints

Manage saved subscriber lists.

Contact Attributes

5 endpoints

Define the schema of your contact records.

Orders

5 endpoints

Sync transactional commerce data to drive lifecycle messaging.

Products

5 endpoints

Maintain the catalog that powers product blocks in messages.

Supplements

12 endpoints

Custom data tables linked to contacts.

Includes

5 endpoints

Reusable HTML content snippets shared across messages.

Data Jobs

5 endpoints

Transform and trigger imports/exports as data jobs.

Imports & Exports

6 endpoints

Bulk operations on contacts, events, orders, and products.

Analytics & Reports

2 endpoints

Async export jobs for audience and message analytics.

Programs

2 endpoints

Inspect program-level message performance.

Jobs

2 endpoints

Track the status of async background work.

Alerts

5 endpoints

Configure and manage account-level alerts.

Conventions

What every endpoint shares.

  1. JSON in, JSON out
    Send Content-Type: application/json; responses are JSON. Errors return a structured body with a code and message.

  2. Stable resource names
    Resources are keyed by intuitive identifiers — contacts by primary key (often email), supplements and includes by key, audiences and orchestrations by ID.

  3. Async jobs for bulk
    Imports, exports, and analytics extracts are job-based: POST to kick off, then poll /v2/jobs/{id} for status.

When to reach for the REST API

Direct HTTP, when you want it.

Production integrations

Sync contacts from your data warehouse, log commerce events from your storefront, or pipe sends from your transactional service — language-agnostic.

Webhooks & receivers

Wire a webhook from any system into Cordial via POST /v2/contactactivities to turn external signals into events that drive your journeys.

No-runtime environments

Edge functions, iPaaS connectors, Zapier-style platforms, or simple cron-driven scripts — if it speaks HTTP, it speaks Cordial.

Start building on the API.

Generate an API key from your Cordial account, open the Swagger reference, and your first request is one curl away.