API Overview#

The CommFlow API allows developers to programmatically interact with CommFlow, enabling custom integrations, automation, and application development.

Introduction#

What Can You Do?#

With the CommFlow API, you can:

• Read data - Access conversations, contacts, tickets
• Create content - Send messages, create tickets
• Update records - Modify status, assignments
• Automate workflows - Trigger actions programmatically
• Build integrations - Connect with other tools

API Style#

CommFlow uses a RESTful API:

• Standard HTTP methods (GET, POST, PUT, DELETE)
• JSON request and response bodies
• Bearer token authentication
• Consistent error handling

Base URL#

All API requests use this base URL:

https://api.commflow.io/v1

Quick Start#

1. Get Your API Key#

1. Go to Settings > API
2. Click Create API Key
3. Name your key
4. Copy the key (shown only once)

2. Make Your First Request#

curl -X GET "https://api.commflow.io/v1/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "id": "user_123",
  "email": "developer@company.com",
  "name": "Developer",
  "workspace": {
    "id": "ws_456",
    "name": "My Workspace"
  }
}

3. Explore Endpoints#

Browse available endpoints in this documentation or use the API playground.

Authentication#

API Keys#

API keys authenticate server-to-server requests:

Authorization: Bearer sk_live_xxxxxxxxxxxxx

Key Types:

OAuth 2.0#

For user-authorized applications:

1. Redirect to authorization URL
2. User grants permission
3. Exchange code for access token
4. Use token for requests

See Authentication for details.

Scopes#

API keys can be scoped to specific permissions:

Making Requests#

Request Format#

POST /v1/conversations/conv_123/messages HTTP/1.1
Host: api.commflow.io
Authorization: Bearer sk_live_xxxxx
Content-Type: application/json
 
{
  "body": "Hello, how can I help?",
  "type": "comment"
}

Response Format#

All responses return JSON:

{
  "data": {
    "id": "msg_789",
    "body": "Hello, how can I help?",
    "type": "comment",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

HTTP Methods#

Pagination#

List endpoints return paginated results:

Request#

GET /v1/conversations?page=1&per_page=25

Response#

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total_pages": 10,
    "total_count": 250
  },
  "links": {
    "first": "/v1/conversations?page=1",
    "prev": null,
    "next": "/v1/conversations?page=2",
    "last": "/v1/conversations?page=10"
  }
}

Parameters#

Filtering & Sorting#

Filtering#

Filter results with query parameters:

GET /v1/tickets?status=open&priority=urgent
GET /v1/contacts?email=*@company.com
GET /v1/conversations?created_after=2026-01-01

Sorting#

Sort results:

GET /v1/tickets?sort=created_at&order=desc
GET /v1/contacts?sort=name&order=asc

Search#

Full-text search:

GET /v1/conversations?q=billing+issue

Error Handling#

Error Response Format#

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "The 'email' field is required.",
    "param": "email"
  }
}

HTTP Status Codes#

Error Types#

Rate Limiting#

Limits#

Headers#

Rate limit info in response headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295
X-RateLimit-Reset: 1705320600

Handling Rate Limits#

When rate limited (429 response):

1. Check Retry-After header
2. Wait the specified time
3. Retry the request
4. Implement exponential backoff

Webhooks#

Receive real-time notifications:

Setting Up Webhooks#

1. Go to Settings > API > Webhooks
2. Add endpoint URL
3. Select events to receive
4. Save webhook

Webhook Payload#

{
  "event": "ticket.created",
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "id": "ticket_123",
    "subject": "Need help with billing",
    "status": "open"
  }
}

Available Events#

See Webhooks for full documentation.

SDKs & Libraries#

Official SDKs#

Example (Node.js)#

import CommFlow from '@commflow/node';
 
const commflow = new CommFlow('sk_live_xxxxx');
 
// Get a conversation
const conversation = await commflow.conversations.get('conv_123');
 
// Send a message
await commflow.messages.create('conv_123', {
  body: 'Thanks for reaching out!',
  type: 'comment'
});

API Playground#

Test API calls interactively:

1. Go to Settings > API > Playground
2. Select endpoint
3. Enter parameters
4. Execute request
5. View response

Best Practices#

Security#

1. Keep keys secret - Never expose in client code
2. Use environment variables - Don't hardcode keys
3. Rotate keys - Periodically regenerate
4. Scope appropriately - Minimal required permissions

Performance#

1. Cache responses - Reduce API calls
2. Use pagination - Don't fetch everything at once
3. Handle rate limits - Implement backoff
4. Batch requests - When possible

Error Handling#

1. Check status codes - Handle all error types
2. Log errors - For debugging
3. Retry transient errors - 5xx errors
4. Fail gracefully - Don't crash on API issues

Getting Help#

Resources#

• API Reference - Full endpoint documentation
• SDKs - Official client libraries
• Changelog - API updates and changes
• Status - API health status

Support#

• Documentation - Search the docs
• Community - Developer forums
• Email - api-support@commflow.io

Next Steps#

• Authentication - Auth deep dive
• Endpoints - Full endpoint reference