ConnectGain API Overview¶

Overview¶

ConnectGain provides three kinds of API, all authenticated with an organization API key:

Endpoints - purpose-built operations (send, search, import, bot control)
REST API proxy - filtered read/write access to your organization's records
External APIs - endpoints designed for external systems (leads, deals and contacts in bulk)

Base Configuration¶

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

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. Each key is scoped to the organization that created it. See API key authentication.

API endpoints¶

Send Messages¶

WhatsApp Lite - Send Message¶

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

Headers:

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

Body:

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

Curl:

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"
 }'

Response:

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

See the WhatsApp Lite API guide for complete WhatsApp documentation.

WhatsApp Cloud - Send Message¶

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

Body:

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

Messenger - Send Message¶

Endpoint: POST /functions/v1/messenger-send

Body:

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

Instagram - Send Message¶

Endpoint: POST /functions/v1/instagram-send

Body:

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

Telegram - Send Message¶

Endpoint: POST /functions/v1/telegram-send

Body:

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

TikTok - Send Message¶

Endpoint: POST /functions/v1/tiktok-send

Body:

{
 "to": "tiktok_user_id",
 "message": "Hello via TikTok!",
 "conversationId": "conv-uuid"
}

Search & Utilities¶

Search Contacts¶

Endpoint: POST /functions/v1/search-contacts

Headers:

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

Body:

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

Response:

{
 "contacts": [
 {
 "id": "uuid",
 "first_name": "John",
 "last_name": "Doe",
 "phones": ["+1234567890"],
 "emails": ["john@example.com"],
 "tags": ["customer"]
 }
 ],
 "count": 1
}

Search Companies¶

Endpoint: POST /functions/v1/search-companies

Body:

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

List Organizations¶

Endpoint: GET /functions/v1/list-organizations

Response:

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

Payments¶

Create Stripe Checkout¶

Endpoint: POST /functions/v1/create-checkout

Body:

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

Get Customer Portal URL¶

Endpoint: GET /functions/v1/customer-portal

Response:

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

External APIs¶

These APIs use X-API-Key header for authentication and are designed for external systems to integrate with ConnectGain.

Insert Message¶

Endpoint: POST /functions/v1/insert-message

Headers:

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

Body:

{
 "phone": "201000000002",
 "content": "Hello from external system!",
 "direction": "outgoing",
 "status": "sent"
}

Curl:

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"
 }'

Response:

{
 "success": true,
 "messageId": "message-uuid",
 "conversationId": "conversation-uuid",
 "contactId": "contact-uuid"
}

Description: Inserts a message into the ConnectGain system. The system will: - Find or create a contact based on the phone number - Find or create a conversation for the contact - Insert the message with the specified direction and status

Parameters: - phone (required): Phone number in international format (e.g., "201000000002") - content (required): Message content/text - direction (required): Message direction - "incoming" or "outgoing" - status (required): Message status - "sent", "received", "delivered", "failed", etc.

Generate API Key¶

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

Headers:

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

Body:

{
 "name": "External System Integration",
 "organizationId": "org-uuid"
}

Curl:

curl -X POST \
 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/generate-api-key' \
 -H 'X-API-Key: cg_your_api_key' \
 -H 'Content-Type: application/json' \
 -d '{
 "name": "External System Integration",
 "organizationId": "org-uuid"
 }'

Response:

{
 "success": true,
 "api_key": "cg_abc123def456...",
 "key_info": {
 "id": "key-uuid",
 "name": "External System Integration",
 "key_prefix": "cg_abc123",
 "expires_at": null,
 "created_at": "2025-01-15T10:30:00Z"
 },
 "warning": "Store this key now — it will not be shown again."
}

Description: Creates a new API key for your organization. API keys are prefixed with cg_ and can be used with external APIs that require X-API-Key header authentication.

Important: Store the API key securely immediately after creation, as it will not be shown again.

Parameters: - name (required): Descriptive name for the API key (e.g., "Production API", "Development Integration") - organizationId (required): Your organization UUID

Data access (REST API proxy)¶

Contacts, companies, deals, conversations, messages, tasks, projects, templates and channels are read and written through the REST API proxy, scoped to the organization that owns the API key:

# List contacts
curl "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts?select=*&order=created_at.desc&limit=100" \
 -H "X-API-Key: cg_your_api_key"

# Search by name
curl "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts?first_name=ilike.*John*" \
 -H "X-API-Key: cg_your_api_key"

# Create a deal
curl -X POST "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/deals" \
 -H "X-API-Key: cg_your_api_key" -H "Content-Type: application/json" \
 -d '{"title":"Enterprise Deal","stage":"LEAD","value":50000,"contact_id":"<contact-uuid>","pipeline_id":"<pipeline-uuid>"}'

# Assign a conversation
curl -X PATCH "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/conversations?id=eq.<conversation-uuid>" \
 -H "X-API-Key: cg_your_api_key" -H "Content-Type: application/json" \
 -d '{"assignee_id":"<user-uuid>"}'

# Open tasks, soonest first
curl "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/tasks?completed=eq.false&order=due_date.asc" \
 -H "X-API-Key: cg_your_api_key"

Filters use column=op.value (eq, neq, gt, gte, lt, lte, ilike, in, cs), with select, order, limit and offset for shaping and pagination. The full parameter reference is in the Complete API reference; worked requests for every resource are in the REST API proxy cURL examples.

Error Responses¶

400 Bad Request:

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

401 Unauthorized:

{
 "message": "JWT expired"
}

403 Forbidden:

{
 "message": "Invalid API key"
}

404 Not Found:

{
 "message": "Could not find resource"
}

500 Internal Server Error:

{
 "message": "Internal server error",
 "error": "Error details"
}

Postman Collection¶

Download the official collection from the Postman collection page (direct download).

Setting Up Variables¶

Import collection into Postman
Set collection variables:
url: https://txpaxbxhnvnhsjwwaeoy.supabase.co
api_key: Your ConnectGain API key
organization_id: Your organization UUID
contact_id: Test contact ID
deal_id: Test deal ID
conversation_id: Test conversation ID
message_id: Test message ID
Start testing APIs!

Complete CRUD Examples¶

End-to-end contact, deal and integration walkthroughs live in the REST API proxy cURL examples and the Deals API guide.

Notes¶

All timestamps are in ISO 8601 format
JSONB fields support nested objects
Arrays (tags, phones, emails) work with standard JSON arrays
Relations can be fetched using select parameter
Filtering uses column=eq.value syntax (see Data access)
Supports order, limit, offset for pagination
API keys are prefixed with cg_ and should be kept secure
Every request is scoped to the organization that created the key

Complete Documentation: See the WhatsApp Lite API guide for the full WhatsApp Lite endpoint reference.

ConnectGain API Overview¶

Overview¶

Table of Contents¶

Base Configuration¶

Authentication¶

API endpoints¶

Send Messages¶

WhatsApp Lite - Send Message¶

WhatsApp Cloud - Send Message¶

Messenger - Send Message¶

Instagram - Send Message¶

Telegram - Send Message¶

TikTok - Send Message¶

Search & Utilities¶

Search Contacts¶

Search Companies¶

List Organizations¶

Payments¶

Create Stripe Checkout¶

Get Customer Portal URL¶

External APIs¶

Insert Message¶

Generate API Key¶

Data access (REST API proxy)¶

Error Responses¶

Postman Collection¶

Setting Up Variables¶

Complete CRUD Examples¶

Notes¶

See also¶