Cordial Cordial
Talk to sales
REST API · v2 · api.cordial.io

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 → Full reference (Swagger)
quickstart 
# 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.

  • Base URL: https://api.cordial.io
  • All paths versioned: /v2/…
  • HTTPS only. HTTP requests are rejected.
  • Keys scope to a single account. Rotate any time from the dashboard.
curl · authorization 
# 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)"
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" },
    }),
  }
);
24 resources · 106 endpoints

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.

  • POST
    /v2/contacts Create or upsert a contact
  • GET
    /v2/contacts/{primary_key} Fetch a single contact by primary key
  • PUT
    /v2/contacts/{primary_key} Update a contact
  • PUT
    /v2/contacts/{primary_key}/unsubscribe/{channel} Unsubscribe from a channel
  • GET
    /v2/contacts List or search contacts

Batch Messages

13 endpoints

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

  • POST
    /v2/batchmessages Create a batch message
  • GET
    /v2/batchmessages List batch messages
  • PUT
    /v2/batchmessages/{id} Update a batch message draft
  • PUT
    /v2/batchmessages/{id}/send Send or schedule
  • GET
    /v2/batchmessages/{id} Get a single batch message

Automation Templates

11 endpoints

Send transactional and lifecycle messages from saved templates.

  • GET
    /v2/automationtemplates List automation templates
  • POST
    /v2/automationtemplates Create an automation template
  • PUT
    /v2/automationtemplates/{key} Update an automation template
  • POST
    /v2/automationtemplates/{key}/send Send from a template

Orchestrations

4 endpoints

List, inspect, and trigger journey orchestrations.

  • GET
    /v2/orchestrations List orchestrations
  • GET
    /v2/orchestrations/{orchestrationID} Get a single orchestration
  • GET
    /v2/orchestrations/{orchestrationID}/actions Inspect action nodes
  • POST
    /v2/orchestrations/{orchestrationID}/trigger Trigger an orchestration for a contact

Audiences

1 endpoint

Count contacts matching a criteria object on demand.

  • POST
    /v2/audiencecount Count contacts matching an audience

Contact Activities

2 endpoints

Capture and read event-stream activity for contacts.

  • POST
    /v2/contactactivities Log a custom event
  • GET
    /v2/contactactivities Read events

Contact Lists

7 endpoints

Manage saved subscriber lists.

  • GET
    /v2/accountlists/{id} Get a list
  • POST
    /v2/accountlists Create a list
  • GET
    /v2/accountlists/{id}/count Get current member count
  • PUT
    /v2/accountlists/{id}/clear Clear all members

Contact Attributes

5 endpoints

Define the schema of your contact records.

  • GET
    /v2/accountcontactattributes List attribute definitions
  • POST
    /v2/accountcontactattributes Add an attribute
  • PUT
    /v2/accountcontactattributes/{key} Update an attribute
  • DELETE
    /v2/accountcontactattributes/{key} Delete an attribute

Orders

5 endpoints

Sync transactional commerce data to drive lifecycle messaging.

  • POST
    /v2/orders Add an order
  • GET
    /v2/orders List orders
  • GET
    /v2/orders/{id} Get a single order
  • PUT
    /v2/orders/{id} Update an order

Products

5 endpoints

Maintain the catalog that powers product blocks in messages.

  • POST
    /v2/products Add products
  • GET
    /v2/products List products
  • GET
    /v2/products/{productID} Get a single product
  • PUT
    /v2/products/{productID} Update a product

Supplements

12 endpoints

Custom data tables linked to contacts.

  • GET
    /v2/supplements List supplement tables
  • POST
    /v2/supplements Create a supplement
  • GET
    /v2/supplements/{key} Get a single supplement
  • PUT
    /v2/supplements/{key} Update a supplement
  • PUT
    /v2/supplements/{key}/clear Clear all records

Includes

5 endpoints

Reusable HTML content snippets shared across messages.

  • GET
    /v2/includes List content includes
  • POST
    /v2/includes Create an include
  • GET
    /v2/includes/{key} Get an include
  • PUT
    /v2/includes/{key} Update an include

Data Jobs

5 endpoints

Transform and trigger imports/exports as data jobs.

  • POST
    /v2/datajobs/{key}/transform Run a transformation
  • POST
    /v2/datajobs/{key}/trigger Trigger a transformation
  • GET
    /v2/datajobs/{key}/runs List runs of a recurring job
  • GET
    /v2/datajobs/{key}/runs/{runMarker}/stats Per-run statistics

Imports & Exports

6 endpoints

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

  • POST
    /v2/contactimports Bulk contact import
  • POST
    /v2/contactexports Contact export job
  • POST
    /v2/contactactivityexport Event export job
  • POST
    /v2/ordersimport Order import job
  • POST
    /v2/productimports Product import job
  • POST
    /v2/accountmonitorexport Account log export

Analytics & Reports

2 endpoints

Async export jobs for audience and message analytics.

  • POST
    /v2/audiencetrendsexport Audience trends export
  • POST
    /v2/messageanalyticsexport Message report export

Programs

2 endpoints

Inspect program-level message performance.

  • GET
    /v2/programs/{id}/summary Program summary stats
  • GET
    /v2/programs/{id}/stats Time-series message stats

Jobs

2 endpoints

Track the status of async background work.

  • GET
    /v2/jobs List jobs
  • GET
    /v2/jobs/{id} Get a single job status

Alerts

5 endpoints

Configure and manage account-level alerts.

  • GET
    /v2/alerts List alerts
  • POST
    /v2/alerts Create an alert
  • GET
    /v2/alerts/{id} Get a single alert
  • PUT
    /v2/alerts/{id} Update an alert
Open the full Swagger reference →
Conventions

What every endpoint shares.

  1. 1

    JSON in, JSON out

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

  2. 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. 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.

Need something more conversational for your team? The CLI → wraps the API for terminals. Need agent access? Plug into the MCP server → for AI assistants.

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.

Open API reference → Talk to our team