ChatCoat PlatformZapier Integration

Official Developer & Partner Review Specification

App ID: 246187Version: 1.0.0

ChatCoat API Documentation — Zapier Integration

This document specifies the OAuth 2.0 authentication architecture, polling triggers, actions, and payload schemas utilized by the official ChatCoat Zapier App (App ID: 246187, Version: 1.0.0). All endpoints run on ChatCoat’s production cloud infrastructure.

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-12T16:48:46.893869Z)
Primary Keys / Deduplication	Unique UUID v4 strings (36-character canonical format)
Infrastructure Ownership	100% first-party owned and operated by ChatCoat

2. OAuth 2.0 Authentication Lifecycle

ChatCoat employs standard OAuth 2.0 with cryptographic workspace isolation. Zapier tokens never cross tenant boundaries.

1User Consent & Authorization

When a user connects ChatCoat in Zapier, they are directed to the Authorization URL. The user authenticates via Clerk on ChatCoat’s secure consent screen and chooses their target workspace.

2Single-Use Code Issuance

Upon consent, ChatCoat redirects back to Zapier’s callback with a single-use authorization code (cca_code_...) valid for 10 minutes.

3Token Exchange & Storage

Zapier exchanges the code via POST /oauth/token for an access token (cca_...) and rolling refresh token (ccr_...). Tokens are SHA-256 hashed in the database and tied directly to the workspace.

4Automated Token Refresh

Access tokens expire after 24 hours (86,400s). Zapier automatically refreshes them in the background using the 180-day rolling refresh token without user disruption.

Supported OAuth 2.0 Scopes

Scope Key	Description	Usage in Zapier
leads:read	Read captured campaign leads and visitor details	Used by "Watch New Leads" Trigger
leads:write	Create, update, and manage lead records	Used by "Create Lead" Action
campaigns:read	Read marketing campaign details and publishing status	Used for dynamic campaign dropdowns
offline_access	Issue long-lived refresh tokens for automated background sync	Maintains persistent live polling in Zapier

3. Production Endpoints Specification

Complete technical specification for every endpoint called by the Zapier integration.

GET/oauth/authorize

OAuth Authorization URL

Browser entry point for Zapier authentication. Validates client parameters and redirects the user to the ChatCoat OAuth consent screen.

Query Parameters:

client_id (string, required): The registered Zapier OAuth client ID.
redirect_uri (string, required): https://zapier.com/dashboard/auth/oauth/return/App246187CLIAPI/
response_type (string, required): Must be code.
state (string, optional): Anti-forgery CSRF token provided by Zapier.
scope (string, optional): Space-delimited requested scopes (e.g. leads:read leads:write offline_access).

Response Behavior:

HTTP 302 Found redirect to the ChatCoat consent screen at https://chatcoat.com/oauth/authorize?....

POST/oauth/token

Token Exchange & Refresh URL

Exchanges a single-use authorization code for bearer access and refresh tokens, or issues a new access token using a valid refresh token. Supports application/x-www-form-urlencoded, application/json, and HTTP Basic Auth.

Request Parameters (grant_type=authorization_code):

grant_type: authorization_code
code: The single-use authorization code received from the authorization redirect.
redirect_uri: Must match the redirect URI sent in the authorization request.
client_id: The Zapier client ID (via form or Basic Auth).
client_secret: The Zapier client secret (if configured).

Response Example (200 OK):

{
  "access_token": "cca_a1b2c3d4e5f6g7h8i9j0...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "ccr_9z8y7x6w5v4u3t2s1r0...",
  "scope": "leads:read leads:write campaigns:read offline_access"
}

POST/oauth/token (or /oauth/refresh)

Refresh Token Flow

Called automatically by Zapier when the access token expires. ChatCoat validates the refresh token and returns a new access token alongside a new rolling refresh token.

Request Parameters (grant_type=refresh_token):

grant_type: refresh_token
refresh_token: The stored refresh token (ccr_...).
client_id: The Zapier client ID.

Response Example (200 OK):

{
  "access_token": "cca_new_token_778899aabbcc...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "ccr_new_rolling_token_112233...",
  "scope": "leads:read leads:write campaigns:read offline_access"
}

GET/oauth/me

Connection Test / User Info URL

Zapier invokes this endpoint during connection setup to test authentication health and display the connected account label in the Zapier dashboard.

Required Headers:

Authorization: Bearer cca_...

Response Example (200 OK):

{
  "id": "2abaf0ee-47ae-4eb2-8a32-7af5e6c476ad",
  "organization_id": "2abaf0ee-47ae-4eb2-8a32-7af5e6c476ad",
  "organization_name": "Acme Marketing Co.",
  "workspace_id": "2abaf0ee-47ae-4eb2-8a32-7af5e6c476ad",
  "workspace_name": "Acme Marketing Co.",
  "user_id": "2d46e609-8ea5-48dd-bd48-b3180b68edab",
  "user_email": "user@example.com",
  "user_name": "Jane Doe"
}

GET/api/leads

Trigger: Watch New Leads

Polling trigger returning captured leads for the authenticated workspace. Ordered reverse-chronologically (created_at.desc(), id.desc()) to guarantee optimal incremental deduplication in Zapier.

Query Parameters:

limit (integer, optional): Maximum items to return. Default: 100, Zapier polling default: 20. Max: 500.
offset (integer, optional): Pagination offset. Default: 0.
platform (string, optional): Filter by platform (e.g., instagram, facebook).
status (string, optional): Filter by lead status (new, contacted, qualified).
campaign_id (string, optional): Filter leads captured from a specific campaign.

Response Example (200 OK — Array of Leads):

[
  {
    "id": "b34bb0eb-c8b5-4cda-85a7-46216da69808",
    "organization_id": "2abaf0ee-47ae-4eb2-8a32-7af5e6c476ad",
    "campaign_id": "a51eb876-5b0f-4b11-9e93-3e49fa6d2bb5",
    "campaign_post_id": "d75a20b2-a37b-41cf-8a93-dd4a27e5f678",
    "platform": "instagram",
    "platform_user_id": "178414000123456",
    "username": "sarah_growth_lead",
    "display_name": "Sarah Connor",
    "source_comment_id": "1adb1b04-5ebc-44f9-9c89-657d65a044c2",
    "source_comment_text": "Please send me the pricing guide and product demo link!",
    "intent": "pricing_inquiry",
    "status": "new",
    "tags": ["zapier-demo", "instagram-lead"],
    "created_at": "2026-09-12T16:48:46.893869Z",
    "updated_at": "2026-09-12T16:48:46.893874Z"
  }
]

Zapier Deduplication Compliance

Every lead item provides a stable UUID in id and an ISO-8601 UTC timestamp ending in Z in created_at. Zapier uses id as the primary deduplication key.

POST/api/leads

Action: Create Lead

Action endpoint used to create a new lead in ChatCoat from Zapier triggers (such as Google Sheets, Facebook Lead Ads, Typeform, or CRM events). Automatically binds the lead to the authenticated workspace.

Request Body Schema (JSON):

platform (string, optional, default: "custom"): Lead origin platform (instagram, facebook, whatsapp, zapier).
username (string, optional): Social handle or username of the lead.
display_name (string, optional): Real name or contact name.
source_comment_text (string, optional): Inbound message or comment text.
intent (string, optional): Detected lead intent (e.g., pricing, support, book).
status (string, optional, default: "new"): Lead workflow status.
campaign_id (string, optional): Foreign key to an existing campaign ID. Blank strings are normalized to null.
tags (array of strings, optional): Custom labels or tracking tags.

Request Example:

{
  "platform": "zapier",
  "username": "alex_retail_pro",
  "display_name": "Alex Miller",
  "source_comment_text": "I am interested in connecting ChatCoat with our CRM system.",
  "intent": "sales_inquiry",
  "status": "new",
  "tags": ["zapier-import", "hot-lead"]
}

Response Example (200 OK — Created Lead):

{
  "id": "d9b758fe-ca73-4976-a4eb-94d83b816892",
  "organization_id": "2abaf0ee-47ae-4eb2-8a32-7af5e6c476ad",
  "campaign_id": null,
  "campaign_post_id": null,
  "platform": "zapier",
  "platform_user_id": null,
  "username": "alex_retail_pro",
  "display_name": "Alex Miller",
  "source_comment_id": null,
  "source_comment_text": "I am interested in connecting ChatCoat with our CRM system.",
  "intent": "sales_inquiry",
  "status": "new",
  "tags": ["zapier-import", "hot-lead"],
  "created_at": "2026-09-13T20:45:12.112345Z",
  "updated_at": "2026-09-13T20:45:12.112349Z"
}

GET/api/campaigns

Dynamic Dropdown / Resource Endpoint

Provides a list of social marketing campaigns belonging to the user's workspace. Powers dynamic dropdown menus in Zapier action and trigger configurations.

Required Headers:

Authorization: Bearer cca_...

Response Example (200 OK — Array of Campaigns):

[
  {
    "id": "a51eb876-5b0f-4b11-9e93-3e49fa6d2bb5",
    "organization_id": "2abaf0ee-47ae-4eb2-8a32-7af5e6c476ad",
    "name": "Summer Promo 2026",
    "description": "Instagram & Facebook discount campaign with comment-to-DM leads",
    "status": "published",
    "scheduled_publish_at": null,
    "published_at": "2026-09-01T10:00:00Z",
    "delete_after_hours": 24,
    "created_at": "2026-08-30T09:25:00Z"
  }
]

4. Error Codes & Response Handling

ChatCoat follows standard RFC 7807 problem details and HTTP status conventions.

Status Code	Error Code	Meaning & Recommended Zapier Handling
200 OK	—	Success. Data returned as expected.
400 Bad Request	invalid_request	Missing required parameters or malformed input payload.
401 Unauthorized	invalid_token	Access token expired or revoked. Zapier triggers automated refresh.
403 Forbidden	access_denied	User does not have permission to access the specified organization.
404 Not Found	not_found	Requested resource or workspace does not exist.
429 Too Many Requests	rate_limit_exceeded	Request limit exceeded. Zapier respects backoff and retries.
500 Server Error	server_error	Internal processing error. Auto-retried by Zapier.

Developer Support & Review Contacts

For questions regarding the ChatCoat Zapier integration, OAuth configuration, or developer assistance, contact our engineering team at support@chatcoat.com.