The Supportly API is a RESTful interface that lets you integrate customer support into your products. Manage conversations, contacts, teams, and more programmatically.
Learn how to authenticate your API requests
Create, list, and manage customer conversations
Get real-time notifications for events
https://api.supportly.io/api/v1curl "https://api.supportly.io/api/v1/accounts/1/conversations" \ -H "api_access_token: YOUR_TOKEN"
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v1/accounts/1/conversations") req = Net::HTTP::Get.new(uri) req['api_access_token'] = 'YOUR_TOKEN' res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/conversations', { headers: { 'api_access_token': 'YOUR_TOKEN' } }); const data = await resp.json();
import requests resp = requests.get('https://api.supportly.io/api/v1/accounts/1/conversations', headers={'api_access_token': 'YOUR_TOKEN'}) data = resp.json()
Supportly supports multiple authentication methods. Include your credentials in the request header to access protected endpoints.
Use a user or bot token via the api_access_token header. Best for server-side integrations.
Use Authorization: Bearer TOKEN header. Best for third-party apps acting on behalf of users.
Browser session-based auth for the Supportly dashboard. Not for API integrations.
Platform-level tokens for multi-account management. Used by platform app developers.
curl "https://api.supportly.io/api/v1/accounts/1/conversations" \ -H "api_access_token: YOUR_TOKEN"
curl "https://api.supportly.io/api/v1/accounts/1/conversations" \ -H "Authorization: Bearer YOUR_OAUTH_TOKEN"
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v1/accounts/1/conversations") req = Net::HTTP::Get.new(uri) req['api_access_token'] = 'YOUR_TOKEN' res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) } data = JSON.parse(res.body)
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/conversations', { headers: { 'api_access_token': 'YOUR_TOKEN' } }); const data = await resp.json();
import requests resp = requests.get('https://api.supportly.io/api/v1/accounts/1/conversations', headers={'api_access_token': 'YOUR_TOKEN'}) data = resp.json()
API requests are rate-limited to ensure platform stability. Limits are applied per token on a sliding window.
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset429 response. Wait until X-RateLimit-Reset before retrying.HTTP/1.1 200 OK X-RateLimit-Limit: 300 X-RateLimit-Remaining: 295 X-RateLimit-Reset: 1708003600
HTTP/1.1 429 Too Many Requests X-RateLimit-Limit: 300 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1708003600 Retry-After: 30 { "errors": [ { "message": "Rate limit exceeded. Please retry after 30 seconds." } ] }
The API uses standard HTTP status codes. Errors return a JSON body with details about what went wrong.
{
"errors": [
{
"field": "email",
"message": "has already been taken",
"code": "taken"
}
]
}List endpoints return paginated results. Use the page query parameter to navigate through pages.
{
"data": {
"meta": {
"mine_count": 5,
"unassigned_count": 12,
"all_count": 42
},
"payload": [ ... objects ... ]
}
}Supportly supports the OAuth 2.0 Authorization Code flow, allowing third-party applications to securely access the API on behalf of users. Create OAuth apps in Settings → Developer Apps.
/oauth/authorize with your client ID and scopes.POST /oauth/token.## Step 1: Redirect user to authorize GET https://api.supportly.io/oauth/authorize ?client_id=YOUR_CLIENT_ID &redirect_uri=https://yourapp.com/callback &response_type=code &scope=conversations.read contacts.read ## Step 2: User approves → redirected back with code https://yourapp.com/callback?code=AUTH_CODE&state=CSRF_TOKEN ## Step 3: Exchange code for access token POST https://api.supportly.io/oauth/token { "grant_type": "authorization_code", "code": "AUTH_CODE", "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "redirect_uri": "https://yourapp.com/callback" } ## Step 4: Use access token for API requests GET https://api.supportly.io/api/v1/accounts/1/conversations Authorization: Bearer YOUR_ACCESS_TOKEN ## Step 5: Refresh when expired POST https://api.supportly.io/oauth/token { "grant_type": "refresh_token", "refresh_token": "..." }
Redirect users to this URL to begin the OAuth flow. Displays a consent page where the user can approve or deny access.
| client_idstringrequired | Your OAuth application's client ID |
| redirect_uristringrequired | URL to redirect after authorization. Must match a registered redirect URI. |
| response_typestringrequired | Must be code |
| scopestring | Space-separated list of requested scopes. Defaults to read. |
| statestring | An opaque value for CSRF protection. Returned unchanged in the callback. |
GET https://api.supportly.io/oauth/authorize? client_id=your_client_id& redirect_uri=https://yourapp.com/callback& response_type=code& scope=conversations.read contacts.read& state=random_csrf_string
Exchange an authorization code for an access token and refresh token. The authorization code is single-use and expires in 10 minutes.
| grant_typestringrequired | Must be authorization_code |
| codestringrequired | The authorization code received from the callback |
| client_idstringrequired | Your application's client ID |
| client_secretstringrequired | Your application's client secret |
| redirect_uristringrequired | Must match the redirect URI used in the authorize request |
curl -X POST "https://api.supportly.io/oauth/token" \ -H "Content-Type: application/json" \ -d '{ "grant_type": "authorization_code", "code": "AUTH_CODE_HERE", "client_id": "your_client_id", "client_secret": "your_client_secret", "redirect_uri": "https://yourapp.com/callback" }'
require 'net/http' require 'json' uri = URI("https://api.supportly.io/oauth/token") req = Net::HTTP::Post.new(uri) req['Content-Type'] = 'application/json' req.body = { grant_type: 'authorization_code', code: 'AUTH_CODE_HERE', client_id: 'your_client_id', client_secret: 'your_client_secret', redirect_uri: 'https://yourapp.com/callback' }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) } data = JSON.parse(res.body)
const resp = await fetch('https://api.supportly.io/oauth/token', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ grant_type: 'authorization_code', code: 'AUTH_CODE_HERE', client_id: 'your_client_id', client_secret: 'your_client_secret', redirect_uri: 'https://yourapp.com/callback' }) }); const data = await resp.json();
import requests resp = requests.post('https://api.supportly.io/oauth/token', json={ 'grant_type': 'authorization_code', 'code': 'AUTH_CODE_HERE', 'client_id': 'your_client_id', 'client_secret': 'your_client_secret', 'redirect_uri': 'https://yourapp.com/callback' }) data = resp.json()
{
"access_token": "eyJhbGciOiJIUzI1NiJ9...",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "dGhpcyBpcyBhIHJlZnJlc2g...",
"scope": "conversations.read contacts.read",
"created_at": 1708000000
}Use a refresh token to obtain a new access token when the current one expires. Access tokens expire after 24 hours.
| grant_typestringrequired | Must be refresh_token |
| refresh_tokenstringrequired | The refresh token from a previous token exchange |
| client_idstringrequired | Your application's client ID |
| client_secretstringrequired | Your application's client secret |
curl -X POST "https://api.supportly.io/oauth/token" \ -H "Content-Type: application/json" \ -d '{ "grant_type": "refresh_token", "refresh_token": "YOUR_REFRESH_TOKEN", "client_id": "your_client_id", "client_secret": "your_client_secret" }'
require 'net/http' require 'json' uri = URI("https://api.supportly.io/oauth/token") req = Net::HTTP::Post.new(uri) req['Content-Type'] = 'application/json' req.body = { grant_type: 'refresh_token', refresh_token: 'YOUR_REFRESH_TOKEN', client_id: 'your_client_id', client_secret: 'your_client_secret' }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
const resp = await fetch('https://api.supportly.io/oauth/token', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ grant_type: 'refresh_token', refresh_token: 'YOUR_REFRESH_TOKEN', client_id: 'your_client_id', client_secret: 'your_client_secret' }) });
import requests resp = requests.post('https://api.supportly.io/oauth/token', json={ 'grant_type': 'refresh_token', 'refresh_token': 'YOUR_REFRESH_TOKEN', 'client_id': 'your_client_id', 'client_secret': 'your_client_secret' })
Immediately invalidate an access token or refresh token. Use this when a user disconnects your app.
| tokenstringrequired | The access token or refresh token to revoke |
| client_idstringrequired | Your application's client ID |
| client_secretstringrequired | Your application's client secret |
curl -X POST "https://api.supportly.io/oauth/revoke" \ -H "Content-Type: application/json" \ -d '{ "token": "TOKEN_TO_REVOKE", "client_id": "your_client_id", "client_secret": "your_client_secret" }'
require 'net/http' require 'json' uri = URI("https://api.supportly.io/oauth/revoke") req = Net::HTTP::Post.new(uri) req['Content-Type'] = 'application/json' req.body = { token: 'TOKEN_TO_REVOKE', client_id: 'your_client_id', client_secret: 'your_client_secret' }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
const resp = await fetch('https://api.supportly.io/oauth/revoke', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ token: 'TOKEN_TO_REVOKE', client_id: 'your_client_id', client_secret: 'your_client_secret' }) });
import requests resp = requests.post('https://api.supportly.io/oauth/revoke', json={ 'token': 'TOKEN_TO_REVOKE', 'client_id': 'your_client_id', 'client_secret': 'your_client_secret' })
Conversations are the core of Supportly. Each conversation represents an interaction thread between a customer and your team across any channel.
Retrieve a paginated list of conversations. Filter by status, assignee, inbox, team, and labels.
| statusstring | Filter by status: open, resolved, pending, snoozed, all |
| assignee_typestring | Filter by assignment: me, unassigned, assigned, all |
| inbox_idinteger | Filter conversations by inbox |
| team_idinteger | Filter conversations by team |
| labels[]array | Filter by labels |
| pageinteger | Page number for pagination (default: 1) |
Create a new conversation. Requires an inbox and contact to start the thread.
| inbox_idintegerrequired | The inbox to create the conversation in |
| contact_idintegerrequired | The contact associated with this conversation |
| messageobject | Initial message: { "content": "Hello!" } |
| assignee_idinteger | Agent ID to assign the conversation to |
| team_idinteger | Team ID to assign the conversation to |
| statusstring | Initial status: open, pending |
Retrieve a single conversation by its display ID, including metadata, participants, and assignment info.
Update conversation properties like status, priority, or custom attributes.
| statusstring | open, resolved, pending, snoozed |
| prioritystring | none, low, medium, high, urgent |
| snoozed_untilinteger | Unix timestamp for snooze end (when status is snoozed) |
curl "https://api.supportly.io/api/v1/accounts/1/conversations?status=open&page=1" \ -H "api_access_token: YOUR_TOKEN"
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v1/accounts/1/conversations?status=open&page=1") req = Net::HTTP::Get.new(uri) req['api_access_token'] = 'YOUR_TOKEN' res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) } data = JSON.parse(res.body)
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/conversations?status=open&page=1', { headers: { 'api_access_token': 'YOUR_TOKEN' } }); const data = await resp.json();
import requests resp = requests.get('https://api.supportly.io/api/v1/accounts/1/conversations', params={'status': 'open', 'page': 1}, headers={'api_access_token': 'YOUR_TOKEN'}) data = resp.json()
curl -X POST "https://api.supportly.io/api/v1/accounts/1/conversations" \ -H "api_access_token: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "inbox_id": 1, "contact_id": 42, "message": { "content": "Hello, I need help!" }, "status": "open" }'
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v1/accounts/1/conversations") req = Net::HTTP::Post.new(uri) req['api_access_token'] = 'YOUR_TOKEN' req['Content-Type'] = 'application/json' req.body = { inbox_id: 1, contact_id: 42, message: { content: 'Hello, I need help!' }, status: 'open' }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/conversations', { method: 'POST', headers: { 'api_access_token': 'YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ inbox_id: 1, contact_id: 42, message: { content: 'Hello, I need help!' }, status: 'open' }) });
import requests resp = requests.post('https://api.supportly.io/api/v1/accounts/1/conversations', headers={'api_access_token': 'YOUR_TOKEN'}, json={'inbox_id': 1, 'contact_id': 42, 'message': {'content': 'Hello, I need help!'}, 'status': 'open'}) data = resp.json()
Messages are individual communications within a conversation. Send replies, notes, and attachments.
Retrieve all messages for a specific conversation, ordered chronologically.
Send a new message in a conversation. Supports text, private notes, and file attachments.
| contentstringrequired | The message text content |
| message_typestring | outgoing (reply to customer) or activity (private note) |
| privateboolean | If true, creates an internal note visible only to agents |
| content_attributesobject | Additional message metadata |
Delete a specific message from a conversation. Cannot be undone.
curl -X POST "https://api.supportly.io/api/v1/accounts/1/conversations/42/messages" \ -H "api_access_token: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "content": "Thanks for reaching out!", "message_type": "outgoing" }'
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v1/accounts/1/conversations/42/messages") req = Net::HTTP::Post.new(uri) req['api_access_token'] = 'YOUR_TOKEN' req['Content-Type'] = 'application/json' req.body = { content: 'Thanks for reaching out!', message_type: 'outgoing' }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/conversations/42/messages', { method: 'POST', headers: { 'api_access_token': 'YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ content: 'Thanks for reaching out!', message_type: 'outgoing' }) });
import requests resp = requests.post('https://api.supportly.io/api/v1/accounts/1/conversations/42/messages', headers={'api_access_token': 'YOUR_TOKEN'}, json={'content': 'Thanks for reaching out!', 'message_type': 'outgoing'})
Contacts represent individuals who interact with your team. Manage customer profiles, custom attributes, and conversation history.
Retrieve a paginated list of all contacts in your account.
| pageinteger | Page number (default: 1, 15 per page) |
| sortstring | Sort field: name, email, phone_number, last_activity_at, created_at |
| order_bystring | asc or desc |
Create a new contact in your account.
| namestring | Contact's full name |
| emailstring | Contact's email address |
| phone_numberstring | Contact's phone number (E.164 format) |
| avatar_urlstring | URL to the contact's avatar image |
| identifierstring | Unique external identifier for the contact |
| lifecycle_stagestring | Contact lifecycle stage: lead, mql, sql, opportunity, customer, evangelist, other |
| sourcestring | How the contact was acquired: website, referral, organic, paid, social, email, event, partner, other |
| custom_attributesobject | Key-value pairs of custom attributes |
Retrieve a single contact by ID, including all profile data, lifecycle stage, source, and custom attributes.
Update contact profile information, lifecycle stage, source, custom attributes, or avatar.
| namestring | Contact's full name |
| emailstring | Contact's email address |
| phone_numberstring | Contact's phone number (E.164 format) |
| lifecycle_stagestring | Contact lifecycle stage: lead, mql, sql, opportunity, customer, evangelist, other |
| sourcestring | How the contact was acquired |
| custom_attributesobject | Key-value pairs of custom attributes |
Permanently delete a contact and all associated data. This action cannot be undone.
Retrieve all conversations associated with a specific contact.
Search contacts by name, email, phone number, or identifier.
| qstringrequired | Search query string |
| pageinteger | Page number |
Track interactions and activities for a specific contact — calls, emails, meetings, notes, and tasks.
List all activities for a contact, ordered by most recent.
Log a new activity for a contact.
| activity_typestringrequired | Type: call, email, meeting, note, task |
| titlestringrequired | Activity title |
| descriptionstring | Detailed description or notes |
| due_datestring | ISO 8601 due date (for tasks) |
| completed_atstring | ISO 8601 timestamp when completed (null if not completed) |
| user_idinteger | Agent who performed the activity |
| metadataobject | Additional metadata key-value pairs |
Update an existing activity for a contact.
Delete a contact activity.
curl -X POST "https://api.supportly.io/api/v1/accounts/1/contacts" \ -H "api_access_token: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Jane Smith", "email": "jane@example.com", "phone_number": "+1234567890", "custom_attributes": { "plan": "enterprise" } }'
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v1/accounts/1/contacts") req = Net::HTTP::Post.new(uri) req['api_access_token'] = 'YOUR_TOKEN' req['Content-Type'] = 'application/json' req.body = { name: 'Jane Smith', email: 'jane@example.com', phone_number: '+1234567890', custom_attributes: { plan: 'enterprise' } }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/contacts', { method: 'POST', headers: { 'api_access_token': 'YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'Jane Smith', email: 'jane@example.com', phone_number: '+1234567890', custom_attributes: { plan: 'enterprise' } }) });
import requests resp = requests.post('https://api.supportly.io/api/v1/accounts/1/contacts', headers={'api_access_token': 'YOUR_TOKEN'}, json={'name': 'Jane Smith', 'email': 'jane@example.com', 'phone_number': '+1234567890', 'custom_attributes': {'plan': 'enterprise'}})
Inboxes are communication channels (website chat, email, social media, API) where customer conversations originate.
Returns all inboxes configured for the account.
Retrieve details for a specific inbox including channel configuration.
Create a new inbox. Required fields depend on the channel type (web, email, api, etc.).
| namestringrequired | Inbox display name |
| channelobjectrequired | Channel configuration including type |
curl "https://api.supportly.io/api/v1/accounts/1/inboxes" \ -H "api_access_token: YOUR_TOKEN"
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v1/accounts/1/inboxes") req = Net::HTTP::Get.new(uri) req['api_access_token'] = 'YOUR_TOKEN' res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) } data = JSON.parse(res.body)
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/inboxes', { headers: { 'api_access_token': 'YOUR_TOKEN' } }); const data = await resp.json();
import requests resp = requests.get('https://api.supportly.io/api/v1/accounts/1/inboxes', headers={'api_access_token': 'YOUR_TOKEN'}) data = resp.json()
Agents are team members who handle conversations. Manage agent accounts, availability, and assignments.
Returns all agents (team members) for the account.
Invite a new agent to your account.
| namestringrequired | Agent's full name |
| emailstringrequired | Agent's email address |
| rolestringrequired | agent or administrator |
Update an agent's name, role, or availability status.
Remove an agent from your account. Their conversations will be unassigned.
curl "https://api.supportly.io/api/v1/accounts/1/agents" \ -H "api_access_token: YOUR_TOKEN"
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v1/accounts/1/agents") req = Net::HTTP::Get.new(uri) req['api_access_token'] = 'YOUR_TOKEN' res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) } data = JSON.parse(res.body)
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/agents', { headers: { 'api_access_token': 'YOUR_TOKEN' } }); const data = await resp.json();
import requests resp = requests.get('https://api.supportly.io/api/v1/accounts/1/agents', headers={'api_access_token': 'YOUR_TOKEN'}) data = resp.json()
Teams group agents together for organized assignment, routing, and management of conversations.
Returns all teams in the account.
Create a new team.
| namestringrequired | Team name |
| descriptionstring | Team description |
| allow_auto_assignboolean | Enable auto-assignment for this team |
curl -X POST "https://api.supportly.io/api/v1/accounts/1/teams" \ -H "api_access_token: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Sales Team", "description": "Handles all sales inquiries", "allow_auto_assign": true }'
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v1/accounts/1/teams") req = Net::HTTP::Post.new(uri) req['api_access_token'] = 'YOUR_TOKEN' req['Content-Type'] = 'application/json' req.body = { name: 'Sales Team', description: 'Handles all sales inquiries', allow_auto_assign: true }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) } data = JSON.parse(res.body)
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/teams', { method: 'POST', headers: { 'api_access_token': 'YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'Sales Team', description: 'Handles all sales inquiries', allow_auto_assign: true }) }); const data = await resp.json();
import requests resp = requests.post('https://api.supportly.io/api/v1/accounts/1/teams', headers={'api_access_token': 'YOUR_TOKEN'}, json={'name': 'Sales Team', 'description': 'Handles all sales inquiries', 'allow_auto_assign': True}) data = resp.json()
Organize conversations and contacts with custom labels for categorization and filtering.
Returns all labels configured for the account.
Create a new label.
| titlestringrequired | Label name (lowercase, no spaces) |
| descriptionstring | Label description |
| colorstring | Hex color code (e.g., #FF5733) |
| show_on_sidebarboolean | Whether to show in the sidebar |
curl -X POST "https://api.supportly.io/api/v1/accounts/1/labels" \ -H "api_access_token: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "priority-customer", "description": "High-priority customer requests", "color": "#FF5733", "show_on_sidebar": true }'
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v1/accounts/1/labels") req = Net::HTTP::Post.new(uri) req['api_access_token'] = 'YOUR_TOKEN' req['Content-Type'] = 'application/json' req.body = { title: 'priority-customer', description: 'High-priority customer requests', color: '#FF5733', show_on_sidebar: true }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) } data = JSON.parse(res.body)
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/labels', { method: 'POST', headers: { 'api_access_token': 'YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ title: 'priority-customer', description: 'High-priority customer requests', color: '#FF5733', show_on_sidebar: true }) }); const data = await resp.json();
import requests resp = requests.post('https://api.supportly.io/api/v1/accounts/1/labels', headers={'api_access_token': 'YOUR_TOKEN'}, json={'title': 'priority-customer', 'description': 'High-priority customer requests', 'color': '#FF5733', 'show_on_sidebar': True}) data = resp.json()
Automate repetitive tasks with rules that trigger actions based on conversation events and conditions.
Returns all automation rules for the account.
Create an automation rule with event triggers, conditions, and actions.
curl "https://api.supportly.io/api/v1/accounts/1/automation_rules" \ -H "api_access_token: YOUR_TOKEN"
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v1/accounts/1/automation_rules") req = Net::HTTP::Get.new(uri) req['api_access_token'] = 'YOUR_TOKEN' res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) } data = JSON.parse(res.body)
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/automation_rules', { headers: { 'api_access_token': 'YOUR_TOKEN' } }); const data = await resp.json();
import requests resp = requests.get('https://api.supportly.io/api/v1/accounts/1/automation_rules', headers={'api_access_token': 'YOUR_TOKEN'}) data = resp.json()
Pre-written reply templates that agents can quickly insert into conversations.
Returns all canned responses. Optionally search by keyword.
Create a canned response template.
| short_codestringrequired | Shortcut code for quick access |
| contentstringrequired | Template content |
curl -X POST "https://api.supportly.io/api/v1/accounts/1/canned_responses" \ -H "api_access_token: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "short_code": "greeting", "content": "Hello! Thanks for reaching out. How can I help you today?" }'
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v1/accounts/1/canned_responses") req = Net::HTTP::Post.new(uri) req['api_access_token'] = 'YOUR_TOKEN' req['Content-Type'] = 'application/json' req.body = { short_code: 'greeting', content: 'Hello! Thanks for reaching out. How can I help you today?' }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) } data = JSON.parse(res.body)
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/canned_responses', { method: 'POST', headers: { 'api_access_token': 'YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ short_code: 'greeting', content: 'Hello! Thanks for reaching out. How can I help you today?' }) }); const data = await resp.json();
import requests resp = requests.post('https://api.supportly.io/api/v1/accounts/1/canned_responses', headers={'api_access_token': 'YOUR_TOKEN'}, json={'short_code': 'greeting', 'content': 'Hello! Thanks for reaching out. How can I help you today?'}) data = resp.json()
Create and manage outbound campaigns to engage customers proactively.
Returns all campaigns for the account.
Create a new campaign.
| titlestringrequired | Campaign title |
| messagestringrequired | Campaign message content |
| inbox_idintegerrequired | Inbox to send from |
curl -X POST "https://api.supportly.io/api/v1/accounts/1/campaigns" \ -H "api_access_token: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Welcome Campaign", "message": "Hi there! Welcome to our platform. How can we assist you?", "inbox_id": 1 }'
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v1/accounts/1/campaigns") req = Net::HTTP::Post.new(uri) req['api_access_token'] = 'YOUR_TOKEN' req['Content-Type'] = 'application/json' req.body = { title: 'Welcome Campaign', message: 'Hi there! Welcome to our platform. How can we assist you?', inbox_id: 1 }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) } data = JSON.parse(res.body)
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/campaigns', { method: 'POST', headers: { 'api_access_token': 'YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ title: 'Welcome Campaign', message: 'Hi there! Welcome to our platform. How can we assist you?', inbox_id: 1 }) }); const data = await resp.json();
import requests resp = requests.post('https://api.supportly.io/api/v1/accounts/1/campaigns', headers={'api_access_token': 'YOUR_TOKEN'}, json={'title': 'Welcome Campaign', 'message': 'Hi there! Welcome to our platform. How can we assist you?', 'inbox_id': 1}) data = resp.json()
Receive real-time HTTP callbacks when events occur in your Supportly account.
conversation_created, conversation_status_changed, conversation_updated,
message_created, message_updated,
contact_created, contact_updated,
webwidget_triggered
Returns all configured webhooks.
Create a webhook subscription.
| urlstringrequired | The URL to receive webhook payloads |
| subscriptionsarray | List of events to subscribe to |
{
"event": "message_created",
"id": 42,
"content": "Hello!",
"message_type": "incoming",
"conversation": {
"id": 1,
"status": "open"
}
}Leverage AI-powered features for intelligent assistance, knowledge management, and automated responses.
Returns all AI assistants configured for the account.
Returns all knowledge base documents used by Captain AI.
Upload a document to the AI knowledge base.
| titlestringrequired | Document title |
| contentstringrequired | Document content |
Create a new copilot conversation thread for agent assistance.
curl -X POST "https://api.supportly.io/api/v1/accounts/1/captain/documents" \ -H "api_access_token: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Product FAQ", "content": "## Frequently Asked Questions\n\nQ: How do I reset my password?\nA: Go to Settings > Security > Reset Password." }'
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v1/accounts/1/captain/documents") req = Net::HTTP::Post.new(uri) req['api_access_token'] = 'YOUR_TOKEN' req['Content-Type'] = 'application/json' req.body = { title: 'Product FAQ', content: '## Frequently Asked Questions\n\nQ: How do I reset my password?\nA: Go to Settings > Security > Reset Password.' }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) } data = JSON.parse(res.body)
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/captain/documents', { method: 'POST', headers: { 'api_access_token': 'YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ title: 'Product FAQ', content: '## Frequently Asked Questions...' }) }); const data = await resp.json();
import requests resp = requests.post('https://api.supportly.io/api/v1/accounts/1/captain/documents', headers={'api_access_token': 'YOUR_TOKEN'}, json={'title': 'Product FAQ', 'content': '## Frequently Asked Questions...'}) data = resp.json()
AI-powered tools for creating, rewriting, and managing help center articles. Generate articles from prompts, conversations, or rewrite existing content.
Generate a new help center article using AI. Supports generation from a prompt, an existing conversation, or a topic suggestion.
| promptstring | A text prompt describing the article to generate |
| conversation_idinteger | Generate an article based on a resolved conversation |
| category_idinteger | Category to assign the generated article to |
Rewrite an existing article using AI to improve clarity, tone, or completeness.
| article_idintegerrequired | The article to rewrite |
| instructionsstring | Specific rewriting instructions (e.g., "make it shorter", "add examples") |
Get AI-suggested article topics based on recent conversations and knowledge gaps.
curl -X POST "https://api.supportly.io/api/v1/accounts/1/portals/1/help_center/ai_articles/generate" \ -H "api_access_token: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "prompt": "How to set up two-factor authentication", "category_id": 5 }'
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v1/accounts/1/portals/1/help_center/ai_articles/generate") req = Net::HTTP::Post.new(uri) req['api_access_token'] = 'YOUR_TOKEN' req['Content-Type'] = 'application/json' req.body = { prompt: 'How to set up two-factor authentication', category_id: 5 }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) } data = JSON.parse(res.body)
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/portals/1/help_center/ai_articles/generate', { method: 'POST', headers: { 'api_access_token': 'YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ prompt: 'How to set up two-factor authentication', category_id: 5 }) }); const data = await resp.json();
import requests resp = requests.post('https://api.supportly.io/api/v1/accounts/1/portals/1/help_center/ai_articles/generate', headers={'api_access_token': 'YOUR_TOKEN'}, json={'prompt': 'How to set up two-factor authentication', 'category_id': 5}) data = resp.json()
AI-powered spam detection scores incoming messages for spam likelihood. Flag or unflag conversations as spam with administrative controls.
Mark a conversation as spam. The conversation will be flagged and can be filtered in the admin view.
Remove the spam flag from a conversation.
curl -X POST "https://api.supportly.io/api/v1/accounts/1/conversations/42/spam" \ -H "api_access_token: YOUR_TOKEN"
uri = URI("https://api.supportly.io/api/v1/accounts/1/conversations/42/spam") req = Net::HTTP::Post.new(uri) req['api_access_token'] = 'YOUR_TOKEN' res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/conversations/42/spam', { method: 'POST', headers: { 'api_access_token': 'YOUR_TOKEN' } });
import requests resp = requests.post('https://api.supportly.io/api/v1/accounts/1/conversations/42/spam', headers={'api_access_token': 'YOUR_TOKEN'})
Help center portals provide self-service knowledge bases for your customers.
Returns all help center portals.
Create a new help center portal.
| namestringrequired | Portal name |
| slugstringrequired | URL-friendly identifier |
| colorstring | Brand color hex code |
curl -X POST "https://api.supportly.io/api/v1/accounts/1/portals" \ -H "api_access_token: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Help Center", "slug": "help-center", "color": "#1B83FF" }'
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v1/accounts/1/portals") req = Net::HTTP::Post.new(uri) req['api_access_token'] = 'YOUR_TOKEN' req['Content-Type'] = 'application/json' req.body = { name: 'Help Center', slug: 'help-center', color: '#1B83FF' }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) } data = JSON.parse(res.body)
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/portals', { method: 'POST', headers: { 'api_access_token': 'YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'Help Center', slug: 'help-center', color: '#1B83FF' }) }); const data = await resp.json();
import requests resp = requests.post('https://api.supportly.io/api/v1/accounts/1/portals', headers={'api_access_token': 'YOUR_TOKEN'}, json={'name': 'Help Center', 'slug': 'help-center', 'color': '#1B83FF'}) data = resp.json()
Help center articles provide self-service support content for your customers.
Returns all articles for a portal. Supports filtering by category and status.
Create a new help center article.
| titlestringrequired | Article title |
| contentstringrequired | Article content (Markdown) |
| statusstring | draft or published |
| category_idinteger | Category ID to organize the article |
Update an existing article's content, title, or status.
Delete an article from the help center.
curl -X POST "https://api.supportly.io/api/v1/accounts/1/portals/my-portal/articles" \ -H "api_access_token: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Getting Started with Supportly", "content": "## Welcome\nThis guide will help you...", "status": "published", "category_id": 1 }'
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v1/accounts/1/portals/my-portal/articles") req = Net::HTTP::Post.new(uri) req['api_access_token'] = 'YOUR_TOKEN' req['Content-Type'] = 'application/json' req.body = { title: 'Getting Started with Supportly', content: '## Welcome...', status: 'published', category_id: 1 }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/portals/my-portal/articles', { method: 'POST', headers: { 'api_access_token': 'YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ title: 'Getting Started with Supportly', content: '## Welcome...', status: 'published', category_id: 1 }) });
import requests resp = requests.post('https://api.supportly.io/api/v1/accounts/1/portals/my-portal/articles', headers={'api_access_token': 'YOUR_TOKEN'}, json={'title': 'Getting Started with Supportly', 'content': '## Welcome...', 'status': 'published', 'category_id': 1})
Organize help center articles into categories for better navigation.
Returns all categories for a portal.
Create a new category.
| namestringrequired | Category name |
| descriptionstring | Category description |
| localestring | Locale code (e.g., en) |
curl -X POST "https://api.supportly.io/api/v1/accounts/1/portals/my-portal/categories" \ -H "api_access_token: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Getting Started", "description": "Introductory guides and tutorials", "locale": "en" }'
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v1/accounts/1/portals/my-portal/categories") req = Net::HTTP::Post.new(uri) req['api_access_token'] = 'YOUR_TOKEN' req['Content-Type'] = 'application/json' req.body = { name: 'Getting Started', description: 'Introductory guides and tutorials', locale: 'en' }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) } data = JSON.parse(res.body)
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/portals/my-portal/categories', { method: 'POST', headers: { 'api_access_token': 'YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'Getting Started', description: 'Introductory guides and tutorials', locale: 'en' }) }); const data = await resp.json();
import requests resp = requests.post('https://api.supportly.io/api/v1/accounts/1/portals/my-portal/categories', headers={'api_access_token': 'YOUR_TOKEN'}, json={'name': 'Getting Started', 'description': 'Introductory guides and tutorials', 'locale': 'en'}) data = resp.json()
The Client Portal provides a branded self-service interface where end-users can sign in via magic link, view their support tickets, reply to existing tickets, and create new ones.
api_access_token. Authentication is handled via magic link tokens. The base path is /hc/{portal_slug}/client-portal/api.
Returns portal information including name, branding, and configuration for the client portal login page.
Send a magic sign-in link to the customer's email address. The link expires after a set period.
| emailstringrequired | The customer's email address |
Verify a magic link token and return an authenticated session. Returns the customer's contact record and a session token.
| tokenstringrequired | The magic link token from the email |
List all tickets for the authenticated customer. Requires the session token from magic link verification.
| X-Portal-Tokenstringrequired | Session token from magic link verification |
Create a new support ticket from the client portal.
| subjectstringrequired | Ticket subject line |
| descriptionstringrequired | Ticket description / initial message |
| inbox_idinteger | Target inbox (uses default if not specified) |
Get details of a specific ticket including all messages.
Reply to an existing ticket with a new message.
| contentstringrequired | The reply message content |
curl -X POST "https://api.supportly.io/hc/my-portal/client-portal/api/request-magic-link" \ -H "Content-Type: application/json" \ -d '{"email": "customer@example.com"}'
require 'net/http' require 'json' uri = URI("https://api.supportly.io/hc/my-portal/client-portal/api/request-magic-link") req = Net::HTTP::Post.new(uri) req['Content-Type'] = 'application/json' req.body = { email: 'customer@example.com' }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
const resp = await fetch('https://api.supportly.io/hc/my-portal/client-portal/api/request-magic-link', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email: 'customer@example.com' }) }); const data = await resp.json();
import requests resp = requests.post('https://api.supportly.io/hc/my-portal/client-portal/api/request-magic-link', json={'email': 'customer@example.com'}) data = resp.json()
{
"tickets": [
{
"id": 1,
"subject": "Cannot reset password",
"status": "open",
"created_at": "2024-12-01T10:30:00Z",
"last_message_at": "2024-12-02T14:22:00Z",
"message_count": 4
}
]
}Connect third-party CRMs, scheduling, and commerce platforms via OAuth. Supported providers: HubSpot, Salesforce, Pipedrive, Calendly, Schedly, Stripe, Zendesk, Jira, Slack, and Shopify.
List all available Supportly integrations and their connection status.
Get details for a specific integration provider, including connection status and configuration.
| providerstringrequired | Provider name: hubspot, salesforce, pipedrive, calendly, schedly, stripe, zendesk, jira, slack, shopify |
Initiate an OAuth connection to a provider. Returns an authorization URL to redirect the user to.
Complete the OAuth flow by exchanging the authorization code for access tokens.
| codestringrequired | OAuth authorization code |
| code_verifierstring | PKCE code verifier (required for PKCE providers) |
Disconnect an integration and revoke stored tokens.
Fetch CRM data for a contact from the connected provider. Returns matching records, deals, activities, and other provider-specific data.
Sync a Supportly contact to the connected CRM. Creates or updates the contact record in the provider.
Create an activity note on the contact's CRM record (e.g., log a call, note, or task).
| contentstringrequired | Activity content / note text |
| activity_typestring | Type of activity: note, call, task |
Execute a provider-specific action. Actions vary by provider (e.g., fetch bookings for Schedly, get event types for Calendly, fetch deals for HubSpot).
| actionstringrequired | The action to perform (provider-specific) |
| paramsobject | Action parameters (varies by action) |
get_bookings, get_available_slots, create_booking, cancel_booking, reschedule_booking, get_teams, get_event_types, route_leadget_event_types, get_scheduled_eventsget_deals, get_companies, search_contacts
Update integration-specific settings (e.g., enable Captain AI scheduling for Schedly, set default event type).
| settingsobjectrequired | Provider settings object. Keys vary by provider. |
captain_scheduling_enabled (boolean), default_event_type_id (string), default_routing_config_id (string)
Enable or disable AI knowledge sync for a provider. When enabled, data from the provider is synced into Captain AI's knowledge base.
Trigger an immediate knowledge sync from the provider.
Get the knowledge sync status across all connected providers.
curl -X POST "https://api.supportly.io/api/v1/accounts/1/supportly_integrations/schedly/connect" \ -H "api_access_token: YOUR_TOKEN"
uri = URI("https://api.supportly.io/api/v1/accounts/1/supportly_integrations/schedly/connect") req = Net::HTTP::Post.new(uri) req['api_access_token'] = 'YOUR_TOKEN' res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) } data = JSON.parse(res.body)
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/supportly_integrations/schedly/connect', { method: 'POST', headers: { 'api_access_token': 'YOUR_TOKEN' } }); const data = await resp.json();
import requests resp = requests.post('https://api.supportly.io/api/v1/accounts/1/supportly_integrations/schedly/connect', headers={'api_access_token': 'YOUR_TOKEN'}) data = resp.json()
{
"authorization_url": "https://app.schedly.io/oauth/authorize?client_id=...&scope=read_bookings+write_bookings+read_profile+read_event_types+read_availability+read_teams+write_webhooks"
}curl -X POST "https://api.supportly.io/api/v1/accounts/1/supportly_integrations/schedly/action" \ -H "api_access_token: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "action": "get_available_slots", "params": { "event_type_id": "evt_123", "start_time": "2025-03-10T00:00:00Z", "end_time": "2025-03-14T23:59:59Z", "timezone": "America/New_York" } }'
uri = URI("https://api.supportly.io/api/v1/accounts/1/supportly_integrations/schedly/action") req = Net::HTTP::Post.new(uri) req['api_access_token'] = 'YOUR_TOKEN' req['Content-Type'] = 'application/json' req.body = { action: 'get_available_slots', params: { event_type_id: 'evt_123', start_time: '2025-03-10T00:00:00Z', end_time: '2025-03-14T23:59:59Z', timezone: 'America/New_York' } }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/supportly_integrations/schedly/action', { method: 'POST', headers: { 'api_access_token': 'YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ action: 'get_available_slots', params: { event_type_id: 'evt_123', start_time: '2025-03-10T00:00:00Z', end_time: '2025-03-14T23:59:59Z', timezone: 'America/New_York' } }) }); const data = await resp.json();
import requests resp = requests.post('https://api.supportly.io/api/v1/accounts/1/supportly_integrations/schedly/action', headers={'api_access_token': 'YOUR_TOKEN'}, json={'action': 'get_available_slots', 'params': {'event_type_id': 'evt_123', 'start_time': '2025-03-10T00:00:00Z', 'end_time': '2025-03-14T23:59:59Z', 'timezone': 'America/New_York'}}) data = resp.json()
Companies represent organizations that your contacts belong to. Manage company profiles with industry, revenue, employee data, and social links for account-based support.
Returns a paginated list of all companies in your account.
| pageinteger | Page number (default: 1, 25 per page) |
| sortstring | Sort field: name, domain, created_at |
Search companies by name or domain.
| qstringrequired | Search query string |
Retrieve a single company with all profile data, linked contacts, and deals.
Create a new company.
| namestringrequired | Company name |
| domainstring | Company website domain |
| descriptionstring | Company description |
| industrystring | Industry vertical (e.g. Technology, Healthcare, Finance) |
| employee_countinteger | Number of employees |
| annual_revenuedecimal | Annual revenue in USD |
| phonestring | Company phone number |
| addressstring | Full mailing address |
| social_linksobject | Social profiles: twitter, facebook, linkedin, github |
Update company information. Accepts all the same body parameters as create.
Delete a company. Contacts will be unlinked but not deleted.
Manage deals associated with a specific company.
List all deals for a company.
Create a new deal under this company.
Update a company deal.
Delete a company deal.
Track interactions and activities for a specific company.
List all activities for a company.
Log a new activity for a company.
| activity_typestringrequired | Type: call, email, meeting, note, task |
| titlestringrequired | Activity title |
| descriptionstring | Detailed description or notes |
| due_datestring | ISO 8601 due date |
| completed_atstring | ISO 8601 timestamp when completed |
| user_idinteger | Agent who performed the activity |
| metadataobject | Additional metadata |
Update a company activity.
Delete a company activity.
curl -X POST "https://api.supportly.io/api/v1/accounts/1/companies" \ -H "api_access_token: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Inc", "domain": "acme.com", "description": "Leading technology company", "industry": "Technology", "employee_count": 150, "annual_revenue": 5000000, "phone": "+1-555-0100", "address": "123 Main St, San Francisco, CA 94102", "social_links": { "twitter": "https://twitter.com/acmeinc", "linkedin": "https://linkedin.com/company/acme" } }'
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v1/accounts/1/companies") req = Net::HTTP::Post.new(uri) req['api_access_token'] = 'YOUR_TOKEN' req['Content-Type'] = 'application/json' req.body = { name: 'Acme Inc', domain: 'acme.com', industry: 'Technology', employee_count: 150, annual_revenue: 5000000, phone: '+1-555-0100', address: '123 Main St, San Francisco, CA 94102', social_links: { twitter: 'https://twitter.com/acmeinc', linkedin: 'https://linkedin.com/company/acme' } }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/companies', { method: 'POST', headers: { 'api_access_token': 'YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'Acme Inc', domain: 'acme.com', industry: 'Technology', employee_count: 150, annual_revenue: 5000000, phone: '+1-555-0100', social_links: { twitter: 'https://twitter.com/acmeinc' } }) });
import requests resp = requests.post('https://api.supportly.io/api/v1/accounts/1/companies', headers={'api_access_token': 'YOUR_TOKEN'}, json={'name': 'Acme Inc', 'domain': 'acme.com', 'industry': 'Technology', 'employee_count': 150, 'annual_revenue': 5000000, 'phone': '+1-555-0100', 'social_links': {'linkedin': 'https://linkedin.com/company/acme'}})
{
"id": 42,
"name": "Acme Inc",
"domain": "acme.com",
"description": "Leading technology company",
"industry": "Technology",
"employee_count": 150,
"annual_revenue": "5000000.0",
"phone": "+1-555-0100",
"address": "123 Main St, San Francisco, CA 94102",
"social_links": {
"twitter": "https://twitter.com/acmeinc",
"linkedin": "https://linkedin.com/company/acme"
},
"contacts_count": 0,
"avatar_url": null,
"created_at": "2026-03-07T10:00:00.000Z",
"updated_at": "2026-03-07T10:00:00.000Z"
}Deals represent sales opportunities in your pipeline. Track deal stages, values, expected close dates, and link deals to contacts and companies.
List all deals for a specific contact.
Create a new deal linked to a contact.
| namestringrequired | Deal name or title |
| valuedecimal | Deal value in your account currency |
| stagestring | Pipeline stage: new_deal, discovery, proposal, negotiation, won, lost |
| pipelinestring | Pipeline name (e.g. "default", "enterprise") |
| expected_close_datestring | ISO 8601 expected close date |
| company_idinteger | Associated company ID |
| assignee_idinteger | Agent assigned to the deal |
| notesstring | Additional notes about the deal |
Update a deal linked to a contact. Accepts all the same body parameters as create.
Delete a deal from a contact.
The same CRUD operations are available scoped to a company.
List all deals for a company.
Create a deal under a company.
Update a company deal.
Delete a company deal.
Update any deal by ID regardless of parent context. Useful for Kanban drag-drop stage changes.
curl -X POST "https://api.supportly.io/api/v1/accounts/1/contacts/5/deals" \ -H "api_access_token: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Enterprise License Q2", "value": 25000, "stage": "proposal", "pipeline": "default", "expected_close_date": "2026-06-30", "assignee_id": 3 }'
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v1/accounts/1/contacts/5/deals") req = Net::HTTP::Post.new(uri) req['api_access_token'] = 'YOUR_TOKEN' req['Content-Type'] = 'application/json' req.body = { name: 'Enterprise License Q2', value: 25000, stage: 'proposal', pipeline: 'default', expected_close_date: '2026-06-30' }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/contacts/5/deals', { method: 'POST', headers: { 'api_access_token': 'YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'Enterprise License Q2', value: 25000, stage: 'proposal', expected_close_date: '2026-06-30' }) });
import requests resp = requests.post('https://api.supportly.io/api/v1/accounts/1/contacts/5/deals', headers={'api_access_token': 'YOUR_TOKEN'}, json={'name': 'Enterprise License Q2', 'value': 25000, 'stage': 'proposal', 'expected_close_date': '2026-06-30'})
{
"id": 1,
"name": "Enterprise License Q2",
"value": "25000.0",
"stage": "proposal",
"pipeline": "default",
"expected_close_date": "2026-06-30",
"contact_id": 5,
"company_id": null,
"assignee_id": 3,
"notes": null,
"created_at": "2026-03-07T10:00:00.000Z",
"updated_at": "2026-03-07T10:00:00.000Z"
}Tasks associated with deals — follow-ups, demos, contract reviews, and other action items to move deals forward.
List all tasks for a deal.
| deal_idintegerrequired | Filter tasks by deal |
Create a new task for a deal.
| deal_idintegerrequired | The deal this task belongs to |
| titlestringrequired | Task title |
| descriptionstring | Task description |
| due_datestring | ISO 8601 due date |
| completedboolean | Whether the task is completed (default: false) |
| assignee_idinteger | Agent assigned to this task |
Update a deal task. Accepts all the same body parameters as create (except deal_id).
Delete a deal task.
curl -X POST "https://api.supportly.io/api/v1/accounts/1/deal_tasks" \ -H "api_access_token: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "deal_id": 1, "title": "Send proposal document", "description": "Attach pricing PDF and SOW", "due_date": "2026-03-15", "assignee_id": 3 }'
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v1/accounts/1/deal_tasks") req = Net::HTTP::Post.new(uri) req['api_access_token'] = 'YOUR_TOKEN' req['Content-Type'] = 'application/json' req.body = { deal_id: 1, title: 'Send proposal document', description: 'Attach pricing PDF and SOW', due_date: '2026-03-15' }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/deal_tasks', { method: 'POST', headers: { 'api_access_token': 'YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ deal_id: 1, title: 'Send proposal document', due_date: '2026-03-15' }) });
import requests resp = requests.post('https://api.supportly.io/api/v1/accounts/1/deal_tasks', headers={'api_access_token': 'YOUR_TOKEN'}, json={'deal_id': 1, 'title': 'Send proposal document', 'due_date': '2026-03-15'})
Deal events provide an audit trail of everything that happened on a deal — stage changes, amount updates, assignments, task completions, and notes.
Retrieve the timeline of events for a deal, ordered by most recent first.
| deal_idintegerrequired | Filter events by deal |
curl "https://api.supportly.io/api/v1/accounts/1/deal_events?deal_id=1" \ -H "api_access_token: YOUR_TOKEN"
require 'net/http' uri = URI("https://api.supportly.io/api/v1/accounts/1/deal_events?deal_id=1") req = Net::HTTP::Get.new(uri) req['api_access_token'] = 'YOUR_TOKEN' res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/deal_events?deal_id=1', { headers: { 'api_access_token': 'YOUR_TOKEN' } });
import requests resp = requests.get('https://api.supportly.io/api/v1/accounts/1/deal_events', headers={'api_access_token': 'YOUR_TOKEN'}, params={'deal_id': 1})
[
{
"id": 3,
"event_type": "stage_changed",
"data": {
"from": "discovery",
"to": "proposal"
},
"performed_by": { "id": 3, "name": "Agent Smith" },
"created_at": "2026-03-07T10:30:00.000Z"
}
]Automate deal workflows — trigger actions when deals reach specific stages, amounts, or conditions. Requires admin access.
List all deal automation rules.
Retrieve a single deal automation by ID.
Create a new deal automation rule.
| namestringrequired | Automation rule name |
| descriptionstring | Rule description |
| trigger_typestringrequired | Event that triggers the rule: stage_changed, deal_created, deal_closed_won, deal_closed_lost, deal_updated |
| action_typestringrequired | Action to perform: webhook, send_notification, assign_agent, create_activity, update_field |
| trigger_configobject | Configuration for the trigger (e.g. {"from_stage": "discovery", "to_stage": "proposal"}) |
| action_configobject | Configuration for the action (e.g. {"agent_id": 3} for assign_agent) |
| enabledboolean | Whether the rule is active (default: true) |
Update a deal automation rule.
Delete a deal automation rule.
curl -X POST "https://api.supportly.io/api/v1/accounts/1/deal_automations" \ -H "api_access_token: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Auto-assign large deals", "trigger_type": "deal_created", "action_type": "assign_agent", "trigger_config": {"min_value": 10000}, "action_config": {"agent_id": 3}, "enabled": true }'
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v1/accounts/1/deal_automations") req = Net::HTTP::Post.new(uri) req['api_access_token'] = 'YOUR_TOKEN' req['Content-Type'] = 'application/json' req.body = { name: 'Auto-assign large deals', trigger_type: 'deal_created', action_type: 'assign_agent', trigger_config: { min_value: 10000 }, action_config: { agent_id: 3 } }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/deal_automations', { method: 'POST', headers: { 'api_access_token': 'YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'Auto-assign large deals', trigger_type: 'deal_created', action_type: 'assign_agent', trigger_config: { min_value: 10000 }, action_config: { agent_id: 3 } }) });
import requests resp = requests.post('https://api.supportly.io/api/v1/accounts/1/deal_automations', headers={'api_access_token': 'YOUR_TOKEN'}, json={'name': 'Auto-assign large deals', 'trigger_type': 'deal_created', 'action_type': 'assign_agent', 'trigger_config': {'min_value': 10000}, 'action_config': {'agent_id': 3}})
Activities are a unified CRM interaction log. Track calls, emails, meetings, notes, and tasks across contacts and companies. Activities are always scoped to either a contact or a company — see the Contacts and Companies sections for the full endpoint reference.
GET/POST /contacts/{contact_id}/activitiesPATCH/DELETE /contacts/{contact_id}/activities/{id}GET/POST /companies/{company_id}/activitiesPATCH/DELETE /companies/{company_id}/activities/{id}
| idinteger | Unique activity identifier |
| activity_typestring | call, email, meeting, note, task |
| titlestring | Activity title |
| descriptionstring | Detailed description |
| due_datestring | ISO 8601 due date (for tasks) |
| completed_atstring | ISO 8601 timestamp when completed |
| user_idinteger | Agent who performed the activity |
| metadataobject | Additional metadata key-value pairs |
| created_atstring | ISO 8601 creation timestamp |
| updated_atstring | ISO 8601 last update timestamp |
curl -X POST "https://api.supportly.io/api/v1/accounts/1/contacts/5/activities" \ -H "api_access_token: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "activity_type": "call", "title": "Discovery call", "description": "Discussed requirements and timeline" }'
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v1/accounts/1/contacts/5/activities") req = Net::HTTP::Post.new(uri) req['api_access_token'] = 'YOUR_TOKEN' req['Content-Type'] = 'application/json' req.body = { activity_type: 'call', title: 'Discovery call', description: 'Discussed requirements and timeline' }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/contacts/5/activities', { method: 'POST', headers: { 'api_access_token': 'YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ activity_type: 'call', title: 'Discovery call', description: 'Discussed requirements and timeline' }) });
import requests resp = requests.post('https://api.supportly.io/api/v1/accounts/1/contacts/5/activities', headers={'api_access_token': 'YOUR_TOKEN'}, json={'activity_type': 'call', 'title': 'Discovery call', 'description': 'Discussed requirements and timeline'})
{
"id": 1,
"activity_type": "call",
"title": "Discovery call",
"description": "Discussed requirements and timeline",
"due_date": null,
"completed_at": null,
"user_id": null,
"metadata": {},
"created_at": "2026-03-07T10:00:00.000Z",
"updated_at": "2026-03-07T10:00:00.000Z"
}Connect third-party services like Slack, Dialogflow, and OpenAI to extend Supportly's capabilities.
Returns all available integration apps and their connection status.
Create a new integration connection (hook).
Disconnect an integration.
{
"authorization_url": "https://provider.com/oauth/authorize?client_id=...",
"code_verifier": "abc123..." // Only for PKCE providers
}Automatically intercept website form submissions to create contacts and conversations. Includes form discovery, smart field mapping, and automatic contact/company creation.
Get the form capture configuration for a web widget inbox, including tracked forms, field mappings, and label suggestions.
Update form capture settings — enable/disable tracking, configure field mappings, and set auto-labeling rules.
| enabledboolean | Enable or disable form capture for this inbox |
| tracked_formsarray | List of form selectors to capture (CSS selectors) |
| field_mappingsobject | Map form fields to contact attributes |
| auto_labelsarray | Labels to automatically apply to captured conversations |
Submit a captured form from the widget SDK. Creates a contact and conversation from the form data.
| website_tokenstringrequired | The inbox website token |
| form_dataobjectrequired | Captured form field values |
| form_urlstring | The URL where the form was submitted |
| form_selectorstring | CSS selector of the captured form |
website_token, not api_access_token.
curl -X PATCH "https://api.supportly.io/api/v1/accounts/1/inboxes/5/form_capture" \ -H "api_access_token: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "enabled": true, "tracked_forms": ["#contact-form", ".demo-request"], "field_mappings": { "email": "email", "full_name": "name", "company": "company_name" }, "auto_labels": ["form-lead", "website"] }'
uri = URI("https://api.supportly.io/api/v1/accounts/1/inboxes/5/form_capture") req = Net::HTTP::Patch.new(uri) req['api_access_token'] = 'YOUR_TOKEN' req['Content-Type'] = 'application/json' req.body = { enabled: true, tracked_forms: ['#contact-form'], field_mappings: { email: 'email', full_name: 'name' } }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/inboxes/5/form_capture', { method: 'PATCH', headers: { 'api_access_token': 'YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ enabled: true, tracked_forms: ['#contact-form'], field_mappings: { email: 'email', full_name: 'name' } }) });
import requests resp = requests.patch('https://api.supportly.io/api/v1/accounts/1/inboxes/5/form_capture', headers={'api_access_token': 'YOUR_TOKEN'}, json={'enabled': True, 'tracked_forms': ['#contact-form'], 'field_mappings': {'email': 'email', 'full_name': 'name'}})
Crawl public and authenticated websites to automatically learn product knowledge. Uses AI for content extraction, knowledge ingestion, and Auto-Intelligence analysis.
List all site explorer crawl sessions for the account.
Create a new site crawl session.
| urlstringrequired | The starting URL to crawl |
| namestring | Friendly name for the session |
| max_pagesinteger | Maximum number of pages to crawl (default: 50) |
| include_patternsarray | URL patterns to include (glob syntax) |
| exclude_patternsarray | URL patterns to exclude (glob syntax) |
Start or resume a crawl session.
Pause an active crawl session.
Resume a paused crawl session.
Re-crawl all pages in the session to refresh knowledge.
List all discovered and crawled pages within a session, including their status and extracted content.
Get the AI-extracted knowledge documents generated from the crawl.
Save authentication credentials for crawling pages behind a login. Supports cookie-based and form-based authentication.
| auth_typestringrequired | cookie or form |
| credentialsobjectrequired | Authentication credentials (varies by auth_type) |
Attempt automatic login to the target website using saved credentials. Returns a session with authenticated cookies for crawling protected pages.
Test whether the target URL is accessible and check for any authentication or connectivity issues.
Open an interactive visual proxy for the crawl session. Renders the target website through a proxy layer, allowing you to navigate and capture pages visually.
Delete a crawl session and all associated data.
curl -X POST "https://api.supportly.io/api/v1/accounts/1/site_explorer_sessions" \ -H "api_access_token: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "url": "https://docs.example.com", "name": "Product Docs", "max_pages": 100, "include_patterns": ["/docs/*", "/help/*"], "exclude_patterns": ["/blog/*"] }'
uri = URI("https://api.supportly.io/api/v1/accounts/1/site_explorer_sessions") req = Net::HTTP::Post.new(uri) req['api_access_token'] = 'YOUR_TOKEN' req['Content-Type'] = 'application/json' req.body = { url: 'https://docs.example.com', name: 'Product Docs', max_pages: 100 }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/site_explorer_sessions', { method: 'POST', headers: { 'api_access_token': 'YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ url: 'https://docs.example.com', name: 'Product Docs', max_pages: 100 }) }); const data = await resp.json();
import requests resp = requests.post('https://api.supportly.io/api/v1/accounts/1/site_explorer_sessions', headers={'api_access_token': 'YOUR_TOKEN'}, json={'url': 'https://docs.example.com', 'name': 'Product Docs', 'max_pages': 100}) data = resp.json()
{
"id": 12,
"url": "https://docs.example.com",
"name": "Product Docs",
"status": "pending",
"pages_discovered": 0,
"pages_crawled": 0,
"max_pages": 100,
"created_at": "2025-03-01T10:00:00Z"
}Manage subscriptions, payment methods, invoices, and add-ons. Supportly uses a three-tier model: Free, Pro, and Enterprise, with optional add-ons for AI Credits and Remove Branding.
Get the current billing status, including active plan, subscription details, usage, and add-ons.
Create a Stripe Checkout session to subscribe to a plan or change plans.
| price_idstringrequired | Stripe price ID for the target plan |
| billing_periodstring | monthly or yearly (default: monthly) |
Enable or disable AI overage billing ($0.06/credit). When enabled, AI continues working beyond plan limits with metered usage billing.
Subscribe to the "Remove Supportly Branding" add-on ($19/month). Removes all Supportly branding from the widget and help center.
Cancel the branding removal add-on. Branding will be restored at the end of the current billing period.
Cancel the current subscription. The account will be downgraded to the Free plan at the end of the billing period.
List all billing invoices for the account.
List all payment methods on file for the account.
Create a Stripe SetupIntent for adding a new payment method without an immediate charge.
Set a payment method as the default for future charges.
| payment_method_idstringrequired | Stripe payment method ID |
Remove a payment method from the account.
| payment_method_idstringrequired | Stripe payment method ID to remove |
Get Stripe publishable key and configuration for client-side Stripe.js integration.
curl "https://api.supportly.io/api/v1/accounts/1/supportly_billing" \ -H "api_access_token: YOUR_TOKEN"
uri = URI("https://api.supportly.io/api/v1/accounts/1/supportly_billing") req = Net::HTTP::Get.new(uri) req['api_access_token'] = 'YOUR_TOKEN' res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) } data = JSON.parse(res.body)
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/supportly_billing', { headers: { 'api_access_token': 'YOUR_TOKEN' } }); const data = await resp.json();
import requests resp = requests.get('https://api.supportly.io/api/v1/accounts/1/supportly_billing', headers={'api_access_token': 'YOUR_TOKEN'}) data = resp.json()
{
"plan": "pro",
"status": "active",
"billing_period": "monthly",
"current_period_end": "2025-04-01T00:00:00Z",
"agent_count": 5,
"agent_limit": 10,
"addons": {
"ai_credits": { "active": true, "remaining": 850 },
"remove_branding": { "active": false }
},
"stripe_customer_id": "cus_..."
}Import data from other platforms like Intercom, Zendesk, and Freshdesk into Supportly.
Start a data migration from a supported platform.
| sourcestringrequired | Source platform: intercom, zendesk, freshdesk |
| credentialsobjectrequired | Authentication credentials for the source platform |
Check the status of a data migration.
{
"id": 1,
"source": "intercom",
"status": "in_progress",
"progress": 65,
"records_imported": 1250,
"total_records": 1920
}Create and manage OAuth 2.0 applications for third-party integrations with Supportly.
Returns all OAuth applications created by your account.
Register a new OAuth application.
| namestringrequired | Application name |
| redirect_urisarrayrequired | Array of allowed redirect URIs |
| scopesarray | Requested OAuth scopes |
Introspect the current OAuth token to retrieve scope, expiry, and ownership details.
{
"id": 1,
"name": "My Integration",
"client_id": "abc123...",
"client_secret": "secret_shown_only_once...",
"redirect_uris": ["https://yourapp.com/callback"],
"scopes": ["conversations.read", "contacts.read"]
}{
"resource_owner_id": 42,
"scope": "conversations.read contacts.read",
"expires_in": 82400,
"application": { "uid": "abc123..." },
"created_at": 1708000000
}Manage your Supportly account settings, including name, locale, and auto-resolve configuration.
Retrieve account details including settings and feature flags.
Update account settings.
| namestring | Account name |
| localestring | Default locale |
| auto_resolve_durationinteger | Auto-resolve conversations after N days |
curl "https://api.supportly.io/api/v1/accounts/1" \ -H "api_access_token: YOUR_TOKEN"
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v1/accounts/1") req = Net::HTTP::Get.new(uri) req['api_access_token'] = 'YOUR_TOKEN' res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) } data = JSON.parse(res.body)
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1', { headers: { 'api_access_token': 'YOUR_TOKEN' } }); const data = await resp.json();
import requests resp = requests.get('https://api.supportly.io/api/v1/accounts/1', headers={'api_access_token': 'YOUR_TOKEN'}) data = resp.json()
Define custom data fields for conversations and contacts to capture business-specific information.
Returns all custom attribute definitions.
Define a new custom attribute.
| attribute_display_namestringrequired | Display name for the attribute |
| attribute_display_typestringrequired | Type: text, number, link, date, list, checkbox |
| attribute_modelstringrequired | conversation_attribute or contact_attribute |
curl -X POST "https://api.supportly.io/api/v1/accounts/1/custom_attribute_definitions" \ -H "api_access_token: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "attribute_display_name": "Subscription Plan", "attribute_display_type": "list", "attribute_model": "contact_attribute" }'
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v1/accounts/1/custom_attribute_definitions") req = Net::HTTP::Post.new(uri) req['api_access_token'] = 'YOUR_TOKEN' req['Content-Type'] = 'application/json' req.body = { attribute_display_name: 'Subscription Plan', attribute_display_type: 'list', attribute_model: 'contact_attribute' }.to_json res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) } data = JSON.parse(res.body)
const resp = await fetch('https://api.supportly.io/api/v1/accounts/1/custom_attribute_definitions', { method: 'POST', headers: { 'api_access_token': 'YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ attribute_display_name: 'Subscription Plan', attribute_display_type: 'list', attribute_model: 'contact_attribute' }) }); const data = await resp.json();
import requests resp = requests.post('https://api.supportly.io/api/v1/accounts/1/custom_attribute_definitions', headers={'api_access_token': 'YOUR_TOKEN'}, json={'attribute_display_name': 'Subscription Plan', 'attribute_display_type': 'list', 'attribute_model': 'contact_attribute'}) data = resp.json()
Access analytics and performance reports for agents, inboxes, and teams.
Get agent performance metrics for a date range.
| sincestringrequired | Start date (ISO 8601) |
| untilstringrequired | End date (ISO 8601) |
Get inbox-level performance metrics.
Get team-level performance metrics.
curl "https://api.supportly.io/api/v2/accounts/1/reports/agents?since=2024-01-01&until=2024-01-31" \ -H "api_access_token: YOUR_TOKEN"
require 'net/http' require 'json' uri = URI("https://api.supportly.io/api/v2/accounts/1/reports/agents?since=2024-01-01&until=2024-01-31") req = Net::HTTP::Get.new(uri) req['api_access_token'] = 'YOUR_TOKEN' res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) } data = JSON.parse(res.body)
const resp = await fetch('https://api.supportly.io/api/v2/accounts/1/reports/agents?since=2024-01-01&until=2024-01-31', { headers: { 'api_access_token': 'YOUR_TOKEN' } }); const data = await resp.json();
import requests resp = requests.get('https://api.supportly.io/api/v2/accounts/1/reports/agents', headers={'api_access_token': 'YOUR_TOKEN'}, params={'since': '2024-01-01', 'until': '2024-01-31'}) data = resp.json()
The Supportly MCP (Model Context Protocol) Server gives AI assistants like Claude, Cursor, and any MCP-compatible client full read and write access to your Supportly account. It exposes 78 tools across conversations, contacts, agents, reports, Captain AI, automations, and integrations — all over a single HTTP endpoint.
Set up Claude Desktop, Cursor, or any MCP client in minutes
Full read/write access to every part of Supportly
Real-time support health in any AI context
POST https://app.supportly.io/mcp | Protocol version: 2024-11-05| tools | 78 tools covering every resource in Supportly — with full read and write access |
| resources | Live resources: Support Radar, All Agents |
| prompts | Built-in prompt templates: support_briefing, contact_summary |
| batching | Supports batched JSON-RPC 2.0 requests in a single HTTP call |
curl "https://app.supportly.io/mcp"
{
"name": "Supportly MCP Server",
"version": "1.0.0",
"protocol": "2024-11-05",
"tool_count": 78,
"endpoints": {
"mcp": { "method": "POST", "path": "/mcp" },
"mcp_account": { "method": "POST", "path": "/mcp/accounts/:account_id" }
}
}The MCP server uses the same API access token as the REST API. Pass it as the api_access_token or x-api-key header on every request.
| api_access_tokenrequired | Your agent API access token. Find it in Profile Settings → Access Token. |
| x-api-key | Alias for api_access_token — use whichever your MCP client supports. |
| x-account-id | Optional. Override the account to use. If omitted, the first account linked to your token is used. |
POST /mcp/accounts/:account_idcurl -X POST "https://app.supportly.io/mcp" \ -H "api_access_token: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2024-11-05", "clientInfo": { "name": "my-client", "version": "1.0" }, "capabilities": {} } }'
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"protocolVersion": "2024-11-05",
"capabilities": { "tools": {}, "resources": {}, "prompts": {} },
"serverInfo": { "name": "Supportly MCP", "version": "1.0.0" }
}
}Any MCP-compatible client can connect to the Supportly MCP server. Below are setup instructions for the most common clients.
Add the following to your claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):
Add to your Cursor MCP settings at ~/.cursor/mcp.json:
Any HTTP client can call the MCP endpoint directly using JSON-RPC 2.0 over POST.
"Use get_support_radar to show me what's happening in support right now."{
"mcpServers": {
"supportly": {
"command": "npx",
"args": ["-y", "mcp-remote",
"https://app.supportly.io/mcp"],
"env": {
"MCP_API_KEY": "YOUR_API_ACCESS_TOKEN"
}
}
}
}{
"mcpServers": {
"supportly": {
"url": "https://app.supportly.io/mcp",
"headers": {
"api_access_token": "YOUR_API_ACCESS_TOKEN"
}
}
}
}curl -X POST "https://app.supportly.io/mcp" \ -H "api_access_token: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
Full read and write access to conversations. List, search, create, reply, assign, label, prioritise, mute, and bulk-update conversations.
| list_conversations | List conversations with filters: status, assignee, inbox, team, label, priority, page |
| get_conversation | Full conversation detail with last 20 messages, contact info, assignee, labels, timeline |
| create_conversation | Create a new conversation for a contact in a specific inbox |
| send_message | Send a reply or private note in a conversation |
| assign_conversation | Assign to an agent and/or team (pass 0 to unassign) |
| update_conversation_status | Set status: open, resolved, pending, snoozed (with optional snooze datetime) |
| add_conversation_label | Add a label to a conversation |
| remove_conversation_label | Remove a label from a conversation |
| update_conversation_priority | Set priority: low, medium, high, urgent |
| mute_conversation | Mute or unmute a conversation |
| search_conversations | Full-text search across conversation messages and contact info |
| get_conversation_messages | Get all messages with sender info, timestamps, and type |
| bulk_assign_conversations | Assign multiple conversations to an agent/team at once |
| bulk_update_conversation_status | Batch status update across multiple conversations |
| bulk_add_label | Add a label to multiple conversations at once |
curl -X POST "https://app.supportly.io/mcp" \ -H "api_access_token: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "list_conversations", "arguments": { "status": "open", "priority": "urgent", "assignee_type": "unassigned" } } }'
{
"method": "tools/call",
"params": {
"name": "send_message",
"arguments": {
"conversation_id": 42,
"content": "Hi! I can help with that.",
"private": false
}
}
}Full CRUD for contacts including notes, conversation history, merging, and custom attributes.
| list_contacts | List contacts with search, company filter, and sorting |
| get_contact | Full contact profile: details, recent conversations, notes, custom attributes |
| create_contact | Create a contact with name, email, phone, company, location, and custom attributes |
| update_contact | Update any contact field including additional attributes |
| search_contacts | Search by name, email, phone, or company |
| merge_contacts | Merge two contacts — child is merged into parent and deleted |
| get_contact_conversations | All conversations for a contact with optional status filter |
| add_contact_note | Add a note to a contact |
| get_contact_notes | List all notes for a contact with author and timestamp |
| delete_contact_note | Remove a note from a contact |
{
"method": "tools/call",
"params": {
"name": "get_contact",
"arguments": { "id": 1234 }
}
}{
"method": "tools/call",
"params": {
"name": "add_contact_note",
"arguments": {
"contact_id": 1234,
"content": "Spoke with their CEO. Interested in enterprise plan."
}
}
}Read agent workloads, availability, team compositions, and inbox configuration.
| list_agents | All agents with roles, availability, open conversation count, and team memberships |
| get_agent | Agent detail with full workload breakdown: open, pending, snoozed, resolved today |
| list_teams | All teams with member counts and open conversation counts |
| get_team | Team detail with all members listed |
| list_team_agents | All agents in a specific team |
| list_inboxes | All inboxes with channel type, open count, and config (auto-assign, working hours) |
| get_inbox | Inbox detail with members, stats, and configuration |
{
"method": "tools/call",
"params": {
"name": "list_agents",
"arguments": { "team_id": 3 }
}
}Real-time support health and historical performance reports — by account, agent, team, inbox, or label.
| get_support_radar | Real-time snapshot: open/pending/snoozed counts, unassigned, urgent conversations, agent workload, most recent activity |
| get_account_summary | Account-level performance for a date range: volume, resolution rate, avg resolution time, CSAT |
| get_csat_summary | CSAT score breakdown: Satisfied / Neutral / Dissatisfied counts and percentages |
| list_csat_responses | Individual CSAT survey responses with rating, feedback, contact, and agent |
| get_agent_report | Per-agent performance: conversations handled, resolved, CSAT score |
| get_team_report | Per-team performance for a date range |
| get_inbox_report | Per-inbox volume and resolution stats |
| get_label_report | Conversation volume breakdown by label |
supportly://radar — useful for polling tools.{
"method": "tools/call",
"params": {
"name": "get_support_radar",
"arguments": {}
}
}
// Returns:
"""
=== SUPPORTLY SUPPORT RADAR ===
Generated: 2025-01-15 09:30 UTC
📊 VOLUME
Open: 47 | Pending: 12 | Snoozed: 3
Unassigned (open): 8
Created today: 23 | Resolved today: 19
🚨 PRIORITY ALERTS
Urgent conversations: 2
High priority: 7
...
"""Full CRUD for automation rules — create, update, enable/disable, and delete rules that trigger on conversation events.
| list_automation_rules | All rules with trigger events, conditions, actions, and active status |
| get_automation_rule | Full rule detail with all conditions and actions listed |
| create_automation_rule | Create a rule with event, conditions array, and actions array |
| update_automation_rule | Update any fields of an existing rule |
| toggle_automation_rule | Enable or disable a rule without deleting it |
| delete_automation_rule | Permanently delete a rule |
conversation_created · conversation_updated · conversation_status_changed · message_created · contact_created · contact_updated
assign_an_agent · assign_a_team · add_label · remove_label · send_message · mute_conversation · resolve_conversation · snooze_conversation
{
"name": "create_automation_rule",
"arguments": {
"name": "Escalate billing urgency",
"event": "message_created",
"conditions": [{
"attribute_key": "content",
"filter_operator": "contains",
"values": ["billing", "invoice"]
}],
"actions": [
{ "action_name": "add_label", "action_params": ["billing"] },
{ "action_name": "assign_a_team", "action_params": [2] }
],
"active": true
}
}Query and manage the Captain AI knowledge base. Search indexed documents, add new knowledge, and inspect assistants and scenarios.
| list_captain_assistants | All Captain AI assistants with document counts |
| get_captain_assistant | Assistant detail including indexed vs pending document counts |
| query_captain_knowledge | Semantic search across indexed knowledge base documents |
| list_captain_documents | All knowledge base documents with status (indexed / pending / failed) |
| create_captain_document | Add a new document to the knowledge base (indexing starts automatically) |
| delete_captain_document | Remove a document from the knowledge base |
| list_captain_scenarios | All Captain automation scenarios |
{
"name": "query_captain_knowledge",
"arguments": {
"query": "refund policy for annual plans",
"limit": 5
}
}{
"name": "create_captain_document",
"arguments": {
"name": "Refund Policy v2",
"content": "Annual plan refunds are available within 30 days of renewal..."
}
}Manage labels, canned responses (saved reply templates), and outgoing webhooks.
| list_labels | All labels with colors and conversation usage counts |
| create_label | Create a label with title, description, and hex color |
| update_label | Update label title, description, or color |
| list_canned_responses | All saved reply templates with optional search by short code or content |
| create_canned_response | Create a new template with short code and content |
| update_canned_response | Update short code or content |
| delete_canned_response | Delete a template |
| list_webhooks | All outgoing webhooks with subscribed events |
| create_webhook | Create a webhook with URL and event subscriptions |
| delete_webhook | Delete a webhook |
{
"name": "create_canned_response",
"arguments": {
"short_code": "refund30",
"content": "Refunds are available within 30 days of purchase. I've initiated yours now."
}
}{
"name": "create_webhook",
"arguments": {
"url": "https://your-app.com/hooks/supportly",
"subscriptions": [
"conversation_created",
"message_created",
"conversation_status_changed"
]
}
}Query connected integrations and get a unified 360° view of any customer across all connected services — CRM, billing, bookings, and more.
| list_integrations | All available integrations with connection status, sync state, and last sync timestamp |
| get_integration_status | Detailed status for a specific integration (Pipedrive, HubSpot, Schedly, Stripe, etc.) |
| get_customer_360 | Unified customer view: support history, notes, CRM data, billing, bookings — all in one call |
| trigger_integration_sync | Manually trigger a data sync for a connected integration |
pipedrive hubspot salesforce schedly zendesk stripe shopify slack gong fireflies confluence linear jira calendly
{
"name": "get_customer_360",
"arguments": { "contact_id": 1234 }
}
// Returns a unified profile:
"""
=== CUSTOMER 360° VIEW ===
Contact: Jane Smith (ID: 1234)
Email: jane@acme.com | Phone: +1 555 0100
Company: Acme Corp
─── SUPPORT HISTORY ───
Total conversations: 14
Open: 2 | Resolved: 12
─── INTEGRATION DATA ───
Pipedrive:
Deal stage: Negotiation | Value: $12,000
Stripe:
Customer ID: cus_xxx | Plan: Business
Schedly:
Next booking: Jan 20 at 2pm
"""Build a custom GPT inside ChatGPT that has live access to your Supportly account. GPT Actions work by pointing ChatGPT at a hosted OpenAPI spec — Supportly provides one ready to use. No coding required.
https://app.supportly.io/mcp/schemas/chatgpt| Conversations | List, get, create, send message, assign, update status/priority, add label |
| Contacts | List, get, create, update, search, add note, get notes |
| Agents & Teams | List agents, list teams, list inboxes |
| Content | List labels, list canned responses |
https://app.supportly.io/mcp/schemas/chatgpt
You are a Supportly assistant with live access to my customer support account. My account ID is: [YOUR_ACCOUNT_ID] Always include account_id in every API request. When asked about support health, list open conversations grouped by priority. Confirm before resolving or reassigning conversations. You can: - View and manage conversations - Search and update contacts - Assign conversations to agents or teams - Send replies or private notes - Look up canned responses
// In ChatGPT after connecting: "Show me all urgent open conversations" "Find the contact Jane Smith and add a note" "Resolve conversation 142 and send a closing message" "Who are our available agents right now?" "Search for a canned response about refunds"
Connect Supportly to Google Gemini by creating a custom Gem. Gemini Gems support OpenAPI-based function calling — Supportly provides a ready-made spec. You can also use it directly via Google AI Studio or Vertex AI for developer integrations.
https://app.supportly.io/api/v1https://app.supportly.io/mcp/schemas/geminiYou are a Supportly customer support assistant. Supportly is our customer support platform. Here is what you know about how to help: - Conversations are support tickets. They can be open, pending, resolved, or snoozed. - Contacts are customers. Each has a name, email, phone, and conversation history. - Agents are support team members. Teams group agents. - Canned responses are saved reply templates. - Priority levels: urgent, high, medium, low. When asked to check on support, describe what a healthy vs unhealthy queue looks like: low unassigned conversations, no urgent items waiting, all agents have reasonable workloads. Always be concise and actionable.
const { GoogleGenerativeAI } = await import('@google/generative-ai'); // Fetch Supportly function declarations const schema = await fetch( 'https://app.supportly.io/mcp/schemas/gemini' ).then(r => r.json()); const genAI = new GoogleGenerativeAI('YOUR_GEMINI_KEY'); const model = genAI.getGenerativeModel({ model: 'gemini-1.5-pro', tools: [{ functionDeclarations: schema.functions }] }); const chat = model.startChat(); const result = await chat.sendMessage( 'Show me all urgent open conversations' ); // Handle function calls const call = result.response.functionCalls()?.[0]; if (call) { const resp = await fetch( `https://app.supportly.io/api/v1/${call.args.account_id}/conversations`, { headers: { 'api_access_token': 'YOUR_TOKEN' } } ); // Feed result back to Gemini... }
© 2026 Supportly. All rights reserved.