Developers

API Reference

REST and GraphQL endpoints, polymorphic ingest, webhook receivers. Base URL: https://api.altacee.com

Full interactive reference at api.altacee.com (forthcoming). This page is a placeholder with representative examples.

Authentication

All API requests require a Bearer token in the Authorization header. Tokens are scoped API keys generated in the Altacee dashboard under Settings → API Keys. Each key carries one or more permission scopes: contacts:read, contacts:write, events:ingest, campaigns:read.

Keys are rotatable at any time. Rotate by creating a new key, updating your integrations, then revoking the old key. There is no downtime window required — both keys are valid simultaneously during the transition.

curl -X GET https://api.altacee.com/v1/contacts \
  -H "Authorization: Bearer ac_live_sk_••••••••••••••••" \
  -H "Content-Type: application/json"

A 401 response indicates an invalid or expired token. A 403 response indicates the token lacks the required scope for the requested operation.

Contacts

The Contacts API provides CRUD operations on the Altacee contact record. A contact is uniquely identified by their id (Altacee-assigned UUID) or by any external identifier registered in the identity graph (email, phone, external_id).

# Create or update a contact (upsert by email)
curl -X POST https://api.altacee.com/v1/contacts \
  -H "Authorization: Bearer ac_live_sk_••••••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "phone": "+447700900123",
    "attributes": {
      "first_name": "Alex",
      "plan": "growth",
      "mrr": 299
    },
    "consents": {
      "email_marketing": true,
      "sms_marketing": false
    }
  }'

# Response
{
  "id": "cnt_01hxyz789abc",
  "email": "[email protected]",
  "created_at": "2026-05-22T09:00:00Z",
  "updated_at": "2026-05-22T09:00:00Z"
}

Events

The /v1/events endpoint is a polymorphic ingest API — it accepts any structured JSON event without a predefined schema. Events are associated with a contact via any known identifier. Altacee performs identity resolution automatically; if the identifier matches an existing contact, the event attaches to their record. If not, a new anonymous profile is created and merged on first authenticated event.

Events arrive in segmentation and journey evaluation within 500 ms of ingestion. Batch ingestion is supported via the /v1/events/batch endpoint (up to 1,000 events per request).

# Ingest a single event
curl -X POST https://api.altacee.com/v1/events \
  -H "Authorization: Bearer ac_live_sk_••••••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "order_completed",
    "user_id": "usr_9182",
    "anonymous_id": "anon_abc123",
    "timestamp": "2026-05-22T09:01:23Z",
    "properties": {
      "order_id": "ord_88821",
      "total": 149.00,
      "currency": "USD",
      "items": [
        { "sku": "PRO-12M", "quantity": 1, "price": 149.00 }
      ]
    }
  }'

# Response
{
  "event_id": "evt_01hxyz000xyz",
  "contact_id": "cnt_01hxyz789abc",
  "received_at": "2026-05-22T09:01:23.412Z"
}

Campaigns

Campaign read endpoints expose send metrics, variant performance, and delivery logs. Campaign creation and modification is handled through the Altacee UI or the Journeys API (see full reference at api.altacee.com).

# List recent campaigns
curl -X GET "https://api.altacee.com/v1/campaigns?limit=10&status=sent" \
  -H "Authorization: Bearer ac_live_sk_••••••••••••••••"

# Response (abbreviated)
{
  "data": [
    {
      "id": "cmp_01hxyz111",
      "name": "May re-engagement",
      "status": "sent",
      "channel": "email",
      "sent_at": "2026-05-20T08:00:00Z",
      "stats": {
        "sent": 48320,
        "delivered": 47901,
        "opened": 12103,
        "clicked": 3841
      }
    }
  ],
  "meta": { "total": 42, "page": 1, "limit": 10 }
}

Webhooks

Altacee can push platform events — message delivered, contact unsubscribed, journey goal completed — to any HTTPS endpoint you configure. Webhook payloads are signed with an HMAC-SHA256 signature using a secret you generate at configuration time. Verify the signature on every request before processing.

Failed deliveries are retried with exponential backoff over 24 hours (up to 10 attempts). A delivery is considered failed if the endpoint returns a non-2xx status code or does not respond within 10 seconds. Replay protection is included via a Altacee-Delivery-Id header that is unique per attempt; deduplicate on this value.

# Signature verification (Node.js example)
import crypto from "crypto";

function verifyWebhook(
  payload: string,       // raw request body as string
  signature: string,     // value of Altacee-Signature header
  secret: string         // your webhook secret
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

# Example payload — message.delivered
{
  "id": "evt_01hxyz222",
  "type": "message.delivered",
  "created_at": "2026-05-22T09:05:11Z",
  "data": {
    "contact_id": "cnt_01hxyz789abc",
    "campaign_id": "cmp_01hxyz111",
    "channel": "email",
    "delivered_at": "2026-05-22T09:05:10Z"
  }
}

← Back to docs Integrations Book a demo

# Create or update a contact (upsert by email) curl -X POST https://api.altacee.com/v1/contacts \ -H "Authorization: Bearer ac_live_sk_••••••••••••••••" \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected]", "phone": "+447700900123", "attributes": { "first_name": "Alex", "plan": "growth", "mrr": 299 }, "consents": { "email_marketing": true, "sms_marketing": false } }' # Response { "id": "cnt_01hxyz789abc", "email": "[email protected]", "created_at": "2026-05-22T09:00:00Z", "updated_at": "2026-05-22T09:00:00Z" }

# Ingest a single event curl -X POST https://api.altacee.com/v1/events \ -H "Authorization: Bearer ac_live_sk_••••••••••••••••" \ -H "Content-Type: application/json" \ -d '{ "type": "order_completed", "user_id": "usr_9182", "anonymous_id": "anon_abc123", "timestamp": "2026-05-22T09:01:23Z", "properties": { "order_id": "ord_88821", "total": 149.00, "currency": "USD", "items": [ { "sku": "PRO-12M", "quantity": 1, "price": 149.00 } ] } }' # Response { "event_id": "evt_01hxyz000xyz", "contact_id": "cnt_01hxyz789abc", "received_at": "2026-05-22T09:01:23.412Z" }

# List recent campaigns curl -X GET "https://api.altacee.com/v1/campaigns?limit=10&status=sent" \ -H "Authorization: Bearer ac_live_sk_••••••••••••••••" # Response (abbreviated) { "data": [ { "id": "cmp_01hxyz111", "name": "May re-engagement", "status": "sent", "channel": "email", "sent_at": "2026-05-20T08:00:00Z", "stats": { "sent": 48320, "delivered": 47901, "opened": 12103, "clicked": 3841 } } ], "meta": { "total": 42, "page": 1, "limit": 10 } }

# Signature verification (Node.js example) import crypto from "crypto"; function verifyWebhook( payload: string, // raw request body as string signature: string, // value of Altacee-Signature header secret: string // your webhook secret ): boolean { const expected = crypto .createHmac("sha256", secret) .update(payload) .digest("hex"); return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expected) ); } # Example payload — message.delivered { "id": "evt_01hxyz222", "type": "message.delivered", "created_at": "2026-05-22T09:05:11Z", "data": { "contact_id": "cnt_01hxyz789abc", "campaign_id": "cmp_01hxyz111", "channel": "email", "delivered_at": "2026-05-22T09:05:10Z" } }