API Endpoints #

Complete reference for all CommFlow API endpoints.

Conversations #

List Conversations #

GET /v1/conversations

Parameters:

Parameter	Type	Description
`status`	string	Filter by status: `open`, `pending`, `closed`
`assignee`	string	Filter by assignee ID
`channel`	string	Filter by channel: `email`, `chat`, `form`
`created_after`	datetime	Created after this date
`created_before`	datetime	Created before this date
`page`	integer	Page number (default: 1)
`per_page`	integer	Results per page (default: 25, max: 100)

Response:

{
  "data": [
    {
      "id": "conv_123",
      "subject": "Need help with billing",
      "status": "open",
      "channel": "email",
      "assignee": {
        "id": "user_456",
        "name": "Sarah Chen"
      },
      "contact": {
        "id": "contact_789",
        "name": "John Doe",
        "email": "john@example.com"
      },
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-15T11:45:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total_count": 150
  }
}

Get Conversation #

GET /v1/conversations/{conversation_id}

Response:

{
  "data": {
    "id": "conv_123",
    "subject": "Need help with billing",
    "status": "open",
    "priority": "normal",
    "channel": "email",
    "assignee": {
      "id": "user_456",
      "name": "Sarah Chen"
    },
    "contact": {
      "id": "contact_789",
      "name": "John Doe",
      "email": "john@example.com"
    },
    "tags": ["billing", "urgent"],
    "custom_fields": {
      "account_id": "12345"
    },
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T11:45:00Z"
  }
}

Create Conversation #

POST /v1/conversations

Request Body:

{
  "subject": "New support request",
  "contact": {
    "email": "customer@example.com",
    "name": "Jane Smith"
  },
  "message": {
    "body": "I need help with my account.",
    "type": "comment"
  },
  "channel": "api",
  "priority": "normal",
  "tags": ["support"]
}

Response:

{
  "data": {
    "id": "conv_124",
    "subject": "New support request",
    "status": "open",
    "created_at": "2026-01-15T12:00:00Z"
  }
}

Update Conversation #

PATCH /v1/conversations/{conversation_id}

Request Body:

{
  "status": "pending",
  "priority": "high",
  "assignee_id": "user_456",
  "tags": ["billing", "escalated"]
}

Messages #

List Messages #

GET /v1/conversations/{conversation_id}/messages

Parameters:

Parameter	Type	Description
`type`	string	Filter by type: `comment`, `note`, `reply`
`page`	integer	Page number
`per_page`	integer	Results per page

Response:

{
  "data": [
    {
      "id": "msg_001",
      "body": "I need help with my account.",
      "type": "comment",
      "author": {
        "type": "contact",
        "id": "contact_789",
        "name": "John Doe"
      },
      "attachments": [],
      "created_at": "2026-01-15T10:30:00Z"
    },
    {
      "id": "msg_002",
      "body": "I'd be happy to help! Can you provide your account ID?",
      "type": "reply",
      "author": {
        "type": "user",
        "id": "user_456",
        "name": "Sarah Chen"
      },
      "created_at": "2026-01-15T10:35:00Z"
    }
  ]
}

Create Message #

POST /v1/conversations/{conversation_id}/messages

Request Body:

{
  "body": "Thanks for reaching out! I'll look into this.",
  "type": "reply"
}

Message Types:

Type	Description
`reply`	Visible to customer
`note`	Internal note (team only)

Create Message with Attachments #

POST /v1/conversations/{conversation_id}/messages
Content-Type: multipart/form-data

Form Data:

Field	Type	Description
`body`	string	Message text
`type`	string	Message type
`attachments[]`	file	File attachments

Contacts #

List Contacts #

GET /v1/contacts

Parameters:

Parameter	Type	Description
`email`	string	Filter by email
`q`	string	Search name or email
`created_after`	datetime	Created after date
`page`	integer	Page number
`per_page`	integer	Results per page

Response:

{
  "data": [
    {
      "id": "contact_789",
      "email": "john@example.com",
      "name": "John Doe",
      "phone": "+1234567890",
      "company": "Acme Inc",
      "custom_fields": {
        "plan": "enterprise",
        "account_id": "12345"
      },
      "created_at": "2026-01-10T08:00:00Z"
    }
  ]
}

Get Contact #

GET /v1/contacts/{contact_id}

Create Contact #

POST /v1/contacts

Request Body:

{
  "email": "newcontact@example.com",
  "name": "Jane Smith",
  "phone": "+1987654321",
  "company": "Tech Corp",
  "custom_fields": {
    "plan": "professional",
    "referral_source": "website"
  }
}

Update Contact #

PATCH /v1/contacts/{contact_id}

Request Body:

{
  "name": "Jane M. Smith",
  "company": "Tech Corp Inc",
  "custom_fields": {
    "plan": "enterprise"
  }
}

Delete Contact #

DELETE /v1/contacts/{contact_id}

Tickets (Inbox)#

List Tickets #

GET /v1/tickets

Parameters:

Parameter	Type	Description
`status`	string	`open`, `pending`, `resolved`, `closed`
`priority`	string	`urgent`, `high`, `normal`, `low`
`assignee`	string	Assignee user ID
`inbox`	string	Inbox ID
`sla_status`	string	`on_track`, `warning`, `breached`

Response:

{
  "data": [
    {
      "id": "ticket_001",
      "subject": "Cannot access my account",
      "status": "open",
      "priority": "high",
      "sla": {
        "status": "on_track",
        "first_response_due": "2026-01-15T14:00:00Z"
      },
      "assignee": {
        "id": "user_456",
        "name": "Sarah Chen"
      },
      "contact": {
        "id": "contact_789",
        "email": "john@example.com"
      },
      "created_at": "2026-01-15T10:00:00Z"
    }
  ]
}

Get Ticket #

GET /v1/tickets/{ticket_id}

Create Ticket #

POST /v1/tickets

Request Body:

{
  "subject": "Bug report: Login issue",
  "description": "Users are unable to log in since the last update.",
  "priority": "high",
  "contact": {
    "email": "reporter@example.com"
  },
  "tags": ["bug", "login"]
}

Update Ticket #

PATCH /v1/tickets/{ticket_id}

Request Body:

{
  "status": "resolved",
  "priority": "normal",
  "assignee_id": "user_789"
}

Users #

List Users #

GET /v1/users

Parameters:

Parameter	Type	Description
`role`	string	Filter by role
`status`	string	`active`, `inactive`

Response:

{
  "data": [
    {
      "id": "user_456",
      "email": "sarah@company.com",
      "name": "Sarah Chen",
      "role": "admin",
      "status": "active",
      "avatar_url": "https://...",
      "created_at": "2025-06-01T00:00:00Z"
    }
  ]
}

Get User #

GET /v1/users/{user_id}

Get Current User #

GET /v1/me

Returns the authenticated user's profile.

Teams #

List Teams #

GET /v1/teams

Response:

{
  "data": [
    {
      "id": "team_001",
      "name": "Support Team",
      "description": "Customer support",
      "members_count": 5,
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

Get Team #

GET /v1/teams/{team_id}

Team Members #

GET /v1/teams/{team_id}/members

Tags #

GET /v1/tags

Response:

{
  "data": [
    {
      "id": "tag_001",
      "name": "billing",
      "color": "#10b981",
      "count": 42
    },
    {
      "id": "tag_002",
      "name": "urgent",
      "color": "#ef4444",
      "count": 15
    }
  ]
}

Create Tag #

POST /v1/tags

Request Body:

{
  "name": "new-feature",
  "color": "#3b82f6"
}

Webhooks #

List Webhooks #

GET /v1/webhooks

Create Webhook #

POST /v1/webhooks

Request Body:

{
  "url": "https://yourapp.com/webhook",
  "events": ["ticket.created", "ticket.updated", "message.created"],
  "secret": "your_webhook_secret"
}

Update Webhook #

PATCH /v1/webhooks/{webhook_id}

Delete Webhook #

DELETE /v1/webhooks/{webhook_id}

Test Webhook #

POST /v1/webhooks/{webhook_id}/test

Sends a test event to verify your endpoint.

Files #

Upload File #

POST /v1/files
Content-Type: multipart/form-data

Form Data:

Field	Type	Description
`file`	file	The file to upload
`folder`	string	Optional folder path

Response:

{
  "data": {
    "id": "file_001",
    "name": "document.pdf",
    "size": 102400,
    "mime_type": "application/pdf",
    "url": "https://files.commflow.io/...",
    "created_at": "2026-01-15T12:00:00Z"
  }
}

Get File #

GET /v1/files/{file_id}

Delete File #

DELETE /v1/files/{file_id}

Search #

Search Everything #

GET /v1/search?q=billing+issue

Parameters:

Parameter	Type	Description
`q`	string	Search query
`type`	string	Filter: `conversation`, `contact`, `ticket`
`limit`	integer	Max results (default: 20)

Response:

{
  "data": {
    "conversations": [...],
    "contacts": [...],
    "tickets": [...]
  },
  "meta": {
    "total_results": 45
  }
}

Bulk Operations #

Bulk Update Tickets #

POST /v1/tickets/bulk

Request Body:

{
  "ids": ["ticket_001", "ticket_002", "ticket_003"],
  "update": {
    "status": "closed",
    "tags": ["resolved"]
  }
}

Bulk Update Contacts #

POST /v1/contacts/bulk

Request Body:

{
  "ids": ["contact_001", "contact_002"],
  "update": {
    "custom_fields": {
      "segment": "enterprise"
    }
  }
}

Rate Limits #

All endpoints are subject to rate limiting:

Plan	Requests/minute
Starter	60
Professional	300
Business	1000

Rate limit headers are included in all responses:

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

Next Steps #

Authentication - Auth reference
API Overview - Getting started

Was this page helpful?