ConnectGain Complete API Documentation¶

Version: 3.0.0 Last Updated: January 2025 Base URL: https://txpaxbxhnvnhsjwwaeoy.supabase.co

Table of Contents¶

Overview
Authentication
API endpoints
Data access (REST API proxy)
Features & Capabilities
Error Handling
Rate Limits & Best Practices

Overview¶

ConnectGain is a comprehensive customer engagement and CRM platform that provides:

Multi-channel messaging (WhatsApp Lite, WhatsApp Cloud, Facebook Messenger, Instagram, Telegram, TikTok, Shopify Inbox, Bulk Email, LinkedIn)
CRM functionality (Contacts, Deals, Companies, Pipelines)
Conversation management (Inbox, Messages, Assignments)
Automation (Bot Flows, Automation Rules, Templates)
Campaign management (Broadcast campaigns, SMS, WhatsApp)
Project management (Projects, Tasks, Milestones)
Analytics & Reporting (Dashboard widgets, Performance metrics)
Team collaboration (Organizations, Users, Permissions, Invitations)
Webhooks (Event-driven integrations)
API integrations (External system integration via API keys)

API Types¶

ConnectGain provides two kinds of API, both authenticated with an organization API key:

Endpoints - purpose-built operations: send a message, create a lead, search contacts, control a bot
REST API proxy - filtered read/write access to your organization's records (contacts, deals, conversations, messages, tasks, projects, companies, templates, channels)

Authentication¶

Every request carries your organization's API key in the X-API-Key header:

X-API-Key: cg_abc123def456...

API keys are created in Settings → API Keys, or by a signed-in owner or admin via the Generate API Key endpoint.

Key Features: - Prefixed with cg_ for easy identification - Scoped to the organization that created it — every request only ever sees that organization's data - Can have custom permissions (send messages, read messages, etc.) - Can have expiration dates - Shown once on creation; store it securely

The ConnectGain app itself calls the same endpoints with the signed-in user's session. That path is not part of the public API; integrations always use an API key.

API endpoints¶

Endpoints are purpose-built operations: sending messages, searching and importing records, controlling bots, and managing your organization.

Message Sending Functions¶

WhatsApp Lite - Send Message¶

Send messages via WhatsApp Lite (AppGain integration).

Endpoint: POST /functions/v1/whatsapp-lite-send

Headers:

X-API-Key: cg_your_api_key
Content-Type: application/json

Request Body:

{
 "to": "201000000002",
 "message": "Hello from ConnectGain!",
 "organizationId": "org-uuid",
 "contactName": "John Doe",
 "from": "AIBot",
 "conversationId": "conv-uuid"
}

Parameters: - to (required): Phone number in international format (e.g., "201000000002") - message (required): Message content (max 4096 characters) - organizationId (required): Your ConnectGain organization UUID - contactName (optional): Contact name for display - from (optional): Sender name for UI display - conversationId (optional): Existing conversation ID

Response:

{
 "success": true,
 "result": {
 "messageId": "message_id",
 "id": "message_id"
 },
 "conversationId": "conv-uuid",
 "contactId": "contact-uuid"
}

Curl Example:

curl -X POST https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/whatsapp-lite-send \
 -H "X-API-Key: cg_your_api_key" \
 -H "Content-Type: application/json" \
 -d '{
 "to": "201000000002",
 "message": "Hello!",
 "from": "AIBot"
 }'

WhatsApp Cloud - Send Message¶

Send messages via WhatsApp Cloud API (Meta).

Endpoint: POST /functions/v1/whatsapp-cloud-send

Request Body:

{
 "to": "phone_number",
 "message": "Hello via WhatsApp Cloud!",
 "conversationId": "conv-uuid",
 "accessToken": "facebook_access_token",
 "phoneNumberId": "phone_number_id"
}

Facebook Messenger - Send Message¶

Send messages via Facebook Messenger.

Endpoint: POST /functions/v1/messenger-send

Request Body:

{
 "to": "user_psid",
 "message": "Hello via Messenger!",
 "conversationId": "conv-uuid",
 "accessToken": "messenger_access_token"
}

Instagram - Send Message¶

Send direct messages via Instagram.

Endpoint: POST /functions/v1/instagram-send

Request Body:

{
 "to": "instagram_user_id",
 "message": "Hello via Instagram!",
 "conversationId": "conv-uuid"
}

Telegram - Send Message¶

Send messages via Telegram.

Endpoint: POST /functions/v1/telegram-send

Request Body:

{
 "to": "telegram_chat_id",
 "message": "Hello via Telegram!",
 "conversationId": "conv-uuid"
}

TikTok - Send Message¶

Send messages via TikTok. The recipient is resolved server-side from the conversation's stored TikTok conversation ID — no recipient identifier is passed in the request body.

Endpoint: POST /functions/v1/tiktok-send

Request Body:

{
 "conversationId": "conv-uuid",
 "message": "Hello via TikTok!",
 "media_urls": ["https://cdn.example.com/uploads/photo.jpg"],
 "reply_to_external_id": "optional-tiktok-message-id"
}

Notes: - Exactly one of message or a single-element media_urls must be provided (TikTok does not support combined text + media in one message, and only one attachment per message). - media_urls entries must point to this project's own Supabase Storage — arbitrary external URLs are rejected.

SMS - Send Message¶

Send a one-off SMS. Unlike every other channel here, SMS has no inbound webhook, so there is no existing conversation to reply into — every send is proactive, to a to the caller supplies.

Endpoint: POST /functions/v1/sms-send

Request Body:

{
 "to": "+201000000003",
 "message": "Hello via SMS!",
 "channelAccountId": "channel-uuid"
}

Notes: - to must be full E.164 with a + and country code — a local number is rejected rather than guessed at. - message max 4096 characters (the same limit every other channel enforces — not a real SMS-segment count, which Appgain determines on its own side).

channelAccountId (the id of a channel_accounts row of type SMS) is optional. It is required only when the organization has more than one active SMS channel; with exactly one, it is used automatically. It selects which channel the sent message is logged against — not which credentials send: those come from the channel's own settings if configured there, otherwise from the organization's Appgain credentials.
With zero active SMS channels, the message still sends (using the organization's own credentials) but is not logged to any conversation — there is nothing to attach it to.
SMS conversations exist but are hidden from the unified inbox; find them via the contact's own message history.

Search & Import Functions¶

Search Contacts¶

Advanced contact search with filtering by name, phone, email, tags, and company.

Endpoint: POST /functions/v1/search-contacts

Headers:

X-API-Key: cg_your_api_key
Content-Type: application/json

Request Body:

{
 "searchTerm": "John",
 "tags": ["customer", "vip"],
 "dealStatus": "open"
}

Parameters: - searchTerm (optional): Search term for name, phone, email, or tags - tags (optional): Array of tags to filter by - dealStatus (optional): Filter by deal status ("open", "closed", etc.)

Response:

{
 "contacts": [
 {
 "id": "uuid",
 "first_name": "John",
 "last_name": "Doe",
 "phones": ["+1234567890"],
 "emails": ["john@example.com"],
 "tags": ["customer"],
 "company": {
 "id": "uuid",
 "name": "Acme Inc"
 },
 "assignee": {
 "id": "uuid",
 "first_name": "Agent",
 "last_name": "Name"
 }
 }
 ],
 "count": 1
}

Features: - Searches across first name, last name, full name, reversed name - Phone number matching (with country code variations) - Email matching (full email or username part) - Tag matching - Company name matching - Returns up to 2000 results - Includes related company and assignee data

Search Companies¶

Search companies by name, domain, email, phone, city, industry, or description.

Endpoint: POST /functions/v1/search-companies

Request Body:

{
 "searchTerm": "Acme",
 "country": "US"
}

Parameters: - searchTerm (optional): Search term for company fields - country (optional): Filter by country (use __no_country__ for null countries)

Response:

{
 "companies": [
 {
 "id": "uuid",
 "name": "Acme Inc",
 "domain": "acme.com",
 "email": "contact@example.com",
 "phone": "+1234567890",
 "city": "New York",
 "country": "US",
 "industry": "Technology"
 }
 ]
}

Import Contacts (CSV)¶

Bulk import contacts from CSV data.

Endpoint: POST /functions/v1/import-contacts

Request Body:

{
 "csvData": "First Name,Last Name,Email,Phone Number\nJohn,Doe,john@example.com,+1234567890",
 "organizationId": "org-uuid"
}

Supported CSV Fields: - First Name, Last Name - Email, Phone Number, Mobile Phone Number - Company name, Job Title - Lead Status, Lifecycle Stage - Street Address, City, State/Region, Postal Code, Country/Region

Response:

{
 "success": true,
 "imported": 10,
 "skipped": 2,
 "errors": []
}

Import Companies (CSV)¶

Bulk import companies from CSV data.

Endpoint: POST /functions/v1/import-companies

Request Body:

{
 "csvData": "Company name,Company Domain Name,Phone Number,City,Country/Region\nAcme Inc,acme.com,+1234567890,New York,US",
 "organizationId": "org-uuid"
}

Supported CSV Fields: - Company name, Company Domain Name, Website URL - Industry, Phone Number - City, State/Region, Country/Region, Street Address, Postal Code - Annual Revenue, Number of Employees - LinkedIn Company Page, Facebook Company Page, Twitter Handle - Logo URL, Description - Lifecycle Stage, Lead Status, Company owner

Import Kommo Leads¶

Import leads from Kommo CRM.

Endpoint: POST /functions/v1/import-kommo-leads

Request Body:

{
 "csvData": "Kommo lead CSV data",
 "organizationId": "org-uuid"
}

External APIs¶

Enroll in Sequence¶

Enroll a contact in a sequence. The organization comes from the API key. If email/phone matches no contact, the contact is created from the other fields; an existing contact is never modified.

Endpoint: POST /functions/v1/sequence-enroll

curl -X POST "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/sequence-enroll" \
 -H "X-API-Key: cg_YOUR_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "sequence_id": "<sequence-uuid>",
 "phone": "+201000000000",
 "first_name": "Ann",
 "last_name": "Lee",
 "email": "ann@example.com",
 "tags": ["shrinkit", "new-merchant"],
 "description": "Signed up via website",
 "source": "signup-form",
 "custom_fields": { "store_url": "https://example.com" }
 }'

Field	Notes
`sequence_id`	Required UUID. The sequence must be `active` and in the key's organization.
`contact_id`	Existing contact UUID. Takes priority; a miss is `404` (never created).
`email`, `phone`	Looked up in that order (email, then phone); phone is matched across formats and stored as E.164. Needed to create a contact.
`first_name`, `last_name`, `tags`, `description`, `source`, `custom_fields`	Used only when a contact is created (`source` defaults to `api`, `tags` to none).

Response: { "success": true, "enrolled": true, "contact_created": true, "contact_id": "...", "sequence_id": "...", "matched_by": "phone" }. enrolled: false with reason already_enrolled or not_eligible (opted out, or no email/phone) is still HTTP 200, so sequential retries are safe. Two simultaneous requests for the same new email/phone can each create a contact (no unique constraint), so do not fire them in parallel. Errors: 400 bad input, 404 contact_id not found, 409 sequence not found or not active, 401 bad key.

Insert Message (External)¶

Insert a message into ConnectGain from an external system. Automatically creates or finds contacts and conversations.

Endpoint: POST /functions/v1/insert-message

Headers:

X-API-Key: cg_abc123def456...
Content-Type: application/json

Request Body:

{
 "phone": "201000000002",
 "content": "Hello from external system!",
 "direction": "outgoing",
 "status": "sent",
 "message_type": "text",
 "metadata": {},
 "channel_account_id": "channel-uuid"
}

Parameters: - phone (required): Phone number in international format - content (required): Message content/text - direction (required): "incoming" or "outgoing" - status (required): "sent", "received", "delivered", "failed", etc. - message_type (optional): Message type (default: "text") - metadata (optional): Additional metadata object - channel_account_id (optional): Specific channel account ID

Response:

{
 "success": true,
 "message": {
 "id": "message-uuid",
 "conversation_id": "conversation-uuid",
 "contact_id": "contact-uuid"
 }
}

Behavior: - Finds or creates contact based on phone number - Finds or creates conversation for the contact - Reopens closed conversations if message is inbound - Inserts message with specified direction and status - Updates conversation's last_message_at timestamp

Curl Example:

curl -X POST \
 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/insert-message' \
 -H 'X-API-Key: cg_abc123def456...' \
 -H 'Content-Type: application/json' \
 -d '{
 "phone": "201000000002",
 "content": "Hello from external system!",
 "direction": "outgoing",
 "status": "sent"
 }'

Generate API Key¶

Create a new API key for external system integration.

Endpoint: POST /functions/v1/generate-api-key

Headers:

X-API-Key: cg_your_api_key
Content-Type: application/json

Request Body:

{
 "name": "External System Integration",
 "expires_in_days": 365,
 "permissions": {
 "can_send_messages": true,
 "can_read_messages": false
 }
}

Parameters: - name (required): Descriptive name for the API key - expires_in_days (optional): Number of days until expiration (null for no expiration) - permissions (optional): Permission object - can_send_messages (boolean): Allow sending messages - can_read_messages (boolean): Allow reading messages

Response:

{
 "success": true,
 "api_key": "cg_abc123def456...",
 "key_info": {
 "id": "key-uuid",
 "name": "External System Integration",
 "key_prefix": "cg_abc123...",
 "expires_at": "2026-01-15T10:30:00Z",
 "created_at": "2025-01-15T10:30:00Z"
 },
 "warning": "Save this API key now. You will not be able to see it again!"
}

Important: The full API key is only shown once. Store it securely immediately after creation.

Organization & Authentication Functions¶

List Organizations¶

Get all organizations the authenticated user has access to.

Endpoint: GET /functions/v1/list-organizations

Headers:

X-API-Key: cg_your_api_key

Response:

{
 "organizations": [
 {
 "id": "uuid",
 "name": "Organization Name",
 "hasAppgainCredentials": true
 }
 ],
 "count": 1
}

Switch Organization¶

Switch the user's active organization.

Endpoint: POST /functions/v1/switch-organization

Request Body:

{
 "organizationId": "org-uuid"
}

Accept Invitation¶

Accept a team invitation and create user account.

Endpoint: POST /functions/v1/accept-invitation

Request Body:

{
 "token": "invitation_token",
 "email": "user@example.com",
 "password": "secure_password",
 "first_name": "John",
 "last_name": "Doe"
}

Send Invitation Email¶

Send an invitation email to a new team member.

Endpoint: POST /functions/v1/send-invitation-email

Request Body:

{
 "email": "newuser@example.com",
 "role": "AGENT",
 "organizationId": "org-uuid"
}

Facebook OAuth¶

Handle Facebook OAuth callback for channel integration.

Endpoint: GET /functions/v1/facebook-oauth?code=oauth_code

Payment & Subscription Functions¶

Create Stripe Checkout¶

Create a Stripe checkout session for subscription.

Endpoint: POST /functions/v1/create-checkout

Request Body:

{
 "priceId": "price_xxxxx",
 "couponCode": "optional_coupon"
}

Response:

{
 "url": "https://checkout.stripe.com/pay/..."
}

Get Customer Portal URL¶

Get Stripe customer portal URL for managing subscription.

Endpoint: GET /functions/v1/customer-portal

Response:

{
 "url": "https://billing.stripe.com/p/portal/..."
}

Check Subscription¶

Check current subscription status.

Endpoint: GET /functions/v1/check-subscription

Response:

{
 "hasActiveSubscription": true,
 "plan": "pro",
 "status": "active"
}

Webhook Functions¶

Webhook endpoints receive events from external services (WhatsApp, Messenger, Instagram, Telegram, TikTok, Stripe).

Available Webhooks: - POST /functions/v1/whatsapp-lite-webhook - WhatsApp Lite webhooks - POST /functions/v1/whatsapp-cloud-webhook - WhatsApp Cloud webhooks - POST /functions/v1/messenger-webhook - Facebook Messenger webhooks - POST /functions/v1/instagram-webhook - Instagram webhooks - POST /functions/v1/telegram-webhook - Telegram webhooks - POST /functions/v1/tiktok-webhook - TikTok webhooks - POST /functions/v1/appgain-whatsapp-webhook - AppGain WhatsApp webhooks - POST /functions/v1/stripe-webhook - Stripe payment webhooks

These endpoints are typically configured in the external service's webhook settings and handle incoming events automatically.

Data access (REST API proxy)¶

Your organization's records are read and written through the REST API proxy:

Base URL: https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/<resource>

Resources: contacts, companies, deals, conversations, messages, tasks, projects, templates, channel_accounts

Every request is scoped to the organization that owns the API key; you never pass an organization id, and you can never read another organization's data.

A request made with a signed-in user's token instead of an API key sees and changes only what that user can in the dashboard: their role, permissions and conversation access apply.

Methods: GET (list / filter), POST (create), PATCH (update matching rows), DELETE (delete matching rows).

A DELETE must name at least one filter. A request with no filter would remove every row of that resource in your organization, and there is no undo — so instead of doing it silently, the API answers 400. If you really do mean to empty the resource, say so with ?confirm_delete_all=true.

Query parameters:

Parameter	Example	Meaning
`select`	`?select=id,first_name,phones`	Columns to return (`` by default); embed related records with `contacts()`
`order`	`?order=created_at.desc`	Sort
`limit` / `offset`	`?limit=50&offset=100`	Pagination (up to 1000 per page)
`<column>=eq.<value>`	`?stage=eq.LEAD`	Equals — also `neq`, `gt`, `gte`, `lt`, `lte`
`<column>=ilike.<text>`	`?first_name=ilike.john`	Case-insensitive contains
`<column>=in.(a,b)`	`?id=in.(uuid1,uuid2)`	Any of
`<column>=cs.{...}`	`?tags=cs.{vip}`	Array contains

# List open conversations with their contact
curl "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/conversations?status=eq.OPEN&select=*,contacts(*)&order=last_message_at.desc" \
 -H "X-API-Key: cg_your_api_key"

# Create a contact
curl -X POST "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts" \
 -H "X-API-Key: cg_your_api_key" -H "Content-Type: application/json" \
 -d '{"first_name":"John","last_name":"Doe","phones":["+15550100001"]}'

# Move a deal
curl -X PATCH "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/deals?id=eq.<deal-uuid>" \
 -H "X-API-Key: cg_your_api_key" -H "Content-Type: application/json" \
 -d '{"stage":"NEGOTIATION"}'

Complete requests for each resource: REST API proxy cURL examples. Searching inside phone, email and tag arrays: Proxy array search.

Pipelines, notes, bot flows, automation rules, campaigns and team members are managed in the app and are not exposed through the proxy.

Features & Capabilities¶

Dashboard & Analytics¶

Dashboard Features: - Customizable widgets (drag-and-drop) - Real-time metrics (messages, conversations, deals, tasks) - Performance charts - Date range filtering - Widget configuration and visibility controls

Analytics Features: - Average response time - SLA compliance tracking - Total messages count - Resolved conversations - Unassigned messages - Overdue conversations - Contact and deal metrics - Task completion rates

Contact Management¶

Features: - Contact CRUD operations - Bulk import (CSV) - Advanced search (name, phone, email, tags, company) - Tag management - Custom fields support - Company association - Contact assignment - Duplicate detection and merging - Contact notes - Deal association - Task association

Views: - Grid view (cards) - Table view - Contact details dialog - Contact edit dialog

Company Management¶

Features: - Company CRUD operations - Bulk import (CSV) - Search by name, domain, email, phone, city, industry - Country filtering - Company details view - Contact association - Deal association

Views: - Grid view (cards) - Table view - Company details dialog

Deal Pipeline Management¶

Features: - Deal CRUD operations - Pipeline management (multiple pipelines) - Stage management (drag-and-drop) - Deal filtering (stage, value range, assignee, tags) - Deal assignment - Value and probability tracking - Expected close date - Custom fields - Deal notes - Contact association

Views: - Kanban board view - Deal details dialog - Pipeline configuration

Conversation Management¶

Features: - Conversation CRUD operations - Message threading - Conversation assignment - Status management (OPEN, CLOSED) - Tag management - Real-time updates - Multi-channel support - Contact association - Deal creation from conversation

Views: - Conversation list - Message thread view - Contact panel - Mobile-responsive design

Message Management¶

Features: - Message CRUD operations - Multi-channel messaging - Message status tracking (SENT, DELIVERED, READ, FAILED) - Message types (text, image, video, audio, document) - Metadata support - Real-time delivery - Message history

Task Management¶

Features: - Task CRUD operations - Task assignment - Due date tracking - Priority levels (LOW, MEDIUM, HIGH) - Completion tracking - Task filtering (status, priority, assignee) - Contact and deal association - Calendar view - List view

Views: - List view - Calendar view - Task details dialog

Template Management¶

Features: - Template CRUD operations - WhatsApp template format support - Template categories (GENERAL, QUICK_REPLY, UTILITY, MARKETING) - Template status (DRAFT, APPROVED, REJECTED) - Template components (BODY, HEADER, FOOTER, BUTTONS) - Variable support ({{name}}, {{company}}, etc.)

Bot Flows¶

Features: - Bot flow CRUD operations - Visual flow builder - Node-based flow design - Flow publishing (DRAFT, PUBLISHED, ARCHIVED) - Version management - Flow execution tracking - Bot session management

Flow Node Types: - Send Message - Collect Input - Condition - Webhook - Assign Conversation - Create Task - End Flow

Automation Rules¶

Features: - Automation rule CRUD operations - Trigger-based automation - Condition matching - Action execution - Active/inactive toggle

Trigger Types: - message.received - New message received - message.sent - Message sent - contact.created - Contact created - contact.updated - Contact updated - contact.assigned - Contact assigned - deal.created - Deal created - deal.updated - Deal updated - deal.stage.changed - Deal stage changed - deal.assigned - Deal assigned - conversation.created - Conversation created - conversation.assigned - Conversation assigned - conversation.status.changed - Conversation status changed

Action Types: - Send Message - Assign Conversation - Assign Contact - Assign Deal - Create Task - Create Deal - Add Tag / Remove Tag (contact or deal) - Update Field (custom fields)

Campaign Management¶

Features: - Campaign CRUD operations - Campaign types (SMS, WHATSAPP_LITE, WHATSAPP_BUSINESS) - Target selection (ALL, TAGS, INDIVIDUAL) - Campaign scheduling - Timezone support - Image support - Campaign status tracking (DRAFT, SCHEDULED, SENDING, COMPLETED, CANCELLED) - Campaign preview - Notification logs

Views: - Campaign list - Campaign creation dialog - Campaign preview - Notification logs

Project Management¶

Features: - Project CRUD operations - Project status tracking (PLANNING, IN_PROGRESS, COMPLETED, DELAYED, CANCELLED) - Start and end dates - Project timeline view - Grid view - Project details

Views: - Grid view - Timeline view - Project details dialog

Channel Management¶

Supported Channels (9): - WhatsApp Lite (Appgain) - WhatsApp Cloud (Meta) - Facebook Messenger - Instagram Direct Messages - Telegram - TikTok - Shopify Inbox - Bulk Email - LinkedIn

SMS is available for broadcast campaigns, sequences, and one-off sends via the API (see SMS - Send Message above) — it is not an inbox channel.

Features: - Channel account CRUD operations - Channel connection/disconnection - Channel status tracking - Channel-specific settings - Webhook configuration - OAuth integration (Facebook, Instagram)

Webhooks¶

Features: - Webhook configuration management - Event subscription - HMAC signature verification - Webhook delivery logging - Retry mechanism - Webhook testing

Available Events: - Contact events: contact.created, contact.updated, contact.assigned - Deal events: deal.created, deal.updated, deal.stage.changed, deal.assigned - Conversation events: conversation.created, conversation.assigned, conversation.status.changed - Message events: message.received, message.sent

Webhook Request Format:

{
 "event": "contact.created",
 "timestamp": "2025-01-15T10:30:00Z",
 "data": {
 "id": "contact-uuid",
 "first_name": "John",
 "last_name": "Doe"
 }
}

Headers: - X-Webhook-Event - Event type - X-Webhook-Timestamp - ISO timestamp - X-Webhook-Signature - HMAC-SHA256 signature (if secret configured)

Team & Organization Management¶

Features: - Organization CRUD operations - User management (profiles) - Role-based access control (OWNER, ADMIN, AGENT, PROJECT_MANAGER, TEAM_ADMIN) - Team invitations - Permission management - Organization switching - User profile management

Permissions (set per user in Settings → Team): - Access CRM features - Access project management - Manage team members - Manage organization settings - Send messages - Read messages

API Key Management¶

Features: - API key generation - API key permissions - API key expiration - API key prefix identification - API key security (hashed storage)

Error Handling¶

Standard Error Response¶

All APIs return errors in a consistent format:

{
 "error": "Error message",
 "details": "Detailed error information",
 "code": "ERROR_CODE"
}

HTTP Status Codes¶

200 OK - Successful request
201 Created - Resource created successfully
400 Bad Request - Invalid request parameters
401 Unauthorized - Authentication required or invalid
403 Forbidden - Insufficient permissions
404 Not Found - Resource not found
409 Conflict - Resource conflict (e.g., duplicate)
422 Unprocessable Entity - Validation error
500 Internal Server Error - Server error
503 Service Unavailable - Service temporarily unavailable

Common Error Codes¶

AUTHENTICATION_FAILED - Authentication failed
INVALID_API_KEY - Invalid API key
INSUFFICIENT_PERMISSIONS - Insufficient permissions
RESOURCE_NOT_FOUND - Resource not found
VALIDATION_ERROR - Request validation failed
RATE_LIMIT_EXCEEDED - Rate limit exceeded
SERVICE_UNAVAILABLE - Service unavailable

Error Examples¶

401 Unauthorized:

{
 "error": "JWT expired",
 "code": "AUTHENTICATION_FAILED"
}

403 Forbidden:

{
 "error": "Invalid API key",
 "code": "INVALID_API_KEY"
}

404 Not Found:

{
 "error": "Could not find resource",
 "code": "RESOURCE_NOT_FOUND"
}

422 Unprocessable Entity:

{
 "error": "Validation error",
 "details": {
 "field": "email",
 "message": "Invalid email format"
 },
 "code": "VALIDATION_ERROR"
}

Rate Limits & Best Practices¶

Rate Limits¶

Endpoints: 100 requests per minute per organization
REST API proxy: 1000 requests per minute per organization
External APIs: 500 requests per minute per API key

Rate limit headers are included in responses: - X-RateLimit-Limit - Request limit - X-RateLimit-Remaining - Remaining requests - X-RateLimit-Reset - Reset timestamp

Best Practices¶

Authentication:
Store API keys securely
Use environment variables for keys
Rotate API keys regularly
Use Bearer tokens for internal requests
Error Handling:
Always check response status codes
Handle rate limit errors gracefully
Implement retry logic with exponential backoff
Log errors for debugging
Performance:
Use pagination for large datasets
Use select parameter to fetch only needed fields
Use filters to reduce data transfer
Cache frequently accessed data
Data Management:
Use bulk operations when possible (import functions)
Batch related operations
Use transactions for multi-step operations
Validate data before sending
Webhooks:
Verify HMAC signatures
Handle webhook failures gracefully
Implement idempotency for webhook handlers
Respond quickly (within 5 seconds)
Security:
Never expose API keys in client-side code
Use HTTPS for all requests
Validate and sanitize all inputs
Implement proper access controls

Postman Collection¶

A complete Postman collection is available on the Postman collection page (direct download).

Setting Up Postman¶

Import the collection into Postman
Set collection variables:
url: https://txpaxbxhnvnhsjwwaeoy.supabase.co
api_key: Your ConnectGain API key
organization_id: Your organization UUID
pipeline_id, channel_account_id: as needed for deals and messaging requests
Start testing APIs!

Collection Structure¶

The collection is organized into folders: - Search - Messages - Organizations - External API (search & insert) - Call Intelligence - Leads & Deals (bulk ingestion)

Support & Resources¶

Documentation: https://docs.connectgain.cloud
App: https://dashboard.connectgain.cloud
API Base URL: https://txpaxbxhnvnhsjwwaeoy.supabase.co
Postman Collection: Postman collection page

Documentation Version: 3.0.0 Last Updated: January 2025 Status: Production Ready

ConnectGain Complete API Documentation¶

Table of Contents¶

Overview¶

API Types¶

Authentication¶

API endpoints¶

Message Sending Functions¶

WhatsApp Lite - Send Message¶

WhatsApp Cloud - Send Message¶

Facebook Messenger - Send Message¶

Instagram - Send Message¶

Telegram - Send Message¶

TikTok - Send Message¶

SMS - Send Message¶

Search & Import Functions¶

Search Contacts¶

Search Companies¶

Import Contacts (CSV)¶

Import Companies (CSV)¶

Import Kommo Leads¶

External APIs¶

Enroll in Sequence¶

Insert Message (External)¶

Generate API Key¶

Organization & Authentication Functions¶

List Organizations¶

Switch Organization¶

Accept Invitation¶

Send Invitation Email¶

Facebook OAuth¶

Payment & Subscription Functions¶

Create Stripe Checkout¶

Get Customer Portal URL¶

Check Subscription¶

Webhook Functions¶

Data access (REST API proxy)¶

Features & Capabilities¶

Dashboard & Analytics¶

Contact Management¶

Company Management¶

Deal Pipeline Management¶

Conversation Management¶

Message Management¶

Task Management¶

Template Management¶

Bot Flows¶

Automation Rules¶

Campaign Management¶

Project Management¶

Channel Management¶

Webhooks¶

Team & Organization Management¶

API Key Management¶

Error Handling¶

Standard Error Response¶

HTTP Status Codes¶

Common Error Codes¶

Error Examples¶

Rate Limits & Best Practices¶

Rate Limits¶

Best Practices¶

Postman Collection¶

Setting Up Postman¶

Collection Structure¶

Support & Resources¶

See also¶