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

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

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

- 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

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