CampaignOS API Documentation

Welcome to the CampaignOS API documentation. This guide covers everything you can do through the API to manage your marketing automation and customer engagement.

What Can You Do?

With the CampaignOS API you can:

• Manage contacts — create, update, import, merge identities, and track consent
• Build segments — define dynamic audiences based on attributes, behavior, and engagement
• Run campaigns — create multi-channel campaigns with A/B testing across email, push, Telegram, and on-site
• Send messages — dispatch messages across all supported channels
• Capture events — ingest custom events from your website, app, or backend
• Manage forms — create embeddable forms for data capture and lead generation
• Handle conversations — manage inbox threads, auto-replies, and assignments
• Track analytics — query campaign performance, funnels, and attribution
• Configure webhooks — receive real-time notifications when things happen in CampaignOS
• Personalize your website — serve modals, banners, and widgets to targeted audiences

Quick Links

Base URL

All API endpoints are relative to your CampaignOS instance:

https://your-campaignos-domain.com/api

Authentication

Most endpoints require either a session cookie (from signing in) or an API key passed in the Authorization header.

Public endpoints like the tracking script, form submissions, and unsubscribe links do not require authentication.

# API key authentication
curl -H "Authorization: Bearer cos_your_api_key_here" \
  https://your-domain.com/api/workspaces

See Authentication and API Keys for details.

Response Format

All API responses return JSON. Paginated endpoints include a pagination object:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 250,
    "totalPages": 5
  }
}

Error Handling

Errors return an appropriate HTTP status code with a JSON body:

{
  "error": "Validation failed",
  "details": [
    { "field": "email", "message": "Invalid email address" }
  ]
}