ChatCoat PlatformREST API Reference

Official Developer & Integration Specification

Version: 1.0.0Protocol: REST / HTTPS

ChatCoat REST API Documentation

Welcome to the official ChatCoat REST API documentation. ChatCoat provides a secure, scalable API for social marketing campaigns, lead capture workflows, content publishing, and multi-tenant workspace automation.

1. Overview & Production Architecture

Production Base URL	https://social-automation-api-8a9h.onrender.com
Authentication	OAuth 2.0 (Authorization Code Grant with Refresh Tokens)
Data Transport / Format	JSON (application/json, UTF-8)
Timestamp Representation	ISO-8601 UTC with "Z" terminator (e.g., 2026-09-14T14:15:30.123456Z)
Primary Keys	Canonical UUID v4 strings (36-character hexadecimal)
Multi-Tenant Isolation	Cryptographically bound to authorized workspace (`organization_id`)

2. Platform Integrations & Automation

ChatCoat maintains pre-built, verified integrations for major workflow automation platforms. For platform-specific setup guides, consult our dedicated integration references:

Make (Integromat) Guide

Documentation for the official Make Custom App. Covers the Watch New Leads polling trigger, Create Lead action, Universal API Call module, and Epoch configurations.

Zapier Integration Guide

Official review specification for Zapier App ID 246187 (v1.0.0). Covers trigger deduplication, dynamic campaign dropdowns, and automated lead capture.

3. Authentication & OAuth 2.0

All API endpoints require a valid Bearer token issued through ChatCoat's OAuth 2.0 Authorization Server.

1Authorization Request

Send users to /oauth/authorize with your client ID, redirect URI, and desired scopes. Users authenticate securely and pick their target workspace.

2Token Exchange

Exchange the single-use authorization code (cca_code_...) at POST /oauth/token for an access token and refresh token.

3API Request Authorization

Attach the access token in the standard HTTP header:
Authorization: Bearer cca_...

4Rolling Token Refresh

Access tokens expire after 24 hours. When providing offline_access, use your refresh token at POST /oauth/token to obtain a new token pair.

Supported OAuth 2.0 Scopes

Scope Key	Description	Grant Permissions
leads:read	View captured leads and lead commentary	Read-only
leads:write	Create, tag, and modify lead records	Read / Write
campaigns:read	List marketing campaigns and post schedules	Read-only
campaigns:write	Create, schedule, or publish social campaigns	Read / Write
comments:read	View incoming social comments and AI intents	Read-only
messages:read	Read WhatsApp and live customer conversations	Read-only
messages:write	Send outbound chat and WhatsApp messages	Write
offline_access	Issue 180-day rolling refresh tokens	Background Access

4. Identity & Workspace Verification (`GET /oauth/me`)

Used to inspect the active token, confirm authorized workspace binding, and verify connection health.

GEThttps://social-automation-api-8a9h.onrender.com/oauth/me

Example Response (200 OK)

{
  "user_id": "user_2t1aBcDeFgHiJkLmNoPq",
  "organization_id": "org_2t1aBcDeFgHiJkLmNoPq",
  "organization_name": "Acme Growth Marketing",
  "client_id": "cca_client_01827492",
  "scopes": [
    "leads:read",
    "leads:write",
    "campaigns:read",
    "offline_access"
  ]
}

5. Leads API

Retrieve captured leads or record new prospect inquiries generated across social media and marketing campaigns.

GET/api/leads

Requires: leads:read

Returns an array of captured leads for the authenticated organization. Records are sorted newest-first by creation date (created_at DESC, id DESC).

Query Parameters

Parameter	Type	Description
limit	integer	Number of records to return (default: 100, max: 500)
offset	integer	Number of records to skip for pagination (default: 0)
campaign_id	string (UUID)	Optional campaign filter
platform	string	Filter by platform (e.g., instagram, facebook, whatsapp, custom)
status	string	Filter by status (new, contacted, qualified, converted, unqualified)

Example Response (200 OK)

[
  {
    "id": "b34bb0eb-c8b5-4cda-85a7-46216da69808",
    "organization_id": "org_2t1aBcDeFgHiJkLmNoPq",
    "campaign_id": "9bf2345e-88c9-4a41-b843-982136e09312",
    "campaign_post_id": null,
    "platform": "instagram",
    "platform_user_id": "17841400000000000",
    "username": "sarah_growth",
    "display_name": "Sarah Miller",
    "source_comment_id": null,
    "source_comment_text": "I am interested in pricing and plans!",
    "intent": "purchase_intent",
    "status": "new",
    "tags": ["pricing-inquiry", "q3-promo"],
    "created_at": "2026-09-12T16:48:46.893869Z",
    "updated_at": "2026-09-12T16:48:46.893869Z"
  }
]

POST/api/leads

Requires: leads:write

Creates a new lead in the authorized workspace. Returns the full LeadResponse entity.

Example Request Body

{
  "platform": "custom",
  "username": "inbound_lead_102",
  "display_name": "Alex Taylor",
  "source_comment_text": "Inquired via marketing website contact form",
  "intent": "demo_request",
  "status": "new",
  "tags": ["web-inbound", "enterprise"],
  "campaign_id": "9bf2345e-88c9-4a41-b843-982136e09312"
}

Example Response (200 OK)

{
  "id": "e9b2c3d4-1234-5678-9abc-def012345678",
  "organization_id": "org_2t1aBcDeFgHiJkLmNoPq",
  "campaign_id": "9bf2345e-88c9-4a41-b843-982136e09312",
  "campaign_post_id": null,
  "platform": "custom",
  "platform_user_id": null,
  "username": "inbound_lead_102",
  "display_name": "Alex Taylor",
  "source_comment_id": null,
  "source_comment_text": "Inquired via marketing website contact form",
  "intent": "demo_request",
  "status": "new",
  "tags": ["web-inbound", "enterprise"],
  "created_at": "2026-09-14T14:15:30.123456Z",
  "updated_at": "2026-09-14T14:15:30.123456Z"
}

6. Campaigns API (`GET /api/campaigns`)

Retrieve social marketing campaigns configured in the workspace.

GEThttps://social-automation-api-8a9h.onrender.com/api/campaigns

Example Response (200 OK)

[
  {
    "id": "9bf2345e-88c9-4a41-b843-982136e09312",
    "organization_id": "org_2t1aBcDeFgHiJkLmNoPq",
    "name": "Summer Product Launch Campaign",
    "status": "published",
    "created_at": "2026-08-20T10:00:00.000000Z",
    "posts": [
      {
        "id": "post_7819234a-1294",
        "platform": "instagram",
        "caption": "Check out our newest release!",
        "status": "published"
      }
    ]
  }
]

7. Error Handling & HTTP Status Codes

ChatCoat returns standard HTTP status codes and structured JSON error responses.

Status Code	Status Name	Description
400	Bad Request	Missing required parameters or malformed payload.
401	Unauthorized	Missing, invalid, or expired Bearer token.
403	Forbidden	Token lacks required scope or workspace permissions.
404	Not Found	Target resource (e.g. campaign or lead ID) does not exist in workspace.
422	Unprocessable Entity	Payload validation failed (type error or schema mismatch).
429	Rate Limit Exceeded	Too many requests; back off and retry using Exponential Backoff.
500	Internal Server Error	An unexpected server error occurred.

Example Error Body

{
  "detail": "Invalid or expired authorization credentials."
}

Developer Support & Verification Assistance

If you need assistance with API access, custom integrations, or review team credentials, contact our engineering team at support@chatcoat.com.

ChatCoat REST API Documentation

1. Overview & Production Architecture

2. Platform Integrations & Automation

3. Authentication & OAuth 2.0

Supported OAuth 2.0 Scopes

4. Identity & Workspace Verification (GET /oauth/me)

5. Leads API

Query Parameters

6. Campaigns API (GET /api/campaigns)

7. Error Handling & HTTP Status Codes

Developer Support & Verification Assistance

4. Identity & Workspace Verification (`GET /oauth/me`)

6. Campaigns API (`GET /api/campaigns`)