Intelligence Cloud · API Reference
API Reference
Customer lifecycle and conversation intelligence for Intelligence Cloud partners.
Base URL https://app.intelligence.cloud/api/v1OpenAPI 3.1.0100 operations
Start
Overview
The Intelligence Cloud API covers two jobs:
-
Customer lifecycle: create and run customer companies, locations, users, products,
connectors, First Alert rules and Insights Hub setup. Use admin credentials
(a reseller admin login).
-
Conversation intelligence: read calls, transcripts, alerts, tasks and insights with
frontline credentials (a frontline user login), and receive the After Call and First Alert
webhooks at addresses you set with admin credentials.
Credentials
Today every integration signs in with the email and password of a dedicated integration user. Turn MFA off for that user's company (PATCH /companies/{companyId} with mfa_enforced: false). API keys arrive in December 2026.
The integration user's password follows the company's password policy, set by the reseller (GET /companies/{companyId}/security-settings). Rotate it before it expires and at least every 90 days. On password_expired, stop the integration and alert an operator.
Each operation carries x-required-role, the credential to use for it: reseller_admin, customer_admin or frontline_user.
Transport
-
HTTPS only, TLS 1.2 or later. Bodies are JSON, UTF-8.
-
Send
Authorization: Bearer <access_token> on every call except login and refresh.
-
Send a descriptive
User-Agent, e.g. riverbend-bi-sync/1.0.
-
Send
X-Request-ID to have your own id echoed back as error.request_id.
-
Identifiers are UUID strings. Don't depend on their version or order.
-
Times are RFC 3339 in UTC.
-
Phone numbers are usually E.164 (
+15555550142). Staff lines appear as extensions (2101).
Some records carry 10-digit numbers without +1. Normalise before you join.
Rules every client must follow
-
Unknown query parameters are silently ignored. The API returns 200 with unfiltered data.
Reject unsupported filters in your client before you send the request.
-
Only the first value of a repeated parameter is read. Use the comma form where a list is allowed.
-
Out of scope is 404, not 403. A record your login cannot see returns 404.
-
Admin logins get empty lists from the conversation-data endpoints (
/calls, /alerts,
/tasks) and 404 from call detail. Check role from GET /me at startup.
-
**Always call the API at
https://app.intelligence.cloud/api/v1**, whatever domain your users
sign in on.
-
Many writes are full replacement (marked in each operation). Read, merge, then write.
-
Only user create is idempotent, and there the
Idempotency-Key header is required.
-
Query strings longer than about 2,000 characters are refused with a non-JSON 404.
This caps
location_id lists at about 50 ids per request.
-
Never poll for new data. Subscribe to the After Call webhook (every call) and the First
Alert webhook (each alert as it fires) for anything that must happen as calls and alerts arrive.
Read the API when a person asks for something or when a webhook tells you to fetch details.
Run scheduled jobs (exports, digests, the nightly catch-up) no more than once a day, over a
bounded date window.
-
v1 is stable. Fields, endpoints and enum values are added without notice: ignore unknown fields
and treat unknown enum values as "other". At least 90 days' notice is given, by email to partner
contacts and in the guide's changelog, before documented behaviour is removed or changed, except
where a security, legal or abuse reason requires a faster change. Undocumented behaviour
(unknown parameters, default windows, search ranking) may change: send only documented
parameters and always send both dates.
-
Tokens, passwords, phone-system keys, webhook URLs and recording links are secrets. Never log them,
email them or put them in tickets. Report a suspected exposure of a secret or of conversation
data to security@tresic.cloud straight away, copying your Tresic contact, and rotate the secret.
For help with an integration, write to support@tresic.cloud.
Rate limits
Login: 5 per minute per IP. Refresh: 20 per minute per IP. Log in once per job and reuse the token. On any endpoint, back off on 429 and 503 with jitter, honouring Retry-After when present.
Terms
Use of this API is governed by the API and SDK Terms (termsOfService), which supplement your agreement with Tresic or your provider.
Roles
Each operation shows the credential it needs.
Reseller admin Customer admin Frontline user
Start
Errors and paging
Standard error. Branch on the HTTP status, then on error.code. Codes include BAD_REQUEST, VALIDATION_ERROR, CONFLICT, NOT_FOUND, FORBIDDEN, ROLE_NOT_ASSIGNABLE, CONNECTOR_NOT_VALID, INVALID_EOD_TIME, INVALID_TIMEZONE, INVALID_FREQUENCY, and lower-case codes on sign-in and single sign-on. Some 422s carry no request_id. Show your own message to end users.
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid sentiment. Must be one of: crisis, very_negative, negative, mildly_negative, below_neutral, neutral, positive, none",
"request_id": "7b1e2c3d-4f5a-4b6c-8d9e-0f1a2b3c4d5e"
}
}
Variations: /tasks uses error.type instead of error.code. Requests rejected before they reach the service return a flat {"statusCode": 401, "message": "…"}. A missing Idempotency-Key returns {"error": "…"}.
| Status | Meaning |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 403 | This login's role cannot do this (FORBIDDEN). |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 409 | Conflict (duplicate name or email, already active or inactive). Read the message. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
Paging
-
Conversation data (
/calls, /alerts, /tasks) returns meta: {has_more, next_cursor, limit}.
-
Management lists return
pagination: {has_more, next_cursor, total_count}.
-
GET /resellers/{resellerId}/companies puts has_more, next_cursor and total_count at the top level.
-
Pass
next_cursor back as cursor, URL-encoded, until has_more is false. Send limit=100 for exports.
-
Default page sizes: 10 on
/calls and /alerts; 20 on most lists; 25 on company users, alert rules and topic calls.
Customer lifecycle (admin credentials)
Authentication
Sign in, renew and sign out. Access tokens last about 15 minutes.
POST
/auth/login
Frontline useralso Customer adminalso Reseller admin
Sign in
Exchange the integration user's email and password for an access token and a refresh token. Limited to 5 per minute per IP.
Integration users need MFA off. If MFA is on, the response is {"status": "mfa_required", …} with no tokens; treat it as a configuration error. An address that signs in through the company's own identity provider returns 409 federated_address: use a password user.
No bearer token needed.
Request body
| Field | Type | Description |
|---|
email required | string (email) | |
password required | string (password) | |
Example
{
"email": "integration@example.com",
"password": "<password>"
}
Responses
| Status | Meaning |
| 200 | Signed in, or a second factor is required. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | invalid_credentials, account_deactivated or account_not_activated. |
| 409 | federated_address: this address signs in through the company's identity provider. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 example
{
"access_token": "<access token>",
"refresh_token": "<refresh token>",
"token_type": "Bearer",
"expires_in": 899,
"user": {
"id": "0193b6c2-7c46-7d12-a3f9-8e2b6c1d4f57",
"user_type": "company_user",
"reseller_id": null,
"email": "integration@example.com",
"first_name": "Data",
"last_name": "Feed",
"display_name": "Data Feed",
"role": "frontline_user",
"scopes": [
"calls:read",
"alerts:read",
"insights:read"
]
}
}
POST
/auth/refresh
Frontline useralso Customer adminalso Reseller admin
Renew the access token
Returns a new access token and a new refresh token. Store the new refresh token; the old one is spent. Sending a spent refresh token again ends the session everywhere (401 renewal_replayed), so never send the same refresh token twice and never share one between processes. Renew before expires_in runs out, or after a 401. If refresh fails, sign in again. Limited to 20 per minute per IP.
No bearer token needed.
Request body
| Field | Type | Description |
|---|
refresh_token required | string | |
Example
{
"refresh_token": "<refresh token>"
}
Responses
| Status | Meaning |
| 200 | Renewed. Same body as login. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | refresh_token_invalid, refresh_token_expired, session_revoked or renewal_replayed. Sign in again. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
access_token required | string | Send as Authorization: Bearer <access_token>. Never log it. |
refresh_token required | string | Single use. Store the new one after every refresh. Never log it. |
token_type required | "Bearer" | |
expires_in required | integer | Seconds until the access token expires (about 900). |
user required | object | |
user.id | string (uuid) | |
user.user_type | "company_user" | "reseller_user" | |
user.reseller_id | string (uuid) | null | |
user.email | string (email) | |
user.first_name | string | |
user.last_name | string | |
user.display_name | string | |
user.role | "frontline_user" | "customer_admin" | "reseller_admin" | "reseller_support" | reseller_support has an admin's reach but is read-only. |
user.scopes | string[] | |
password_expired | boolean | Present and true when the password must be changed in the app. An integration must stop and alert an operator; a person sets a new password for the integration user in the app, then the secrets manager is updated and the integration signs in again. |
200 example
{
"access_token": "string",
"refresh_token": "string",
"token_type": "Bearer",
"expires_in": 0,
"user": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"user_type": "company_user",
"reseller_id": "0193b6c2-0000-7000-8000-000000000000",
"email": "user@example.com",
"first_name": "string",
"last_name": "string",
"display_name": "string",
"role": "frontline_user",
"scopes": [
"string"
]
},
"password_expired": true
}
POST
/auth/logout
Frontline useralso Customer adminalso Reseller admin
Sign out
Ends all of the user's sessions, not just this one: every refresh token the user holds stops working. If several jobs share one integration user, a logout in one job signs out the others. Most integrations never need to call this.
Responses
| Status | Meaning |
| 200 | Signed out everywhere. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
message | string | |
200 example
{
"message": "Logged out successfully"
}
Customer lifecycle (admin credentials)
Resellers
Your reseller's branding and outbound email (SMTP) settings.
GET
/resellers/{resellerId}/branding
Reseller admin
Read reseller branding
Branding used in the app and in emails for all your customers. A company can override it.
Parameters
| Name | In | Type | Description |
resellerId required | path | string (uuid) | Your reseller id (reseller_id from GET /me). |
Responses
| Status | Meaning |
| 200 | Branding. Unset fields are null. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | string | |
data.attributes | object | |
data.attributes.reseller_id | string (uuid) | |
data.attributes.display_name | string | null | |
data.attributes.primary_accent_color | string | null | |
data.attributes.secondary_accent_color | string | null | |
data.attributes.support_email | string | null | |
data.attributes.support_portal_url | string | null | |
data.attributes.privacy_policy_url | string | null | |
data.attributes.terms_of_service_url | string | null | |
data.attributes.copyright_text | string | null | |
data.attributes.main_logo_url | string | null | Set in the Admin UI |
data.attributes.favicon_url | string | null | Set in the Admin UI |
data.attributes.email_logo_url | string | null | Set in the Admin UI |
data.attributes.created_at | string (date-time) | null | |
data.attributes.updated_at | string (date-time) | null | |
200 example
{
"data": {
"type": "reseller_branding",
"attributes": {
"reseller_id": "0193b6c2-41d8-7e0a-9c55-2f7d1e3a9b10",
"display_name": "Harborview Intelligence",
"primary_accent_color": "#1F6FB2",
"secondary_accent_color": "#4B5563",
"support_email": "support@example.com",
"support_portal_url": "https://support.example.com",
"privacy_policy_url": "https://example.com/privacy",
"terms_of_service_url": "https://example.com/terms",
"copyright_text": "© 2026 Harborview Communications",
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
}
PATCH
/resellers/{resellerId}/branding
Reseller admin
Update reseller branding
Partial update: only the fields you send change. Colours are #RRGGBB. URLs are http(s). Logos, favicon and background images are set in the Admin UI (White-labeling), or by your Tresic contact.
Parameters
| Name | In | Type | Description |
resellerId required | path | string (uuid) | Your reseller id (reseller_id from GET /me). |
Request body
| Field | Type | Description |
|---|
display_name | string | Product name shown in the app and in emails. max length 200 |
primary_accent_color | string | pattern ^#[0-9A-Fa-f]{6}$ |
secondary_accent_color | string | pattern ^#[0-9A-Fa-f]{6}$ |
support_email | string (email) | max length 255 |
support_portal_url | string (uri) | max length 2048 |
privacy_policy_url | string (uri) | max length 2048 |
terms_of_service_url | string (uri) | max length 2048 |
copyright_text | string | max length 500 |
Example
{
"display_name": "Harborview Intelligence",
"primary_accent_color": "#1F6FB2",
"support_email": "support@example.com"
}
Responses
| Status | Meaning |
| 200 | Updated branding. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | string | |
data.attributes | object | |
data.attributes.reseller_id | string (uuid) | |
data.attributes.display_name | string | null | |
data.attributes.primary_accent_color | string | null | |
data.attributes.secondary_accent_color | string | null | |
data.attributes.support_email | string | null | |
data.attributes.support_portal_url | string | null | |
data.attributes.privacy_policy_url | string | null | |
data.attributes.terms_of_service_url | string | null | |
data.attributes.copyright_text | string | null | |
data.attributes.main_logo_url | string | null | Set in the Admin UI |
data.attributes.favicon_url | string | null | Set in the Admin UI |
data.attributes.email_logo_url | string | null | Set in the Admin UI |
data.attributes.created_at | string (date-time) | null | |
data.attributes.updated_at | string (date-time) | null | |
200 example
{
"data": {
"type": "string",
"attributes": {
"reseller_id": "0193b6c2-0000-7000-8000-000000000000",
"display_name": "string",
"primary_accent_color": "string",
"secondary_accent_color": "string",
"support_email": "string",
"support_portal_url": "string",
"privacy_policy_url": "string",
"terms_of_service_url": "string",
"copyright_text": "string",
"main_logo_url": "string",
"favicon_url": "string",
"email_logo_url": "string",
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
}
GET
/resellers/{resellerId}/smtp-settings
Reseller admin
Read outbound email (SMTP) settings
One SMTP relay covers all your customers. With none set, email goes out from the platform sender with your branding in the message. The password is always masked.
Parameters
| Name | In | Type | Description |
resellerId required | path | string (uuid) | Your reseller id (reseller_id from GET /me). |
Responses
| Status | Meaning |
| 200 | Settings. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | No SMTP settings are configured. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | string | |
data.attributes | object | |
data.attributes.reseller_id | string (uuid) | |
data.attributes.smtp_host | string | |
data.attributes.smtp_port | integer | |
data.attributes.smtp_username | string | |
data.attributes.smtp_password | string | Always masked. |
data.attributes.sender_name | string | |
data.attributes.sender_email | string (email) | |
data.attributes.created_at | string (date-time) | |
data.attributes.updated_at | string (date-time) | |
200 example
{
"data": {
"type": "smtp_settings",
"attributes": {
"reseller_id": "0193b6c2-41d8-7e0a-9c55-2f7d1e3a9b10",
"smtp_host": "smtp.example.com",
"smtp_port": 587,
"smtp_username": "relay-user",
"smtp_password": "••••••••",
"sender_name": "Harborview Intelligence",
"sender_email": "noreply@example.com",
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
}
PATCH
/resellers/{resellerId}/smtp-settings
Reseller admin
Save outbound email (SMTP) settings
Saves the whole relay definition. The platform tests the connection and sign-in before saving: 200 or 201 means tested and saved, 422 means the test failed (sign-in, TLS or connect). Use port 587 (STARTTLS) or 465 (implicit TLS). The test proves sign-in only; send a real email to confirm the relay accepts mail from sender_email.
Parameters
| Name | In | Type | Description |
resellerId required | path | string (uuid) | Your reseller id (reseller_id from GET /me). |
Request body
| Field | Type | Description |
|---|
smtp_host required | string | |
smtp_port required | integer | 587 (STARTTLS) is recommended; 465 is implicit TLS. min 1, max 65535 |
smtp_username | string | |
smtp_password | string (password) | Stored encrypted. Never returned. |
sender_name required | string | max length 200 |
sender_email required | string (email) | |
Example
{
"smtp_host": "smtp.example.com",
"smtp_port": 587,
"smtp_username": "relay-user",
"smtp_password": "<password>",
"sender_name": "Harborview Intelligence",
"sender_email": "noreply@example.com"
}
Responses
| Status | Meaning |
| 200 | Tested and saved (updated). |
| 201 | Tested and saved (first time). |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 422 | The connection test failed. Nothing was saved. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | string | |
data.attributes | object | |
data.attributes.reseller_id | string (uuid) | |
data.attributes.smtp_host | string | |
data.attributes.smtp_port | integer | |
data.attributes.smtp_username | string | |
data.attributes.smtp_password | string | Always masked. |
data.attributes.sender_name | string | |
data.attributes.sender_email | string (email) | |
data.attributes.created_at | string (date-time) | |
data.attributes.updated_at | string (date-time) | |
200 example
{
"data": {
"type": "string",
"attributes": {
"reseller_id": "0193b6c2-0000-7000-8000-000000000000",
"smtp_host": "string",
"smtp_port": 0,
"smtp_username": "string",
"smtp_password": "string",
"sender_name": "string",
"sender_email": "user@example.com",
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
}
DELETE
/resellers/{resellerId}/smtp-settings
Reseller admin
Remove outbound email (SMTP) settings
Email goes back to the platform sender.
Parameters
| Name | In | Type | Description |
resellerId required | path | string (uuid) | Your reseller id (reseller_id from GET /me). |
Responses
| Status | Meaning |
| 204 | Removed. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
Customer lifecycle (admin credentials)
Companies
Customer companies. Each customer is one company.
GET
/resellers/{resellerId}/companies
Reseller admin
List customer companies
Paging fields are at the top level of this response (no pagination object). Filters combine with AND.
Parameters
| Name | In | Type | Description |
resellerId required | path | string (uuid) | Your reseller id (reseller_id from GET /me). |
search | query | string | Case-insensitive prefix match on company_name only. "Riverbend" matches "Riverbend Auto Group"; "Auto Group" does not. |
is_active | query | boolean | true for active companies, false for deactivated ones.
|
limit | query | integer | Page size. Send 100 and follow next_cursor. min 1, max 100, default 20 |
cursor | query | string | Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400. |
Responses
| Status | Meaning |
| 200 | One page of companies. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object[] | |
data[].type | "company" | |
data[].attributes | object | |
data[].attributes.id | string (uuid) | |
data[].attributes.reseller_id | string (uuid) | |
data[].attributes.reseller_name | string | Empty in the create response. |
data[].attributes.company_name | string | |
data[].attributes.company_code | string | null | |
data[].attributes.vertical | string | null | |
data[].attributes.address | string | null | |
data[].attributes.primary_admin_contact_name | string | |
data[].attributes.primary_admin_contact_email | string (email) | |
data[].attributes.primary_admin_contact_phone | string | |
data[].attributes.enabled_products | "after-call-copilot" | "first-alert-copilot" | "insights-hub"[] | |
data[].attributes.is_active | boolean | |
data[].attributes.mfa_enforced | boolean | |
data[].attributes.mfa_available | boolean | Single read only. |
data[].attributes.location_count | integer | Correct on list rows; 0 on single reads. |
data[].attributes.user_count | integer | Correct on list rows; 0 on single reads. |
data[].attributes.created_at | string (date-time) | |
data[].attributes.updated_at | string (date-time) | |
has_more | boolean | |
next_cursor | string | null | |
total_count | integer | |
200 example
{
"data": [
{
"type": "company",
"attributes": {
"id": "0193b6c2-5a11-7c3e-8f20-6d4b9e1c2a77",
"reseller_id": "0193b6c2-41d8-7e0a-9c55-2f7d1e3a9b10",
"reseller_name": "Harborview Communications",
"company_name": "Riverbend Auto Group",
"company_code": "RIVERBEND",
"primary_admin_contact_name": "Jordan Lee",
"primary_admin_contact_email": "jordan.lee@example.com",
"primary_admin_contact_phone": "+15555550142",
"enabled_products": [
"after-call-copilot",
"first-alert-copilot",
"insights-hub"
],
"is_active": true,
"mfa_enforced": false,
"location_count": 3,
"user_count": 18,
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:06:12Z"
}
}
],
"has_more": false,
"total_count": 1
}
POST
/resellers/{resellerId}/companies
Reseller admin
Create a customer company
Creates the company and always emails an invitation (7-day expiry) to the primary contact, who becomes the company's customer_admin.
-
primary_admin_contact_email must be unique across the whole platform (409).
-
Not idempotent: a retry after a lost response returns 409. Look the company up with
GET /resellers/{resellerId}/companies?search=<name> before retrying.
-
MFA follows your reseller default. To turn it off for an integration user's company,
PATCH /companies/{companyId} with mfa_enforced: false after create, then read it back.
-
vertical and address are set with PATCH after create.
Parameters
| Name | In | Type | Description |
resellerId required | path | string (uuid) | Your reseller id (reseller_id from GET /me). |
Request body
| Field | Type | Description |
|---|
company_name required | string | min length 2, max length 200 |
company_code | string | max length 50 |
primary_admin_contact_name required | string | min length 2, max length 100 |
primary_admin_contact_email required | string (email) | Unique on the platform. This person is invited as customer admin. |
primary_admin_contact_phone required | string | |
enabled_products | "after-call-copilot" | "first-alert-copilot" | "insights-hub"[] | |
Example
{
"company_name": "Riverbend Auto Group",
"company_code": "RIVERBEND",
"primary_admin_contact_name": "Jordan Lee",
"primary_admin_contact_email": "jordan.lee@example.com",
"primary_admin_contact_phone": "+15555550142",
"enabled_products": [
"after-call-copilot",
"first-alert-copilot",
"insights-hub"
]
}
Responses
| Status | Meaning |
| 201 | Created. invited_user is the primary contact. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 409 | The contact email is already in use on the platform (this also catches a retried create). |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
201 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "company" | |
data.attributes | object | |
data.attributes.id | string (uuid) | |
data.attributes.reseller_id | string (uuid) | |
data.attributes.reseller_name | string | Empty in the create response. |
data.attributes.company_name | string | |
data.attributes.company_code | string | null | |
data.attributes.vertical | string | null | |
data.attributes.address | string | null | |
data.attributes.primary_admin_contact_name | string | |
data.attributes.primary_admin_contact_email | string (email) | |
data.attributes.primary_admin_contact_phone | string | |
data.attributes.enabled_products | "after-call-copilot" | "first-alert-copilot" | "insights-hub"[] | |
data.attributes.is_active | boolean | |
data.attributes.mfa_enforced | boolean | |
data.attributes.mfa_available | boolean | Single read only. |
data.attributes.location_count | integer | Correct on list rows; 0 on single reads. |
data.attributes.user_count | integer | Correct on list rows; 0 on single reads. |
data.attributes.created_at | string (date-time) | |
data.attributes.updated_at | string (date-time) | |
invited_user | object | |
invited_user.id | string (uuid) | |
invited_user.email | string (email) | |
invited_user.display_name | string | |
invited_user.status | "invited" | |
invited_user.role | "customer_admin" | |
invited_user.invited_at | string (date-time) | |
invited_user.invite_expires_at | string (date-time) | |
201 example
{
"data": {
"type": "company",
"attributes": {
"id": "0193b6c2-5a11-7c3e-8f20-6d4b9e1c2a77",
"reseller_id": "0193b6c2-41d8-7e0a-9c55-2f7d1e3a9b10",
"reseller_name": "",
"company_name": "Riverbend Auto Group",
"company_code": "RIVERBEND",
"primary_admin_contact_name": "Jordan Lee",
"primary_admin_contact_email": "jordan.lee@example.com",
"primary_admin_contact_phone": "+15555550142",
"enabled_products": [
"after-call-copilot",
"first-alert-copilot",
"insights-hub"
],
"is_active": true,
"mfa_enforced": true,
"location_count": 0,
"user_count": 0,
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
},
"invited_user": {
"id": "0193b6c2-5a12-7c3e-8f20-6d4b9e1c2a78",
"email": "jordan.lee@example.com",
"display_name": "Jordan Lee",
"status": "invited",
"role": "customer_admin",
"invited_at": "2026-11-02T15:04:05Z",
"invite_expires_at": "2026-11-09T15:04:05Z"
}
}
GET
/resellers/{resellerId}/companies/mfa
Reseller admin
Read the MFA default for new companies
companies_mfa_default is the mfa_enforced value every new company starts with.
Parameters
| Name | In | Type | Description |
resellerId required | path | string (uuid) | Your reseller id (reseller_id from GET /me). |
Responses
| Status | Meaning |
| 200 | MFA summary. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.total_active | integer | |
data.with_mfa_required | integer | |
data.companies_mfa_default | boolean | |
data.mfa_available | boolean | |
200 example
{
"data": {
"total_active": 6,
"with_mfa_required": 2,
"companies_mfa_default": true,
"mfa_available": true
}
}
GET
/companies/{companyId}
Reseller admin
Read a company
location_count and user_count read 0 on this endpoint. Use the list row, or count locations and users yourself.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | The company. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "company" | |
data.attributes | object | |
data.attributes.id | string (uuid) | |
data.attributes.reseller_id | string (uuid) | |
data.attributes.reseller_name | string | Empty in the create response. |
data.attributes.company_name | string | |
data.attributes.company_code | string | null | |
data.attributes.vertical | string | null | |
data.attributes.address | string | null | |
data.attributes.primary_admin_contact_name | string | |
data.attributes.primary_admin_contact_email | string (email) | |
data.attributes.primary_admin_contact_phone | string | |
data.attributes.enabled_products | "after-call-copilot" | "first-alert-copilot" | "insights-hub"[] | |
data.attributes.is_active | boolean | |
data.attributes.mfa_enforced | boolean | |
data.attributes.mfa_available | boolean | Single read only. |
data.attributes.location_count | integer | Correct on list rows; 0 on single reads. |
data.attributes.user_count | integer | Correct on list rows; 0 on single reads. |
data.attributes.created_at | string (date-time) | |
data.attributes.updated_at | string (date-time) | |
200 example
{
"data": {
"type": "company",
"attributes": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"reseller_id": "0193b6c2-0000-7000-8000-000000000000",
"reseller_name": "string",
"company_name": "string",
"company_code": "string",
"vertical": "string",
"address": "string",
"primary_admin_contact_name": "string",
"primary_admin_contact_email": "user@example.com",
"primary_admin_contact_phone": "string",
"enabled_products": [
"after-call-copilot"
],
"is_active": true,
"mfa_enforced": true,
"mfa_available": true,
"location_count": 0,
"user_count": 0,
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
}
PATCH
/companies/{companyId}
Reseller admin
Update a company
Every field is optional.
-
**
enabled_products is a full replacement.** Sending two keys turns the third product off.
An empty list is ignored, so you cannot clear all products this way.
-
mfa_enforced: false turns MFA off for the company (required for integration users).
-
Works on a deactivated company.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
Request body
| Field | Type | Description |
|---|
company_name | string | min length 2, max length 200 |
company_code | string | max length 50 |
primary_admin_contact_name | string | min length 2, max length 100 |
primary_admin_contact_email | string (email) | |
primary_admin_contact_phone | string | |
enabled_products | "after-call-copilot" | "first-alert-copilot" | "insights-hub"[] | Full replacement. min items 1 |
vertical | string | Free text label. max length 100 |
address | string | max length 500 |
mfa_enforced | boolean | Must be a JSON boolean. |
Example
{
"mfa_enforced": false,
"vertical": "Auto dealership",
"address": "100 River Rd, Springfield, IL 62701"
}
Responses
| Status | Meaning |
| 200 | Updated company. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "company" | |
data.attributes | object | |
data.attributes.id | string (uuid) | |
data.attributes.reseller_id | string (uuid) | |
data.attributes.reseller_name | string | Empty in the create response. |
data.attributes.company_name | string | |
data.attributes.company_code | string | null | |
data.attributes.vertical | string | null | |
data.attributes.address | string | null | |
data.attributes.primary_admin_contact_name | string | |
data.attributes.primary_admin_contact_email | string (email) | |
data.attributes.primary_admin_contact_phone | string | |
data.attributes.enabled_products | "after-call-copilot" | "first-alert-copilot" | "insights-hub"[] | |
data.attributes.is_active | boolean | |
data.attributes.mfa_enforced | boolean | |
data.attributes.mfa_available | boolean | Single read only. |
data.attributes.location_count | integer | Correct on list rows; 0 on single reads. |
data.attributes.user_count | integer | Correct on list rows; 0 on single reads. |
data.attributes.created_at | string (date-time) | |
data.attributes.updated_at | string (date-time) | |
200 example
{
"data": {
"type": "company",
"attributes": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"reseller_id": "0193b6c2-0000-7000-8000-000000000000",
"reseller_name": "string",
"company_name": "string",
"company_code": "string",
"vertical": "string",
"address": "string",
"primary_admin_contact_name": "string",
"primary_admin_contact_email": "user@example.com",
"primary_admin_contact_phone": "string",
"enabled_products": [
"after-call-copilot"
],
"is_active": true,
"mfa_enforced": true,
"mfa_available": true,
"location_count": 0,
"user_count": 0,
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
}
POST
/companies/{companyId}/deactivate
Reseller admin
Deactivate a company
Suspends the company and blocks its sign-ins. Reads and PATCH still work. There is no company delete.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | Deactivated (is_active: false). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 409 | Conflict (duplicate name or email, already active or inactive). Read the message. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "company" | |
data.attributes | object | |
data.attributes.id | string (uuid) | |
data.attributes.reseller_id | string (uuid) | |
data.attributes.reseller_name | string | Empty in the create response. |
data.attributes.company_name | string | |
data.attributes.company_code | string | null | |
data.attributes.vertical | string | null | |
data.attributes.address | string | null | |
data.attributes.primary_admin_contact_name | string | |
data.attributes.primary_admin_contact_email | string (email) | |
data.attributes.primary_admin_contact_phone | string | |
data.attributes.enabled_products | "after-call-copilot" | "first-alert-copilot" | "insights-hub"[] | |
data.attributes.is_active | boolean | |
data.attributes.mfa_enforced | boolean | |
data.attributes.mfa_available | boolean | Single read only. |
data.attributes.location_count | integer | Correct on list rows; 0 on single reads. |
data.attributes.user_count | integer | Correct on list rows; 0 on single reads. |
data.attributes.created_at | string (date-time) | |
data.attributes.updated_at | string (date-time) | |
200 example
{
"data": {
"type": "company",
"attributes": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"reseller_id": "0193b6c2-0000-7000-8000-000000000000",
"reseller_name": "string",
"company_name": "string",
"company_code": "string",
"vertical": "string",
"address": "string",
"primary_admin_contact_name": "string",
"primary_admin_contact_email": "user@example.com",
"primary_admin_contact_phone": "string",
"enabled_products": [
"after-call-copilot"
],
"is_active": true,
"mfa_enforced": true,
"mfa_available": true,
"location_count": 0,
"user_count": 0,
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
}
POST
/companies/{companyId}/reactivate
Reseller admin
Reactivate a company
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | Reactivated. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 409 | Conflict (duplicate name or email, already active or inactive). Read the message. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "company" | |
data.attributes | object | |
data.attributes.id | string (uuid) | |
data.attributes.reseller_id | string (uuid) | |
data.attributes.reseller_name | string | Empty in the create response. |
data.attributes.company_name | string | |
data.attributes.company_code | string | null | |
data.attributes.vertical | string | null | |
data.attributes.address | string | null | |
data.attributes.primary_admin_contact_name | string | |
data.attributes.primary_admin_contact_email | string (email) | |
data.attributes.primary_admin_contact_phone | string | |
data.attributes.enabled_products | "after-call-copilot" | "first-alert-copilot" | "insights-hub"[] | |
data.attributes.is_active | boolean | |
data.attributes.mfa_enforced | boolean | |
data.attributes.mfa_available | boolean | Single read only. |
data.attributes.location_count | integer | Correct on list rows; 0 on single reads. |
data.attributes.user_count | integer | Correct on list rows; 0 on single reads. |
data.attributes.created_at | string (date-time) | |
data.attributes.updated_at | string (date-time) | |
200 example
{
"data": {
"type": "company",
"attributes": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"reseller_id": "0193b6c2-0000-7000-8000-000000000000",
"reseller_name": "string",
"company_name": "string",
"company_code": "string",
"vertical": "string",
"address": "string",
"primary_admin_contact_name": "string",
"primary_admin_contact_email": "user@example.com",
"primary_admin_contact_phone": "string",
"enabled_products": [
"after-call-copilot"
],
"is_active": true,
"mfa_enforced": true,
"mfa_available": true,
"location_count": 0,
"user_count": 0,
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
}
GET
/companies/{companyId}/security-settings
Reseller admin
Read a company's security settings
The company's password policy, session timeout and sign-in IP ranges. Password policy fields are inherited from the reseller unless the company overrides them (password_policy_source, password_policy_inherited_fields). An integration user's password follows this policy: rotate it before password_expiry_days runs out, and at least every 90 days.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | The company's security settings. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 403 | This login's role cannot do this (FORBIDDEN). |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.min_password_length | integer | Minimum password length. |
data.require_uppercase | boolean | |
data.require_numbers | boolean | |
data.require_special_chars | boolean | |
data.password_expiry_days | integer | null | Days until a password expires; null when passwords don't expire. |
data.session_timeout_minutes | integer | Idle minutes before a web sign-in ends. |
data.allowed_ip_ranges | string[] | CIDR ranges allowed to sign in. Empty means any address. |
data.password_policy_source | string | reseller when the policy is inherited from the reseller, otherwise company. |
data.password_policy_inherited_fields | string[] | Password policy fields inherited from the reseller. |
200 example
{
"data": {
"min_password_length": 12,
"require_uppercase": true,
"require_numbers": true,
"require_special_chars": true,
"password_expiry_days": 90,
"session_timeout_minutes": 30,
"allowed_ip_ranges": [],
"password_policy_source": "reseller",
"password_policy_inherited_fields": [
"min_password_length",
"require_uppercase",
"require_numbers",
"require_special_chars",
"password_expiry_days"
]
}
}
GET
/companies/{companyId}/branding
Reseller adminalso Customer admin
Read company branding overrides
Company values override the reseller's. Null means the reseller value applies.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | Company branding. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "company_branding" | |
data.attributes | object | |
data.attributes.company_id | string (uuid) | |
data.attributes.display_name | string | null | |
data.attributes.primary_accent_color | string | null | |
data.attributes.secondary_accent_color | string | null | |
data.attributes.support_email | string | null | |
data.attributes.privacy_policy_url | string | null | |
data.attributes.terms_of_service_url | string | null | |
data.attributes.copyright_text | string | null | |
data.attributes.company_logo_url | string | null | Set in the Admin UI |
data.attributes.favicon_url | string | null | Set in the Admin UI |
data.attributes.email_header_logo_url | string | null | Set in the Admin UI |
data.attributes.created_at | string (date-time) | null | |
data.attributes.updated_at | string (date-time) | null | |
200 example
{
"data": {
"type": "company_branding",
"attributes": {
"company_id": "0193b6c2-0000-7000-8000-000000000000",
"display_name": "string",
"primary_accent_color": "string",
"secondary_accent_color": "string",
"support_email": "string",
"privacy_policy_url": "string",
"terms_of_service_url": "string",
"copyright_text": "string",
"company_logo_url": "string",
"favicon_url": "string",
"email_header_logo_url": "string",
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
}
PATCH
/companies/{companyId}/branding
Reseller adminalso Customer admin
Update company branding overrides
Partial update. Colours are #RRGGBB. Images are set in the Admin UI, or by your Tresic contact.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
Request body
| Field | Type | Description |
|---|
display_name | string | max length 200 |
primary_accent_color | string | pattern ^#[0-9A-Fa-f]{6}$ |
secondary_accent_color | string | pattern ^#[0-9A-Fa-f]{6}$ |
support_email | string (email) | max length 255 |
privacy_policy_url | string (uri) | max length 2048 |
terms_of_service_url | string (uri) | max length 2048 |
copyright_text | string | max length 500 |
Example
{
"display_name": "Riverbend Insights",
"primary_accent_color": "#0B5D3B"
}
Responses
| Status | Meaning |
| 200 | Updated. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "company_branding" | |
data.attributes | object | |
data.attributes.company_id | string (uuid) | |
data.attributes.display_name | string | null | |
data.attributes.primary_accent_color | string | null | |
data.attributes.secondary_accent_color | string | null | |
data.attributes.support_email | string | null | |
data.attributes.privacy_policy_url | string | null | |
data.attributes.terms_of_service_url | string | null | |
data.attributes.copyright_text | string | null | |
data.attributes.company_logo_url | string | null | Set in the Admin UI |
data.attributes.favicon_url | string | null | Set in the Admin UI |
data.attributes.email_header_logo_url | string | null | Set in the Admin UI |
data.attributes.created_at | string (date-time) | null | |
data.attributes.updated_at | string (date-time) | null | |
200 example
{
"data": {
"type": "company_branding",
"attributes": {
"company_id": "0193b6c2-0000-7000-8000-000000000000",
"display_name": "string",
"primary_accent_color": "string",
"secondary_accent_color": "string",
"support_email": "string",
"privacy_policy_url": "string",
"terms_of_service_url": "string",
"copyright_text": "string",
"company_logo_url": "string",
"favicon_url": "string",
"email_header_logo_url": "string",
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
}
Customer lifecycle (admin credentials)
Single sign-on
Claim and verify the customer's email domain, then connect its OpenID Connect provider. Order: claim domain, customer publishes the DNS TXT record, verify, connect the provider. Reseller admins do this; customer admins cannot.
GET
/companies/{companyId}/domains
Reseller admin
List claimed domains
Not paged.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | Domains. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object[] | |
data[].id | string (uuid) | |
data[].domain | string | |
data[].status | string | pending until the TXT record is found, then verified. |
data[].verification | object | |
data[].verification.type | "TXT" | |
data[].verification.name | string | Record name, _ic-verify.<domain>. |
data[].verification.value | string | |
data[].verified_at | string (date-time) | null | |
data[].last_checked_at | string (date-time) | null | |
data[].last_failure_reason | string | null | |
200 example
{
"data": [
{
"id": "0193b6c2-0000-7000-8000-000000000000",
"domain": "string",
"status": "string",
"verification": {
"type": "TXT",
"name": "string",
"value": "string"
},
"verified_at": "2026-11-02T15:04:05Z",
"last_checked_at": "2026-11-02T15:04:05Z",
"last_failure_reason": "string"
}
]
}
POST
/companies/{companyId}/domains
Reseller admin
Claim a domain
Returns the DNS TXT record the customer must publish (verification.name and verification.value). Claiming the same domain again returns the same record (200). Never remove and re-add a claim: that issues a new value. Consumer mail domains are refused (409 consumer_domain_not_allowed).
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
Request body
| Field | Type | Description |
|---|
domain required | string | max length 253 |
Example
{
"domain": "riverbendauto.example.com"
}
Responses
| Status | Meaning |
| 200 | Already claimed. Same record. |
| 201 | Claimed. Pending verification. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 409 | Conflict (duplicate name or email, already active or inactive). Read the message. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.id | string (uuid) | |
data.domain | string | |
data.status | string | pending until the TXT record is found, then verified. |
data.verification | object | |
data.verification.type | "TXT" | |
data.verification.name | string | Record name, _ic-verify.<domain>. |
data.verification.value | string | |
data.verified_at | string (date-time) | null | |
data.last_checked_at | string (date-time) | null | |
data.last_failure_reason | string | null | |
200 example
{
"data": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"domain": "string",
"status": "string",
"verification": {
"type": "TXT",
"name": "string",
"value": "string"
},
"verified_at": "2026-11-02T15:04:05Z",
"last_checked_at": "2026-11-02T15:04:05Z",
"last_failure_reason": "string"
}
}
DELETE
/companies/{companyId}/domains/{domainId}
Reseller admin
Remove a domain claim
Returns 204, also when already removed.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
domainId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 204 | Removed. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
GET
/companies/{companyId}/domains/{domainId}/verifications
Reseller admin
List verification attempts
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
domainId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | History, newest first. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object[] | |
data[].checked_at | string (date-time) | |
data[].status | string | |
data[].failure_reason | string | null | |
200 example
{
"data": [
{
"checked_at": "2026-11-02T15:04:05Z",
"status": "string",
"failure_reason": "string"
}
]
}
POST
/companies/{companyId}/domains/{domainId}/verifications
Reseller admin
Check the TXT record now
A failed check is a 200 with status: pending and a failure_reason. DNS can take minutes, occasionally days, to show the record. Retry later.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
domainId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | Check result. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.checked_at | string (date-time) | |
data.status | string | |
data.failure_reason | string | null | |
200 example
{
"data": {
"checked_at": "2026-11-02T15:10:00Z",
"status": "pending",
"failure_reason": "No matching TXT record at _ic-verify.riverbendauto.example.com"
}
}
GET
/companies/{companyId}/identity-provider
Reseller admin
Read the identity provider connection
404 not_found when no provider is connected.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | The connection. The client secret is never returned. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.id | string (uuid) | |
data.display_name | string | |
data.type | string | |
data.is_active | boolean | |
data.issuer | string | |
data.well_known_endpoint | string | |
data.client_id | string | |
data.client_auth_method | string | |
data.supported_client_auth_methods | string[] | |
data.secret_held | boolean | |
data.link_callback_uri | string | The reply URL the customer registers with its provider. |
data.instructions | string[] | Steps for the customer's IdP admin. |
data.created_at | string (date-time) | |
200 example
{
"data": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"display_name": "string",
"type": "string",
"is_active": true,
"issuer": "string",
"well_known_endpoint": "string",
"client_id": "string",
"client_auth_method": "string",
"supported_client_auth_methods": [
"string"
],
"secret_held": true,
"link_callback_uri": "string",
"instructions": [
"string"
],
"created_at": "2026-11-02T15:04:05Z"
}
}
POST
/companies/{companyId}/identity-provider
Reseller admin
Connect an OpenID Connect provider
Works with any OpenID Connect provider. Needs at least one verified domain first (422 no_verified_domain). One provider per company; one company per issuer.
After connecting, give the customer's IdP admin the link_callback_uri and the steps in instructions[]. Then create users with auth_method: sso. Test sign-in and invitations on your own sign-in domain before adding users.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
Request body
| Field | Type | Description |
|---|
type required | "oidc" | OpenID Connect only. |
display_name required | string | max length 200 |
issuer required | string | |
well_known_endpoint required | string (uri) | Full HTTPS address of the provider's /.well-known/openid-configuration. |
client_id required | string | |
client_auth_method | "client_secret" | "none" | none for a public client (PKCE only). default "client_secret" |
client_secret | string (password) | Required with client_secret. Write-only. |
secret_expires_at | string (date-time) | |
acknowledgement required | "true" | "yes" | "acknowledged" | "1" | Sending it confirms: anyone who can sign in at this login system will be able to sign in to Intelligence Cloud as a member of this company, and the checks that decide who that is, including any second factor, are made by this login system and not by Intelligence Cloud. |
Example
{
"type": "oidc",
"display_name": "Riverbend sign-in",
"issuer": "https://login.example.com/riverbend",
"well_known_endpoint": "https://login.example.com/riverbend/.well-known/openid-configuration",
"client_id": "6c1f2e3d-4b5a-4978-8e1d-0a2b3c4d5e6f",
"client_auth_method": "client_secret",
"client_secret": "<client secret>",
"acknowledgement": "true"
}
Responses
| Status | Meaning |
| 201 | Connected. |
| 400 | invalid_request, acknowledgement_required or unsafe_endpoint. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 409 | already_connected or issuer_already_in_use. |
| 422 | no_verified_domain. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
201 response fields
| Field | Type | Description |
|---|
data | object | |
data.id | string (uuid) | |
data.display_name | string | |
data.type | string | |
data.is_active | boolean | |
data.issuer | string | |
data.well_known_endpoint | string | |
data.client_id | string | |
data.client_auth_method | string | |
data.supported_client_auth_methods | string[] | |
data.secret_held | boolean | |
data.link_callback_uri | string | The reply URL the customer registers with its provider. |
data.instructions | string[] | Steps for the customer's IdP admin. |
data.created_at | string (date-time) | |
201 example
{
"data": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"display_name": "string",
"type": "string",
"is_active": true,
"issuer": "string",
"well_known_endpoint": "string",
"client_id": "string",
"client_auth_method": "string",
"supported_client_auth_methods": [
"string"
],
"secret_held": true,
"link_callback_uri": "string",
"instructions": [
"string"
],
"created_at": "2026-11-02T15:04:05Z"
}
}
DELETE
/companies/{companyId}/identity-provider
Reseller admin
Disconnect the identity provider
Returns 204, also when nothing is connected.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 204 | Disconnected. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
POST
/companies/{companyId}/identity-provider/test
Reseller admin
Test the identity provider connection
Checks that the provider is reachable and correctly described. 404 when nothing is connected.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | Test result. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.reachable | boolean | |
data.checks | object[] | |
data.checks[].name | string | |
data.checks[].outcome | string | |
data.checks[].detail | string | |
200 example
{
"data": {
"reachable": true,
"checks": [
{
"name": "string",
"outcome": "string",
"detail": "string"
}
]
}
}
Customer lifecycle (admin credentials)
Products
Products are switched on at three levels and all three must be on: company, location, user. Product keys: after-call-copilot, first-alert-copilot, insights-hub.
GET
/products
Reseller admin
List products
Responses
| Status | Meaning |
| 200 | Product catalogue. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object[] | |
data[].key | "after-call-copilot" | "first-alert-copilot" | "insights-hub" | |
data[].name | string | |
200 example
{
"data": [
{
"key": "after-call-copilot",
"name": "After Call Co-Pilot"
},
{
"key": "first-alert-copilot",
"name": "First Alert Co-Pilot"
},
{
"key": "insights-hub",
"name": "Insights Hub"
}
]
}
GET
/companies/{companyId}/products
Reseller admin
Company products
Change them with PATCH /companies/{companyId} (enabled_products, full replacement).
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | Each product and whether it is on. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object[] | |
data[].product_key | "after-call-copilot" | "first-alert-copilot" | "insights-hub" | |
data[].name | string | |
data[].enabled | boolean | |
data[].enabled_at | string (date-time) | null | |
data[].enabled_by | string (uuid) | null | |
200 example
{
"data": [
{
"product_key": "after-call-copilot",
"name": "string",
"enabled": true,
"enabled_at": "2026-11-02T15:04:05Z",
"enabled_by": "0193b6c2-0000-7000-8000-000000000000"
}
]
}
GET
/companies/{companyId}/users/{userId}/products
Reseller admin
A user's products
A user's products are per user, not per location.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
userId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | Each product and whether it is on for the user. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object[] | |
data[].product_key | "after-call-copilot" | "first-alert-copilot" | "insights-hub" | |
data[].name | string | |
data[].enabled | boolean | |
data[].enabled_at | string (date-time) | null | |
data[].enabled_by | string (uuid) | null | |
200 example
{
"data": [
{
"product_key": "after-call-copilot",
"name": "After Call Co-Pilot",
"enabled": true,
"enabled_at": "2026-11-02T15:20:00Z",
"enabled_by": "0193b6c2-41d9-7e0a-9c55-2f7d1e3a9b11"
},
{
"product_key": "first-alert-copilot",
"name": "First Alert Co-Pilot",
"enabled": false,
"enabled_at": null,
"enabled_by": null
},
{
"product_key": "insights-hub",
"name": "Insights Hub",
"enabled": false,
"enabled_at": null,
"enabled_by": null
}
]
}
POST
/locations/{locationId}/users/{userId}/products/{productKey}/enable
Reseller admin
Turn a product on for a user
The product must be on for the company and the location. Idempotent: repeating returns 200. The user must be assigned to the location.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
userId required | path | string (uuid) | |
productKey required | path | "after-call-copilot" | "first-alert-copilot" | "insights-hub" | |
Responses
| Status | Meaning |
| 200 | Product state. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 409 | Conflict (duplicate name or email, already active or inactive). Read the message. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.product_key | "after-call-copilot" | "first-alert-copilot" | "insights-hub" | |
data.name | string | |
data.enabled | boolean | |
data.enabled_at | string (date-time) | null | |
data.enabled_by | string (uuid) | null | |
200 example
{
"data": {
"product_key": "after-call-copilot",
"name": "After Call Co-Pilot",
"enabled": true,
"enabled_at": "2026-11-02T15:20:00Z",
"enabled_by": "0193b6c2-41d9-7e0a-9c55-2f7d1e3a9b11"
}
}
POST
/locations/{locationId}/users/{userId}/products/{productKey}/disable
Reseller admin
Turn a product off for a user
Idempotent. After a disable, enabled_at and enabled_by are null.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
userId required | path | string (uuid) | |
productKey required | path | "after-call-copilot" | "first-alert-copilot" | "insights-hub" | |
Responses
| Status | Meaning |
| 200 | Product state. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.product_key | "after-call-copilot" | "first-alert-copilot" | "insights-hub" | |
data.name | string | |
data.enabled | boolean | |
data.enabled_at | string (date-time) | null | |
data.enabled_by | string (uuid) | null | |
200 example
{
"data": {
"product_key": "after-call-copilot",
"name": "string",
"enabled": true,
"enabled_at": "2026-11-02T15:04:05Z",
"enabled_by": "0193b6c2-0000-7000-8000-000000000000"
}
}
Customer lifecycle (admin credentials)
Locations
Locations hold the customer's teams and departments. Full-product customers have a Management location, with no alert rules, for managers' own lines. A Base Intelligence Seat customer has one location: managers' own lines sit there, so their own calls can raise the two alerts. An extension belongs to exactly one location.
GET
/verticals
Reseller admin
List industries
Every location needs a vertical_id from this list.
Responses
| Status | Meaning |
| 200 | Industries. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object[] | |
data[].id | string (uuid) | |
data[].key | string | |
data[].name | string | |
data[].description | string | |
data[].is_active | boolean | |
data[].display_order | integer | |
200 example
{
"data": [
{
"id": "0193b6c2-0001-7000-8000-00000000c5b5",
"key": "csps-msps",
"name": "CSPs & MSPs (Service Providers)",
"description": "Communications and managed service providers",
"is_active": true,
"display_order": 4
}
]
}
GET
/companies/{companyId}/locations
Reseller admin
List a company's locations
Send limit=100 and follow next_cursor while has_more is true. Filters combine with AND.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
search | query | string | Case-insensitive substring match on location_name. |
is_active | query | boolean | |
limit | query | integer | Page size. Send 100 and follow next_cursor. min 1, max 100, default 20 |
cursor | query | string | Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400. |
offset | query | integer | Rows to skip. Prefer cursor. min 0 |
Responses
| Status | Meaning |
| 200 | One page of locations. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object[] | |
data[].type | "location" | |
data[].attributes | object | |
data[].attributes.id | string (uuid) | |
data[].attributes.company_id | string (uuid) | |
data[].attributes.company_name | string | |
data[].attributes.reseller_name | string | |
data[].attributes.location_name | string | |
data[].attributes.street | string | |
data[].attributes.city | string | |
data[].attributes.state | string | |
data[].attributes.country | string | |
data[].attributes.zipcode | string | |
data[].attributes.support_contact_name | string | |
data[].attributes.support_contact_email | string | |
data[].attributes.support_contact_phone | string | |
data[].attributes.vertical_id | string (uuid) | |
data[].attributes.vertical_name | string | |
data[].attributes.enabled_products | "after-call-copilot" | "first-alert-copilot" | "insights-hub"[] | |
data[].attributes.is_active | boolean | |
data[].attributes.user_count | integer | On list rows. |
data[].attributes.created_at | string (date-time) | |
data[].attributes.updated_at | string (date-time) | |
pagination | object | |
pagination.has_more | boolean | |
pagination.next_cursor | string | null | |
pagination.total_count | integer | |
200 example
{
"data": [
{
"type": "location",
"attributes": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"company_id": "0193b6c2-0000-7000-8000-000000000000",
"company_name": "string",
"reseller_name": "string",
"location_name": "string",
"street": "string",
"city": "string",
"state": "string",
"country": "string",
"zipcode": "string",
"support_contact_name": "string",
"support_contact_email": "string",
"support_contact_phone": "string",
"vertical_id": "0193b6c2-0000-7000-8000-000000000000",
"vertical_name": "string",
"enabled_products": [
"after-call-copilot"
],
"is_active": true,
"user_count": 0,
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
],
"pagination": {
"has_more": true,
"next_cursor": "string",
"total_count": 0
}
}
POST
/companies/{companyId}/locations
Reseller admin
Create a location
A new location has no alert rules. location_name is unique within the company (409). enabled_products must be a subset of the company's products (422). Leave the support contact fields out: an email there invites that person as an admin. Not idempotent: on a lost response, list by search before retrying.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
Request body
| Field | Type | Description |
|---|
location_name required | string | Unique within the company. min length 2, max length 200 |
street required | string | min length 1, max length 200 |
city required | string | min length 1, max length 100 |
state required | string | min length 1, max length 100 |
country required | string | min length 1, max length 100 |
zipcode required | string | min length 1, max length 20 |
vertical_id required | string (uuid) | From GET /verticals. |
enabled_products | "after-call-copilot" | "first-alert-copilot" | "insights-hub"[] | Must be a subset of the company's products. |
Example
{
"location_name": "Riverbend - Service",
"street": "100 River Rd",
"city": "Springfield",
"state": "IL",
"country": "United States",
"zipcode": "62701",
"vertical_id": "0193b6c2-0001-7000-8000-00000000c5b5",
"enabled_products": [
"after-call-copilot",
"first-alert-copilot",
"insights-hub"
]
}
Responses
| Status | Meaning |
| 201 | Created. Name fields (company_name, reseller_name, vertical_name) are empty here; GET fills them. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Unknown vertical_id, or company not found. |
| 409 | Conflict (duplicate name or email, already active or inactive). Read the message. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
201 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "location" | |
data.attributes | object | |
data.attributes.id | string (uuid) | |
data.attributes.company_id | string (uuid) | |
data.attributes.company_name | string | |
data.attributes.reseller_name | string | |
data.attributes.location_name | string | |
data.attributes.street | string | |
data.attributes.city | string | |
data.attributes.state | string | |
data.attributes.country | string | |
data.attributes.zipcode | string | |
data.attributes.support_contact_name | string | |
data.attributes.support_contact_email | string | |
data.attributes.support_contact_phone | string | |
data.attributes.vertical_id | string (uuid) | |
data.attributes.vertical_name | string | |
data.attributes.enabled_products | "after-call-copilot" | "first-alert-copilot" | "insights-hub"[] | |
data.attributes.is_active | boolean | |
data.attributes.user_count | integer | On list rows. |
data.attributes.created_at | string (date-time) | |
data.attributes.updated_at | string (date-time) | |
201 example
{
"data": {
"type": "location",
"attributes": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"company_id": "0193b6c2-0000-7000-8000-000000000000",
"company_name": "string",
"reseller_name": "string",
"location_name": "string",
"street": "string",
"city": "string",
"state": "string",
"country": "string",
"zipcode": "string",
"support_contact_name": "string",
"support_contact_email": "string",
"support_contact_phone": "string",
"vertical_id": "0193b6c2-0000-7000-8000-000000000000",
"vertical_name": "string",
"enabled_products": [
"after-call-copilot"
],
"is_active": true,
"user_count": 0,
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
}
GET
/companies/{companyId}/locations/{locationId}
Reseller admin
Read a location
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
locationId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | The location. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "location" | |
data.attributes | object | |
data.attributes.id | string (uuid) | |
data.attributes.company_id | string (uuid) | |
data.attributes.company_name | string | |
data.attributes.reseller_name | string | |
data.attributes.location_name | string | |
data.attributes.street | string | |
data.attributes.city | string | |
data.attributes.state | string | |
data.attributes.country | string | |
data.attributes.zipcode | string | |
data.attributes.support_contact_name | string | |
data.attributes.support_contact_email | string | |
data.attributes.support_contact_phone | string | |
data.attributes.vertical_id | string (uuid) | |
data.attributes.vertical_name | string | |
data.attributes.enabled_products | "after-call-copilot" | "first-alert-copilot" | "insights-hub"[] | |
data.attributes.is_active | boolean | |
data.attributes.user_count | integer | On list rows. |
data.attributes.created_at | string (date-time) | |
data.attributes.updated_at | string (date-time) | |
200 example
{
"data": {
"type": "location",
"attributes": {
"id": "0193b6c2-6b29-7a51-b0e4-1c8f3d5e7a02",
"company_id": "0193b6c2-5a11-7c3e-8f20-6d4b9e1c2a77",
"company_name": "Riverbend Auto Group",
"reseller_name": "Harborview Communications",
"location_name": "Riverbend - Service",
"street": "100 River Rd",
"city": "Springfield",
"state": "IL",
"country": "United States",
"zipcode": "62701",
"support_contact_name": "",
"support_contact_email": "",
"support_contact_phone": "",
"vertical_id": "0193b6c2-0001-7000-8000-00000000c5b5",
"vertical_name": "CSPs & MSPs (Service Providers)",
"enabled_products": [
"after-call-copilot",
"first-alert-copilot",
"insights-hub"
],
"is_active": true,
"created_at": "2026-11-02T15:12:00Z",
"updated_at": "2026-11-02T15:12:00Z"
}
}
}
PATCH
/companies/{companyId}/locations/{locationId}
Reseller admin
Update a location
Every field is optional. **enabled_products is a full replacement.** Works on an inactive location.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
locationId required | path | string (uuid) | |
Request body
| Field | Type | Description |
|---|
location_name | string | min length 2, max length 200 |
street | string | max length 200 |
city | string | max length 100 |
state | string | max length 100 |
country | string | max length 100 |
zipcode | string | max length 20 |
vertical_id | string (uuid) | |
enabled_products | "after-call-copilot" | "first-alert-copilot" | "insights-hub"[] | Full replacement. |
Example
{
"location_name": "Riverbend - Service Department"
}
Responses
| Status | Meaning |
| 200 | Updated. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 409 | Conflict (duplicate name or email, already active or inactive). Read the message. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "location" | |
data.attributes | object | |
data.attributes.id | string (uuid) | |
data.attributes.company_id | string (uuid) | |
data.attributes.company_name | string | |
data.attributes.reseller_name | string | |
data.attributes.location_name | string | |
data.attributes.street | string | |
data.attributes.city | string | |
data.attributes.state | string | |
data.attributes.country | string | |
data.attributes.zipcode | string | |
data.attributes.support_contact_name | string | |
data.attributes.support_contact_email | string | |
data.attributes.support_contact_phone | string | |
data.attributes.vertical_id | string (uuid) | |
data.attributes.vertical_name | string | |
data.attributes.enabled_products | "after-call-copilot" | "first-alert-copilot" | "insights-hub"[] | |
data.attributes.is_active | boolean | |
data.attributes.user_count | integer | On list rows. |
data.attributes.created_at | string (date-time) | |
data.attributes.updated_at | string (date-time) | |
200 example
{
"data": {
"type": "location",
"attributes": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"company_id": "0193b6c2-0000-7000-8000-000000000000",
"company_name": "string",
"reseller_name": "string",
"location_name": "string",
"street": "string",
"city": "string",
"state": "string",
"country": "string",
"zipcode": "string",
"support_contact_name": "string",
"support_contact_email": "string",
"support_contact_phone": "string",
"vertical_id": "0193b6c2-0000-7000-8000-000000000000",
"vertical_name": "string",
"enabled_products": [
"after-call-copilot"
],
"is_active": true,
"user_count": 0,
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
}
POST
/companies/{companyId}/locations/{locationId}/deactivate
Reseller admin
Deactivate a location
There is no location delete. While inactive, GET /locations/{locationId}/users returns 422; other reads and writes still work. Read is_active to tell whether a location is inactive.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
locationId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | Deactivated. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 409 | Conflict (duplicate name or email, already active or inactive). Read the message. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "location" | |
data.attributes | object | |
data.attributes.id | string (uuid) | |
data.attributes.company_id | string (uuid) | |
data.attributes.company_name | string | |
data.attributes.reseller_name | string | |
data.attributes.location_name | string | |
data.attributes.street | string | |
data.attributes.city | string | |
data.attributes.state | string | |
data.attributes.country | string | |
data.attributes.zipcode | string | |
data.attributes.support_contact_name | string | |
data.attributes.support_contact_email | string | |
data.attributes.support_contact_phone | string | |
data.attributes.vertical_id | string (uuid) | |
data.attributes.vertical_name | string | |
data.attributes.enabled_products | "after-call-copilot" | "first-alert-copilot" | "insights-hub"[] | |
data.attributes.is_active | boolean | |
data.attributes.user_count | integer | On list rows. |
data.attributes.created_at | string (date-time) | |
data.attributes.updated_at | string (date-time) | |
200 example
{
"data": {
"type": "location",
"attributes": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"company_id": "0193b6c2-0000-7000-8000-000000000000",
"company_name": "string",
"reseller_name": "string",
"location_name": "string",
"street": "string",
"city": "string",
"state": "string",
"country": "string",
"zipcode": "string",
"support_contact_name": "string",
"support_contact_email": "string",
"support_contact_phone": "string",
"vertical_id": "0193b6c2-0000-7000-8000-000000000000",
"vertical_name": "string",
"enabled_products": [
"after-call-copilot"
],
"is_active": true,
"user_count": 0,
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
}
POST
/companies/{companyId}/locations/{locationId}/reactivate
Reseller admin
Reactivate a location
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
locationId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | Reactivated. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 409 | Conflict (duplicate name or email, already active or inactive). Read the message. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "location" | |
data.attributes | object | |
data.attributes.id | string (uuid) | |
data.attributes.company_id | string (uuid) | |
data.attributes.company_name | string | |
data.attributes.reseller_name | string | |
data.attributes.location_name | string | |
data.attributes.street | string | |
data.attributes.city | string | |
data.attributes.state | string | |
data.attributes.country | string | |
data.attributes.zipcode | string | |
data.attributes.support_contact_name | string | |
data.attributes.support_contact_email | string | |
data.attributes.support_contact_phone | string | |
data.attributes.vertical_id | string (uuid) | |
data.attributes.vertical_name | string | |
data.attributes.enabled_products | "after-call-copilot" | "first-alert-copilot" | "insights-hub"[] | |
data.attributes.is_active | boolean | |
data.attributes.user_count | integer | On list rows. |
data.attributes.created_at | string (date-time) | |
data.attributes.updated_at | string (date-time) | |
200 example
{
"data": {
"type": "location",
"attributes": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"company_id": "0193b6c2-0000-7000-8000-000000000000",
"company_name": "string",
"reseller_name": "string",
"location_name": "string",
"street": "string",
"city": "string",
"state": "string",
"country": "string",
"zipcode": "string",
"support_contact_name": "string",
"support_contact_email": "string",
"support_contact_phone": "string",
"vertical_id": "0193b6c2-0000-7000-8000-000000000000",
"vertical_name": "string",
"enabled_products": [
"after-call-copilot"
],
"is_active": true,
"user_count": 0,
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
}
Customer lifecycle (admin credentials)
User groups
Groups route alerts (for example "Upset Customers") and grant Insights Hub access ("Insights Hub Access").
GET
/locations/{locationId}/user-groups
Reseller admin
List a location's groups
Rows don't include members; read a single group for those.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
search | query | string | Case-insensitive substring match on group_name. |
limit | query | integer | Page size. Send 100 and follow next_cursor. min 1, max 100, default 20 |
cursor | query | string | Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400. |
Responses
| Status | Meaning |
| 200 | One page of groups. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object[] | |
data[].type | "user_group" | |
data[].attributes | object | |
data[].attributes.id | string (uuid) | |
data[].attributes.location_id | string (uuid) | |
data[].attributes.group_name | string | |
data[].attributes.user_count | integer | |
data[].attributes.members | object[] | On single reads. |
data[].attributes.members[].id | string (uuid) | |
data[].attributes.members[].email | string (email) | |
data[].attributes.members[].first_name | string | |
data[].attributes.members[].last_name | string | |
data[].attributes.members[].display_name | string | |
data[].attributes.created_at | string (date-time) | |
data[].attributes.updated_at | string (date-time) | |
pagination | object | |
pagination.has_more | boolean | |
pagination.next_cursor | string | null | |
pagination.total_count | integer | |
200 example
{
"data": [
{
"type": "user_group",
"attributes": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"location_id": "0193b6c2-0000-7000-8000-000000000000",
"group_name": "string",
"user_count": 0,
"members": [
{
"id": "0193b6c2-0000-7000-8000-000000000000",
"email": "user@example.com",
"first_name": "string",
"last_name": "string",
"display_name": "string"
}
],
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
],
"pagination": {
"has_more": true,
"next_cursor": "string",
"total_count": 0
}
}
POST
/locations/{locationId}/user-groups
Reseller admin
Create a group
group_name is unique within the location (409). Not idempotent.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
Request body
| Field | Type | Description |
|---|
group_name required | string | min length 2, max length 200 |
member_ids | string (uuid)[] | Users assigned to this location. |
Example
{
"group_name": "Upset Customers"
}
Responses
| Status | Meaning |
| 201 | Created. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 409 | Conflict (duplicate name or email, already active or inactive). Read the message. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
201 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "user_group" | |
data.attributes | object | |
data.attributes.id | string (uuid) | |
data.attributes.location_id | string (uuid) | |
data.attributes.group_name | string | |
data.attributes.user_count | integer | |
data.attributes.members | object[] | On single reads. |
data.attributes.members[].id | string (uuid) | |
data.attributes.members[].email | string (email) | |
data.attributes.members[].first_name | string | |
data.attributes.members[].last_name | string | |
data.attributes.members[].display_name | string | |
data.attributes.created_at | string (date-time) | |
data.attributes.updated_at | string (date-time) | |
201 example
{
"data": {
"type": "user_group",
"attributes": {
"id": "0193b6c2-8d51-74e0-9b6a-2c7e1f3d5a10",
"location_id": "0193b6c2-6b29-7a51-b0e4-1c8f3d5e7a02",
"group_name": "Upset Customers",
"user_count": 0,
"created_at": "2026-11-02T15:14:00Z",
"updated_at": "2026-11-02T15:14:00Z"
}
}
}
GET
/locations/{locationId}/user-groups/{groupId}
Reseller admin
Read a group with its members
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
groupId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | The group and members[]. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "user_group" | |
data.attributes | object | |
data.attributes.id | string (uuid) | |
data.attributes.location_id | string (uuid) | |
data.attributes.group_name | string | |
data.attributes.user_count | integer | |
data.attributes.members | object[] | On single reads. |
data.attributes.members[].id | string (uuid) | |
data.attributes.members[].email | string (email) | |
data.attributes.members[].first_name | string | |
data.attributes.members[].last_name | string | |
data.attributes.members[].display_name | string | |
data.attributes.created_at | string (date-time) | |
data.attributes.updated_at | string (date-time) | |
200 example
{
"data": {
"type": "user_group",
"attributes": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"location_id": "0193b6c2-0000-7000-8000-000000000000",
"group_name": "string",
"user_count": 0,
"members": [
{
"id": "0193b6c2-0000-7000-8000-000000000000",
"email": "user@example.com",
"first_name": "string",
"last_name": "string",
"display_name": "string"
}
],
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
}
PATCH
/locations/{locationId}/user-groups/{groupId}
Reseller admin
Rename a group or set its members
**member_ids replaces the whole membership.** Read the group, merge, then write. Every id must be a user at this location (422).
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
groupId required | path | string (uuid) | |
Request body
| Field | Type | Description |
|---|
group_name | string | min length 2, max length 200 |
member_ids | string (uuid)[] | |
Example
{
"member_ids": [
"0193b6c2-7c45-7d12-a3f9-8e2b6c1d4f56"
]
}
Responses
| Status | Meaning |
| 200 | Updated. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 409 | Conflict (duplicate name or email, already active or inactive). Read the message. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "user_group" | |
data.attributes | object | |
data.attributes.id | string (uuid) | |
data.attributes.location_id | string (uuid) | |
data.attributes.group_name | string | |
data.attributes.user_count | integer | |
data.attributes.members | object[] | On single reads. |
data.attributes.members[].id | string (uuid) | |
data.attributes.members[].email | string (email) | |
data.attributes.members[].first_name | string | |
data.attributes.members[].last_name | string | |
data.attributes.members[].display_name | string | |
data.attributes.created_at | string (date-time) | |
data.attributes.updated_at | string (date-time) | |
200 example
{
"data": {
"type": "user_group",
"attributes": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"location_id": "0193b6c2-0000-7000-8000-000000000000",
"group_name": "string",
"user_count": 0,
"members": [
{
"id": "0193b6c2-0000-7000-8000-000000000000",
"email": "user@example.com",
"first_name": "string",
"last_name": "string",
"display_name": "string"
}
],
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
}
DELETE
/locations/{locationId}/user-groups/{groupId}
Reseller admin
Delete a group
Remove the group from alert rules first, or pass force=true.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
groupId required | path | string (uuid) | |
force | query | boolean | Delete even when alert rules still route to the group. default false |
Responses
| Status | Meaning |
| 204 | Deleted. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 409 | Conflict (duplicate name or email, already active or inactive). Read the message. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
GET
/locations/{locationId}/users/{userId}/group-membership
Reseller admin
A user's groups at a location
Lists every group at the location with is_member. The Insights Hub access group shows product_keys: ["insights-hub"].
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
userId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | Groups. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object[] | |
data[].id | string (uuid) | |
data[].name | string | |
data[].is_member | boolean | |
data[].product_keys | "after-call-copilot" | "first-alert-copilot" | "insights-hub"[] | |
200 example
{
"data": [
{
"id": "0193b6c2-8d52-74e0-9b6a-2c7e1f3d5a11",
"name": "Insights Hub Access",
"is_member": true,
"product_keys": [
"insights-hub"
]
},
{
"id": "0193b6c2-8d51-74e0-9b6a-2c7e1f3d5a10",
"name": "Upset Customers",
"is_member": true,
"product_keys": []
}
]
}
PUT
/locations/{locationId}/users/{userId}/group-membership
Reseller admin
Set a user's groups at a location
Full replacement for this user at this location. group_ids is required; [] removes the user from every group. Set membership before per-alert email preferences.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
userId required | path | string (uuid) | |
Request body
| Field | Type | Description |
|---|
group_ids required | string (uuid)[] | |
Example
{
"group_ids": [
"0193b6c2-8d51-74e0-9b6a-2c7e1f3d5a10",
"0193b6c2-8d52-74e0-9b6a-2c7e1f3d5a11"
]
}
Responses
| Status | Meaning |
| 200 | The user's groups after the change. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object[] | |
data[].id | string (uuid) | |
data[].name | string | |
data[].is_member | boolean | |
data[].product_keys | "after-call-copilot" | "first-alert-copilot" | "insights-hub"[] | |
200 example
{
"data": [
{
"id": "0193b6c2-0000-7000-8000-000000000000",
"name": "string",
"is_member": true,
"product_keys": [
"after-call-copilot"
]
}
]
}
Customer lifecycle (admin credentials)
Connectors
A connector links a location to the customer's phone system. Create returns 202 and the connector connects in the background: check GET every 10 seconds, for up to 10 minutes, until status is active.
GET
/connector-types
Reseller admin
List connector types
Use netsapiens for the phone system connector.
Responses
| Status | Meaning |
| 200 | Connector types. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object[] | |
data[].key | string | |
data[].name | string | |
200 example
{
"data": [
{
"key": "netsapiens",
"name": "NetSapiens"
}
]
}
POST
/locations/{locationId}/connectors/test
Reseller admin
Dry-run a connector
Checks that the phone system is reachable and the key authenticates. Saves nothing. It does not check the key's write permissions; create reports those (state_reason: invalid_permissions). The key must be read/write. A failed test is a 200 with success: false. Show your own message rather than the error text.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
Request body
| Field | Type | Description |
|---|
type required | "netsapiens" | |
config required | object | |
config.api_url required | string (uri) | Full API root ending in /ns-api/v2. |
config.domain required | string | The customer's phone-system domain. |
config.api_key required | string (password) | Read/write key. Write-only; never returned. |
connector_id | string (uuid) | Test new settings for an existing connector. |
Example
{
"type": "netsapiens",
"config": {
"api_url": "https://pbx.example.com/ns-api/v2",
"domain": "riverbend.example",
"api_key": "<api key>"
}
}
Responses
| Status | Meaning |
| 200 | Test result. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.success | boolean | |
200 example
{
"data": {
"success": true
}
}
GET
/locations/{locationId}/connectors
Reseller admin
List a location's connectors
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
search | query | string | Substring match on the connector name. |
status | query | "connecting" | "active" | "error" | "deactivating" | "inactive" | One status. Invalid values return 400. |
limit | query | integer | Page size. Send 100 and follow next_cursor. min 1, max 100, default 20 |
cursor | query | string | Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400. |
Responses
| Status | Meaning |
| 200 | One page of connectors. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object[] | |
data[].id | string (uuid) | |
data[].location_id | string (uuid) | Company list only. |
data[].location_name | string | Company list only. |
data[].name | string | |
data[].type | string | |
data[].type_display_name | string | |
data[].status | "connecting" | "active" | "error" | "deactivating" | "inactive" | connecting → active (calls flow) or error. Deactivate: deactivating → inactive. Reactivate: back to connecting. |
data[].status_display | string | |
data[].status_message | string | null | |
data[].state_reason | string | |
data[].last_synced_at | string (date-time) | null | |
data[].created_at | string (date-time) | |
data[].updated_at | string (date-time) | |
pagination | object | |
pagination.has_more | boolean | |
pagination.next_cursor | string | null | |
pagination.total_count | integer | |
200 example
{
"data": [
{
"id": "0193b6c2-0000-7000-8000-000000000000",
"location_id": "0193b6c2-0000-7000-8000-000000000000",
"location_name": "string",
"name": "string",
"type": "string",
"type_display_name": "string",
"status": "connecting",
"status_display": "string",
"status_message": "string",
"state_reason": "string",
"last_synced_at": "2026-11-02T15:04:05Z",
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
],
"pagination": {
"has_more": true,
"next_cursor": "string",
"total_count": 0
}
}
POST
/locations/{locationId}/connectors
Reseller admin
Create a connector
Returns 202 with status: connecting. The platform then checks the key and subscribes to call records in the background. Check GET /locations/{locationId}/connectors/{connectorId} every 10 seconds, for up to 10 minutes, until status is active (calls flow) or error (read state_reason and status_message).
-
api_url is the full API root ending in /ns-api/v2.
-
The key must be read/write; a read-only key ends in
error / invalid_permissions.
-
A domain-level key, or a reseller-level key with the domain set, both work.
-
Run the dry run first. Not idempotent: on a lost response, list connectors before retrying.
-
Connectors are never deleted; deactivate instead.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
Request body
| Field | Type | Description |
|---|
name required | string | |
type required | "netsapiens" | |
config required | object | |
config.api_url required | string (uri) | Full API root ending in /ns-api/v2. |
config.domain required | string | The customer's phone-system domain. |
config.api_key required | string (password) | Read/write key. Write-only; never returned. |
Example
{
"name": "Riverbend phone system",
"type": "netsapiens",
"config": {
"api_url": "https://pbx.example.com/ns-api/v2",
"domain": "riverbend.example",
"api_key": "<api key>"
}
}
Responses
| Status | Meaning |
| 202 | Accepted. Connecting in the background. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 409 | Conflict (duplicate name or email, already active or inactive). Read the message. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
202 response fields
| Field | Type | Description |
|---|
data | object | |
data.id | string (uuid) | |
data.location_id | string (uuid) | |
data.name | string | |
data.type | string | |
data.type_display_name | string | |
data.config | object | Settings without the key. |
data.config.api_url | string | |
data.config.domain | string | |
data.status | "connecting" | "active" | "error" | "deactivating" | "inactive" | connecting → active (calls flow) or error. Deactivate: deactivating → inactive. Reactivate: back to connecting. |
data.status_display | string | |
data.status_message | string | null | What went wrong, when status is error. |
data.state_reason | string | Why the connector is in this status, e.g. invalid_permissions. Omitted when there is none. |
data.last_synced_at | string (date-time) | null | |
data.created_at | string (date-time) | |
data.updated_at | string (date-time) | |
202 example
{
"data": {
"id": "4b7e9d2c-1a3f-4e8b-9c6d-2f5a8e1b3c70",
"location_id": "0193b6c2-6b29-7a51-b0e4-1c8f3d5e7a02",
"name": "Riverbend phone system",
"type": "netsapiens",
"type_display_name": "NetSapiens",
"config": {
"api_url": "https://pbx.example.com/ns-api/v2",
"domain": "riverbend.example"
},
"status": "connecting",
"status_display": "connecting",
"status_message": null,
"last_synced_at": null,
"created_at": "2026-11-02T15:16:00Z",
"updated_at": "2026-11-02T15:16:00Z"
}
}
GET
/locations/{locationId}/connectors/{connectorId}
Reseller admin
Read a connector
Check this every 10 seconds, for up to 10 minutes, after create, update, deactivate or reactivate. The API key is never returned.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
connectorId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | The connector. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.id | string (uuid) | |
data.location_id | string (uuid) | |
data.name | string | |
data.type | string | |
data.type_display_name | string | |
data.config | object | Settings without the key. |
data.config.api_url | string | |
data.config.domain | string | |
data.status | "connecting" | "active" | "error" | "deactivating" | "inactive" | connecting → active (calls flow) or error. Deactivate: deactivating → inactive. Reactivate: back to connecting. |
data.status_display | string | |
data.status_message | string | null | What went wrong, when status is error. |
data.state_reason | string | Why the connector is in this status, e.g. invalid_permissions. Omitted when there is none. |
data.last_synced_at | string (date-time) | null | |
data.created_at | string (date-time) | |
data.updated_at | string (date-time) | |
200 example
{
"data": {
"id": "4b7e9d2c-1a3f-4e8b-9c6d-2f5a8e1b3c70",
"location_id": "0193b6c2-6b29-7a51-b0e4-1c8f3d5e7a02",
"name": "Riverbend phone system",
"type": "netsapiens",
"type_display_name": "NetSapiens",
"config": {
"api_url": "https://pbx.example.com/ns-api/v2",
"domain": "riverbend.example"
},
"status": "active",
"status_display": "active",
"status_message": null,
"last_synced_at": "2026-11-02T15:16:20Z",
"created_at": "2026-11-02T15:16:00Z",
"updated_at": "2026-11-02T15:16:20Z"
}
}
PATCH
/locations/{locationId}/connectors/{connectorId}
Reseller admin
Update a connector
Rename it or change its settings. type cannot change. When moving to another server or domain, change api_url and domain first, then the key. Check GET afterwards until it settles.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
connectorId required | path | string (uuid) | |
Request body
| Field | Type | Description |
|---|
name | string | |
config | object | |
config.api_url required | string (uri) | Full API root ending in /ns-api/v2. |
config.domain required | string | The customer's phone-system domain. |
config.api_key required | string (password) | Read/write key. Write-only; never returned. |
Example
{
"name": "Riverbend phone system (main)"
}
Responses
| Status | Meaning |
| 200 | Updated. |
| 202 | Accepted. Reconnecting in the background. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.id | string (uuid) | |
data.location_id | string (uuid) | |
data.name | string | |
data.type | string | |
data.type_display_name | string | |
data.config | object | Settings without the key. |
data.config.api_url | string | |
data.config.domain | string | |
data.status | "connecting" | "active" | "error" | "deactivating" | "inactive" | connecting → active (calls flow) or error. Deactivate: deactivating → inactive. Reactivate: back to connecting. |
data.status_display | string | |
data.status_message | string | null | What went wrong, when status is error. |
data.state_reason | string | Why the connector is in this status, e.g. invalid_permissions. Omitted when there is none. |
data.last_synced_at | string (date-time) | null | |
data.created_at | string (date-time) | |
data.updated_at | string (date-time) | |
200 example
{
"data": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"location_id": "0193b6c2-0000-7000-8000-000000000000",
"name": "string",
"type": "string",
"type_display_name": "string",
"config": {
"api_url": "string",
"domain": "string"
},
"status": "connecting",
"status_display": "string",
"status_message": "string",
"state_reason": "string",
"last_synced_at": "2026-11-02T15:04:05Z",
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
POST
/locations/{locationId}/connectors/{connectorId}/deactivate
Reseller admin
Stop a connector
Returns 202 deactivating, then inactive within seconds. Calls stop flowing. Monitored-number settings are kept. Repeating returns 409.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
connectorId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 202 | Stopping. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 409 | Conflict (duplicate name or email, already active or inactive). Read the message. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
202 response fields
| Field | Type | Description |
|---|
data | object | |
data.id | string (uuid) | |
data.location_id | string (uuid) | |
data.name | string | |
data.type | string | |
data.type_display_name | string | |
data.config | object | Settings without the key. |
data.config.api_url | string | |
data.config.domain | string | |
data.status | "connecting" | "active" | "error" | "deactivating" | "inactive" | connecting → active (calls flow) or error. Deactivate: deactivating → inactive. Reactivate: back to connecting. |
data.status_display | string | |
data.status_message | string | null | What went wrong, when status is error. |
data.state_reason | string | Why the connector is in this status, e.g. invalid_permissions. Omitted when there is none. |
data.last_synced_at | string (date-time) | null | |
data.created_at | string (date-time) | |
data.updated_at | string (date-time) | |
202 example
{
"data": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"location_id": "0193b6c2-0000-7000-8000-000000000000",
"name": "string",
"type": "string",
"type_display_name": "string",
"config": {
"api_url": "string",
"domain": "string"
},
"status": "connecting",
"status_display": "string",
"status_message": "string",
"state_reason": "string",
"last_synced_at": "2026-11-02T15:04:05Z",
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
POST
/locations/{locationId}/connectors/{connectorId}/reactivate
Reseller admin
Restart a connector
Returns 202 connecting. Check its status every 10 seconds, for up to 10 minutes, until active or error.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
connectorId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 202 | Restarting. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 409 | Conflict (duplicate name or email, already active or inactive). Read the message. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
202 response fields
| Field | Type | Description |
|---|
data | object | |
data.id | string (uuid) | |
data.location_id | string (uuid) | |
data.name | string | |
data.type | string | |
data.type_display_name | string | |
data.config | object | Settings without the key. |
data.config.api_url | string | |
data.config.domain | string | |
data.status | "connecting" | "active" | "error" | "deactivating" | "inactive" | connecting → active (calls flow) or error. Deactivate: deactivating → inactive. Reactivate: back to connecting. |
data.status_display | string | |
data.status_message | string | null | What went wrong, when status is error. |
data.state_reason | string | Why the connector is in this status, e.g. invalid_permissions. Omitted when there is none. |
data.last_synced_at | string (date-time) | null | |
data.created_at | string (date-time) | |
data.updated_at | string (date-time) | |
202 example
{
"data": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"location_id": "0193b6c2-0000-7000-8000-000000000000",
"name": "string",
"type": "string",
"type_display_name": "string",
"config": {
"api_url": "string",
"domain": "string"
},
"status": "connecting",
"status_display": "string",
"status_message": "string",
"state_reason": "string",
"last_synced_at": "2026-11-02T15:04:05Z",
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
GET
/companies/{companyId}/connectors
Reseller admin
List a company's connectors
errors[] lists connectors in error with their message, for a health check.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
search | query | string | Substring match on the connector name. |
status | query | "connecting" | "active" | "error" | "deactivating" | "inactive" | connecting → active (calls flow) or error. Deactivate: deactivating → inactive. Reactivate: back to connecting.
|
type | query | "netsapiens" | Connector type key. Invalid values return 400. |
limit | query | integer | Page size. Send 100 and follow next_cursor. min 1, max 100, default 20 |
cursor | query | string | Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400. |
Responses
| Status | Meaning |
| 200 | One page of connectors. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object[] | |
data[].id | string (uuid) | |
data[].location_id | string (uuid) | Company list only. |
data[].location_name | string | Company list only. |
data[].name | string | |
data[].type | string | |
data[].type_display_name | string | |
data[].status | "connecting" | "active" | "error" | "deactivating" | "inactive" | connecting → active (calls flow) or error. Deactivate: deactivating → inactive. Reactivate: back to connecting. |
data[].status_display | string | |
data[].status_message | string | null | |
data[].state_reason | string | |
data[].last_synced_at | string (date-time) | null | |
data[].created_at | string (date-time) | |
data[].updated_at | string (date-time) | |
pagination | object | |
pagination.has_more | boolean | |
pagination.next_cursor | string | null | |
pagination.total_count | integer | |
errors | object[] | Connectors in error. |
errors[].id | string (uuid) | |
errors[].name | string | |
errors[].type | string | |
errors[].location_name | string | |
errors[].status_message | string | null | |
200 example
{
"data": [
{
"id": "0193b6c2-0000-7000-8000-000000000000",
"location_id": "0193b6c2-0000-7000-8000-000000000000",
"location_name": "string",
"name": "string",
"type": "string",
"type_display_name": "string",
"status": "connecting",
"status_display": "string",
"status_message": "string",
"state_reason": "string",
"last_synced_at": "2026-11-02T15:04:05Z",
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
],
"pagination": {
"has_more": true,
"next_cursor": "string",
"total_count": 0
},
"errors": [
{
"id": "0193b6c2-0000-7000-8000-000000000000",
"name": "string",
"type": "string",
"location_name": "string",
"status_message": "string"
}
]
}
Customer lifecycle (admin credentials)
First Alert
Alert rules, monitored numbers, the location alert webhook, and each user's alert email.
GET
/locations/{locationId}/first-alert/rules
Reseller admin
List a location's alert rules
Rows carry trigger_types[] only. Read a single rule for its triggers.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
limit | query | integer | min 1, max 100, default 25 |
cursor | query | string | Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400. |
Responses
| Status | Meaning |
| 200 | One page of rules. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object[] | |
data[].type | "first_alert_rule" | |
data[].attributes | object | |
data[].attributes.id | string (uuid) | |
data[].attributes.location_id | string (uuid) | |
data[].attributes.name | string | |
data[].attributes.priority | "critical" | "high" | "medium" | "low" | |
data[].attributes.match_logic | string | |
data[].attributes.enabled | boolean | |
data[].attributes.is_default | boolean | A platform default rule (can't be deleted). |
data[].attributes.triggers | object[] | Single reads. |
data[].attributes.triggers[].id | string (uuid) | In responses. |
data[].attributes.triggers[].trigger_type required | "sentiment" | "keyword_match" | "conversation_topic" | |
data[].attributes.triggers[].config required | object | object | object | |
data[].attributes.trigger_types | string[] | List rows. |
data[].attributes.groups | object[] | |
data[].attributes.groups[].id | string (uuid) | |
data[].attributes.groups[].group_name | string | |
data[].attributes.created_at | string (date-time) | |
data[].attributes.updated_at | string (date-time) | |
pagination | object | |
pagination.has_more | boolean | |
pagination.next_cursor | string | null | |
pagination.total_count | integer | |
200 example
{
"data": [
{
"type": "first_alert_rule",
"attributes": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"location_id": "0193b6c2-0000-7000-8000-000000000000",
"name": "string",
"priority": "critical",
"match_logic": "string",
"enabled": true,
"is_default": true,
"triggers": [
{
"id": "0193b6c2-0000-7000-8000-000000000000",
"trigger_type": "sentiment",
"config": null
}
],
"trigger_types": [
"string"
],
"groups": [
{
"id": "0193b6c2-0000-7000-8000-000000000000",
"group_name": "string"
}
],
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
],
"pagination": {
"has_more": true,
"next_cursor": "string",
"total_count": 0
}
}
POST
/locations/{locationId}/first-alert/rules
Reseller admin
Create an alert rule
Create rules with enabled: false and enable them once numbers and recipients are set. name is unique within the location (409). Not idempotent.
The Base Intelligence Seat uses two rules routed to the managers' group:
-
Upset Customer:
sentiment lt −40, priority high.
-
Customer Threat:
sentiment lt −20 AND keyword_match on the customer-threat phrases, match_logic: all, priority critical.
The phrases are provided and maintained by Tresic; ask your Tresic contact for the current list.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
Request body
| Field | Type | Description |
|---|
name required | string | min length 1, max length 200 |
priority required | "critical" | "high" | "medium" | "low" | |
match_logic | "any" | "all" | How the rule's triggers combine. default "any" |
enabled | boolean | |
triggers required | object[] | min items 1 |
triggers[].id | string (uuid) | In responses. |
triggers[].trigger_type required | "sentiment" | "keyword_match" | "conversation_topic" | |
triggers[].config required | object | object | object | |
group_ids | string (uuid)[] | Groups at this location that receive the alert. |
Example: Upset Customer
{
"name": "Upset Customer",
"priority": "high",
"match_logic": "any",
"enabled": false,
"triggers": [
{
"trigger_type": "sentiment",
"config": {
"operator": "lt",
"threshold": -40
}
}
],
"group_ids": [
"0193b6c2-8d51-74e0-9b6a-2c7e1f3d5a10"
]
}
Example: Customer Threat
{
"name": "Customer Threat",
"priority": "critical",
"match_logic": "all",
"enabled": false,
"triggers": [
{
"trigger_type": "sentiment",
"config": {
"operator": "lt",
"threshold": -20
}
},
{
"trigger_type": "keyword_match",
"config": {
"match_logic": "any",
"keywords": [
"<phrase supplied by your Tresic contact>",
"<phrase supplied by your Tresic contact>"
]
}
}
],
"group_ids": [
"0193b6c2-8d51-74e0-9b6a-2c7e1f3d5a10"
]
}
Responses
| Status | Meaning |
| 201 | Created. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 409 | Conflict (duplicate name or email, already active or inactive). Read the message. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
201 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "first_alert_rule" | |
data.attributes | object | |
data.attributes.id | string (uuid) | |
data.attributes.location_id | string (uuid) | |
data.attributes.name | string | |
data.attributes.priority | "critical" | "high" | "medium" | "low" | |
data.attributes.match_logic | string | |
data.attributes.enabled | boolean | |
data.attributes.is_default | boolean | A platform default rule (can't be deleted). |
data.attributes.triggers | object[] | Single reads. |
data.attributes.triggers[].id | string (uuid) | In responses. |
data.attributes.triggers[].trigger_type required | "sentiment" | "keyword_match" | "conversation_topic" | |
data.attributes.triggers[].config required | object | object | object | |
data.attributes.trigger_types | string[] | List rows. |
data.attributes.groups | object[] | |
data.attributes.groups[].id | string (uuid) | |
data.attributes.groups[].group_name | string | |
data.attributes.created_at | string (date-time) | |
data.attributes.updated_at | string (date-time) | |
201 example
{
"data": {
"type": "first_alert_rule",
"attributes": {
"id": "6f1c2e8a-3b4d-4c9e-a7f2-1d5e8b9c0a31",
"location_id": "0193b6c2-6b29-7a51-b0e4-1c8f3d5e7a02",
"name": "Upset Customer",
"priority": "high",
"match_logic": "any",
"enabled": false,
"is_default": false,
"triggers": [
{
"id": "9a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"trigger_type": "sentiment",
"config": {
"operator": "lt",
"threshold": -40
}
}
],
"groups": [
{
"id": "0193b6c2-8d51-74e0-9b6a-2c7e1f3d5a10",
"group_name": "Upset Customers"
}
],
"created_at": "2026-11-02T15:18:00Z",
"updated_at": "2026-11-02T15:18:00Z"
}
}
}
GET
/locations/{locationId}/first-alert/rules/{ruleId}
Reseller admin
Read an alert rule
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
ruleId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | The full rule. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "first_alert_rule" | |
data.attributes | object | |
data.attributes.id | string (uuid) | |
data.attributes.location_id | string (uuid) | |
data.attributes.name | string | |
data.attributes.priority | "critical" | "high" | "medium" | "low" | |
data.attributes.match_logic | string | |
data.attributes.enabled | boolean | |
data.attributes.is_default | boolean | A platform default rule (can't be deleted). |
data.attributes.triggers | object[] | Single reads. |
data.attributes.triggers[].id | string (uuid) | In responses. |
data.attributes.triggers[].trigger_type required | "sentiment" | "keyword_match" | "conversation_topic" | |
data.attributes.triggers[].config required | object | object | object | |
data.attributes.trigger_types | string[] | List rows. |
data.attributes.groups | object[] | |
data.attributes.groups[].id | string (uuid) | |
data.attributes.groups[].group_name | string | |
data.attributes.created_at | string (date-time) | |
data.attributes.updated_at | string (date-time) | |
200 example
{
"data": {
"type": "first_alert_rule",
"attributes": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"location_id": "0193b6c2-0000-7000-8000-000000000000",
"name": "string",
"priority": "critical",
"match_logic": "string",
"enabled": true,
"is_default": true,
"triggers": [
{
"id": "0193b6c2-0000-7000-8000-000000000000",
"trigger_type": "sentiment",
"config": {
"operator": null,
"threshold": null
}
}
],
"trigger_types": [
"string"
],
"groups": [
{
"id": "0193b6c2-0000-7000-8000-000000000000",
"group_name": "string"
}
],
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
}
PATCH
/locations/{locationId}/first-alert/rules/{ruleId}
Reseller admin
Update an alert rule
Every field is optional; omitted fields keep their value. **triggers replaces the whole trigger set. group_ids replaces the groups; [] clears them.** Send {"enabled": true} to switch a rule on.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
ruleId required | path | string (uuid) | |
Request body
| Field | Type | Description |
|---|
name | string | min length 1, max length 200 |
priority | "critical" | "high" | "medium" | "low" | |
match_logic | "any" | "all" | |
enabled | boolean | |
triggers | object[] | Replaces every trigger. min items 1 |
triggers[].id | string (uuid) | In responses. |
triggers[].trigger_type required | "sentiment" | "keyword_match" | "conversation_topic" | |
triggers[].config required | object | object | object | |
group_ids | string (uuid)[] | Replaces the groups. [] clears. |
Example
{
"enabled": true
}
Responses
| Status | Meaning |
| 200 | Updated. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 409 | Conflict (duplicate name or email, already active or inactive). Read the message. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "first_alert_rule" | |
data.attributes | object | |
data.attributes.id | string (uuid) | |
data.attributes.location_id | string (uuid) | |
data.attributes.name | string | |
data.attributes.priority | "critical" | "high" | "medium" | "low" | |
data.attributes.match_logic | string | |
data.attributes.enabled | boolean | |
data.attributes.is_default | boolean | A platform default rule (can't be deleted). |
data.attributes.triggers | object[] | Single reads. |
data.attributes.triggers[].id | string (uuid) | In responses. |
data.attributes.triggers[].trigger_type required | "sentiment" | "keyword_match" | "conversation_topic" | |
data.attributes.triggers[].config required | object | object | object | |
data.attributes.trigger_types | string[] | List rows. |
data.attributes.groups | object[] | |
data.attributes.groups[].id | string (uuid) | |
data.attributes.groups[].group_name | string | |
data.attributes.created_at | string (date-time) | |
data.attributes.updated_at | string (date-time) | |
200 example
{
"data": {
"type": "first_alert_rule",
"attributes": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"location_id": "0193b6c2-0000-7000-8000-000000000000",
"name": "string",
"priority": "critical",
"match_logic": "string",
"enabled": true,
"is_default": true,
"triggers": [
{
"id": "0193b6c2-0000-7000-8000-000000000000",
"trigger_type": "sentiment",
"config": {
"operator": null,
"threshold": null
}
}
],
"trigger_types": [
"string"
],
"groups": [
{
"id": "0193b6c2-0000-7000-8000-000000000000",
"group_name": "string"
}
],
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
}
DELETE
/locations/{locationId}/first-alert/rules/{ruleId}
Reseller admin
Delete an alert rule
Platform default rules can't be deleted (409); disable them instead.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
ruleId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 204 | Deleted. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 409 | Conflict (duplicate name or email, already active or inactive). Read the message. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
POST
/locations/{locationId}/first-alert/rules/{ruleId}/duplicate
Reseller admin
Copy an alert rule
Creates "<name> (Copy)", disabled, with the same triggers and groups.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
ruleId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 201 | The copy. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 409 | Conflict (duplicate name or email, already active or inactive). Read the message. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
201 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "first_alert_rule" | |
data.attributes | object | |
data.attributes.id | string (uuid) | |
data.attributes.location_id | string (uuid) | |
data.attributes.name | string | |
data.attributes.priority | "critical" | "high" | "medium" | "low" | |
data.attributes.match_logic | string | |
data.attributes.enabled | boolean | |
data.attributes.is_default | boolean | A platform default rule (can't be deleted). |
data.attributes.triggers | object[] | Single reads. |
data.attributes.triggers[].id | string (uuid) | In responses. |
data.attributes.triggers[].trigger_type required | "sentiment" | "keyword_match" | "conversation_topic" | |
data.attributes.triggers[].config required | object | object | object | |
data.attributes.trigger_types | string[] | List rows. |
data.attributes.groups | object[] | |
data.attributes.groups[].id | string (uuid) | |
data.attributes.groups[].group_name | string | |
data.attributes.created_at | string (date-time) | |
data.attributes.updated_at | string (date-time) | |
201 example
{
"data": {
"type": "first_alert_rule",
"attributes": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"location_id": "0193b6c2-0000-7000-8000-000000000000",
"name": "string",
"priority": "critical",
"match_logic": "string",
"enabled": true,
"is_default": true,
"triggers": [
{
"id": "0193b6c2-0000-7000-8000-000000000000",
"trigger_type": "sentiment",
"config": {
"operator": null,
"threshold": null
}
}
],
"trigger_types": [
"string"
],
"groups": [
{
"id": "0193b6c2-0000-7000-8000-000000000000",
"group_name": "string"
}
],
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
}
GET
/locations/{locationId}/first-alert/config
Reseller admin
Read monitored numbers and the alert webhook
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | Location First Alert configuration. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.webhook_url | string | null | |
data.connector_mappings | object[] | |
data.connector_mappings[].connector_id | string (uuid) | |
data.connector_mappings[].connector_name | string | |
data.connector_mappings[].connector_type | string | |
data.connector_mappings[].monitored_numbers | string[] | |
data.connector_mappings[].id | string (uuid) | |
200 example
{
"data": {
"webhook_url": "string",
"connector_mappings": [
{
"connector_id": "0193b6c2-0000-7000-8000-000000000000",
"connector_name": "string",
"connector_type": "string",
"monitored_numbers": [
"string"
],
"id": "0193b6c2-0000-7000-8000-000000000000"
}
]
}
}
PUT
/locations/{locationId}/first-alert/config
Reseller admin
Set monitored numbers and the alert webhook
Full replacement. Send every monitored number and send webhook_url every time (omit it and it is cleared). webhook_url must be HTTPS; it receives each alert at this location (see the First Alert webhook). Numbers are the extensions and DIDs at this location, read from the phone system with your own key; this API cannot list them. This call does not check whether another location also monitors a number: keep each extension at exactly one location.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
Request body
| Field | Type | Description |
|---|
webhook_url | string (uri) | null | HTTPS only. Send it on every PUT or it is cleared. |
connector_mappings required | object[] | |
connector_mappings[].connector_id required | string (uuid) | |
connector_mappings[].monitored_numbers required | string[] | Extensions or DIDs, as the phone system shows them. |
Example
{
"webhook_url": "https://hooks.example.com/riverbend/alerts",
"connector_mappings": [
{
"connector_id": "4b7e9d2c-1a3f-4e8b-9c6d-2f5a8e1b3c70",
"monitored_numbers": [
"2101",
"2102",
"2103",
"+15555550142"
]
}
]
}
Responses
| Status | Meaning |
| 200 | Saved. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.webhook_url | string | null | |
data.connector_mappings | object[] | |
data.connector_mappings[].connector_id | string (uuid) | |
data.connector_mappings[].connector_name | string | |
data.connector_mappings[].connector_type | string | |
data.connector_mappings[].monitored_numbers | string[] | |
data.connector_mappings[].id | string (uuid) | |
200 example
{
"data": {
"webhook_url": "https://hooks.example.com/riverbend/alerts",
"connector_mappings": [
{
"id": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f60",
"connector_id": "4b7e9d2c-1a3f-4e8b-9c6d-2f5a8e1b3c70",
"connector_name": "Riverbend phone system",
"connector_type": "netsapiens",
"monitored_numbers": [
"2101",
"2102",
"2103",
"+15555550142"
]
}
]
}
}
POST
/locations/{locationId}/first-alert/config/test-webhook
Reseller admin
Test the alert webhook
Sends a test request to url and reports whether your endpoint answered with 2xx.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
Request body
| Field | Type | Description |
|---|
url required | string (uri) | |
Example
{
"url": "https://hooks.example.com/riverbend/alerts"
}
Responses
| Status | Meaning |
| 200 | Test result. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.success | boolean | |
data.status_code | integer | HTTP status your endpoint returned. |
200 example
{
"data": {
"success": true,
"status_code": 200
}
}
GET
/locations/{locationId}/users/{userId}/first-alert/notification-preferences
Reseller admin
Read a user's alert email and digest
**camelCase and not wrapped in data.** emailNotifications.alerts lists the rules the user receives through group membership.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
userId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | Preferences. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
emailNotifications | object | |
emailNotifications.masterEnabled | boolean | |
emailNotifications.alerts | object[] | |
emailNotifications.alerts[].alertId | string (uuid) | |
emailNotifications.alerts[].alertName | string | |
emailNotifications.alerts[].trigger | string | Readable summary of the rule's triggers. |
emailNotifications.alerts[].severity | string | |
emailNotifications.alerts[].description | string | |
emailNotifications.alerts[].emailEnabled | boolean | |
digest | object | |
digest.enabled | boolean | |
digest.frequency | string | |
digest.sendTime | string | |
digest.timezone | string | |
digest.timeFormat | string | |
200 example
{
"emailNotifications": {
"masterEnabled": true,
"alerts": [
{
"alertId": "0193b6c2-0000-7000-8000-000000000000",
"alertName": "string",
"trigger": "string",
"severity": "string",
"description": "string",
"emailEnabled": true
}
]
},
"digest": {
"enabled": true,
"frequency": "string",
"sendTime": "string",
"timezone": "string",
"timeFormat": "string"
}
}
PUT
/locations/{locationId}/users/{userId}/first-alert/email-preferences
Reseller admin
Set a user's alert email
masterEnabled: false turns all alert email off (frontline users). For managers, set masterEnabled: true and list each rule. Omitting alerts keeps the per-rule toggles. A rule the user doesn't receive returns 400; set group membership first.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
userId required | path | string (uuid) | |
Request body
| Field | Type | Description |
|---|
masterEnabled required | boolean | |
alerts | object[] | |
alerts[].alertId required | string (uuid) | Alert rule id. |
alerts[].emailEnabled required | boolean | |
Example
{
"masterEnabled": true,
"alerts": [
{
"alertId": "6f1c2e8a-3b4d-4c9e-a7f2-1d5e8b9c0a31",
"emailEnabled": true
},
{
"alertId": "6f1c2e8a-3b4d-4c9e-a7f2-1d5e8b9c0a32",
"emailEnabled": true
}
]
}
Responses
| Status | Meaning |
| 200 | The full preferences object. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
emailNotifications | object | |
emailNotifications.masterEnabled | boolean | |
emailNotifications.alerts | object[] | |
emailNotifications.alerts[].alertId | string (uuid) | |
emailNotifications.alerts[].alertName | string | |
emailNotifications.alerts[].trigger | string | Readable summary of the rule's triggers. |
emailNotifications.alerts[].severity | string | |
emailNotifications.alerts[].description | string | |
emailNotifications.alerts[].emailEnabled | boolean | |
digest | object | |
digest.enabled | boolean | |
digest.frequency | string | |
digest.sendTime | string | |
digest.timezone | string | |
digest.timeFormat | string | |
200 example
{
"emailNotifications": {
"masterEnabled": true,
"alerts": [
{
"alertId": "0193b6c2-0000-7000-8000-000000000000",
"alertName": "string",
"trigger": "string",
"severity": "string",
"description": "string",
"emailEnabled": true
}
]
},
"digest": {
"enabled": true,
"frequency": "string",
"sendTime": "string",
"timezone": "string",
"timeFormat": "string"
}
}
PUT
/locations/{locationId}/users/{userId}/first-alert/digest-preferences
Reseller admin
Set a user's alert digest
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
userId required | path | string (uuid) | |
Request body
| Field | Type | Description |
|---|
enabled required | boolean | |
frequency required | "daily" | "weekly" | "both" | "never" | |
sendTime required | string | 24-hour HH:MM. pattern ^\d{2}:\d{2}$ |
timezone required | string | IANA zone, e.g. America/Chicago. |
timeFormat | "12h" | "24h" | |
Example
{
"enabled": true,
"frequency": "daily",
"sendTime": "08:00",
"timezone": "America/Chicago",
"timeFormat": "12h"
}
Responses
| Status | Meaning |
| 200 | The full preferences object. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
emailNotifications | object | |
emailNotifications.masterEnabled | boolean | |
emailNotifications.alerts | object[] | |
emailNotifications.alerts[].alertId | string (uuid) | |
emailNotifications.alerts[].alertName | string | |
emailNotifications.alerts[].trigger | string | Readable summary of the rule's triggers. |
emailNotifications.alerts[].severity | string | |
emailNotifications.alerts[].description | string | |
emailNotifications.alerts[].emailEnabled | boolean | |
digest | object | |
digest.enabled | boolean | |
digest.frequency | string | |
digest.sendTime | string | |
digest.timezone | string | |
digest.timeFormat | string | |
200 example
{
"emailNotifications": {
"masterEnabled": true,
"alerts": [
{
"alertId": "0193b6c2-0000-7000-8000-000000000000",
"alertName": "string",
"trigger": "string",
"severity": "string",
"description": "string",
"emailEnabled": true
}
]
},
"digest": {
"enabled": true,
"frequency": "string",
"sendTime": "string",
"timezone": "string",
"timeFormat": "string"
}
}
Customer lifecycle (admin credentials)
Insights Hub
Which numbers and groups a location's Insights Hub covers.
GET
/locations/{locationId}/insights-hub/setup
Reseller admin
Read Insights Hub setup
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | Numbers covered and groups with access. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "insights_hub_setup" | |
data.attributes | object | |
data.attributes.connector_mappings | object[] | |
data.attributes.connector_mappings[].connector_id | string (uuid) | |
data.attributes.connector_mappings[].connector_name | string | |
data.attributes.connector_mappings[].connector_type | string | |
data.attributes.connector_mappings[].monitored_numbers | string[] | |
data.attributes.group_access | string (uuid)[] | |
data.attributes.available_connectors | object[] | |
data.attributes.available_connectors[].id | string (uuid) | |
data.attributes.available_connectors[].name | string | |
data.attributes.available_connectors[].type | string | |
data.attributes.groups | object[] | |
data.attributes.groups[].id | string (uuid) | |
data.attributes.groups[].group_name | string | |
data.attributes.groups[].has_access | boolean | |
200 example
{
"data": {
"type": "insights_hub_setup",
"attributes": {
"connector_mappings": [
{
"connector_id": "0193b6c2-0000-7000-8000-000000000000",
"connector_name": "string",
"connector_type": "string",
"monitored_numbers": [
"string"
]
}
],
"group_access": [
"0193b6c2-0000-7000-8000-000000000000"
],
"available_connectors": [
{
"id": "0193b6c2-0000-7000-8000-000000000000",
"name": "string",
"type": "string"
}
],
"groups": [
{
"id": "0193b6c2-0000-7000-8000-000000000000",
"group_name": "string",
"has_access": true
}
]
}
}
}
POST
/locations/{locationId}/insights-hub/setup
Reseller admin
Save Insights Hub setup
Upsert. Both keys are required ([] is allowed). A user sees Insights Hub when they are in a group_access group and have the insights-hub product.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
Request body
| Field | Type | Description |
|---|
connector_mappings required | object[] | |
connector_mappings[].connector_id required | string (uuid) | |
connector_mappings[].monitored_numbers required | string[] | Extensions or DIDs, as the phone system shows them. |
group_access required | string (uuid)[] | |
Example
{
"connector_mappings": [
{
"connector_id": "4b7e9d2c-1a3f-4e8b-9c6d-2f5a8e1b3c70",
"monitored_numbers": [
"2101",
"2102",
"2103"
]
}
],
"group_access": [
"0193b6c2-8d52-74e0-9b6a-2c7e1f3d5a11"
]
}
Responses
| Status | Meaning |
| 201 | Saved. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
201 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "insights_hub_setup" | |
data.attributes | object | |
data.attributes.connector_mappings | object[] | |
data.attributes.connector_mappings[].connector_id | string (uuid) | |
data.attributes.connector_mappings[].connector_name | string | |
data.attributes.connector_mappings[].connector_type | string | |
data.attributes.connector_mappings[].monitored_numbers | string[] | |
data.attributes.group_access | string (uuid)[] | |
data.attributes.available_connectors | object[] | |
data.attributes.available_connectors[].id | string (uuid) | |
data.attributes.available_connectors[].name | string | |
data.attributes.available_connectors[].type | string | |
data.attributes.groups | object[] | |
data.attributes.groups[].id | string (uuid) | |
data.attributes.groups[].group_name | string | |
data.attributes.groups[].has_access | boolean | |
201 example
{
"data": {
"type": "insights_hub_setup",
"attributes": {
"connector_mappings": [
{
"connector_id": "0193b6c2-0000-7000-8000-000000000000",
"connector_name": "string",
"connector_type": "string",
"monitored_numbers": [
"string"
]
}
],
"group_access": [
"0193b6c2-0000-7000-8000-000000000000"
],
"available_connectors": [
{
"id": "0193b6c2-0000-7000-8000-000000000000",
"name": "string",
"type": "string"
}
],
"groups": [
{
"id": "0193b6c2-0000-7000-8000-000000000000",
"group_name": "string",
"has_access": true
}
]
}
}
}
PATCH
/locations/{locationId}/insights-hub/setup
Reseller admin
Update Insights Hub setup
Each key you send replaces that list; an omitted key is unchanged.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
Request body
| Field | Type | Description |
|---|
connector_mappings | object[] | |
connector_mappings[].connector_id required | string (uuid) | |
connector_mappings[].monitored_numbers required | string[] | Extensions or DIDs, as the phone system shows them. |
group_access | string (uuid)[] | |
Example
{
"connector_mappings": [
{
"connector_id": "4b7e9d2c-1a3f-4e8b-9c6d-2f5a8e1b3c70",
"monitored_numbers": [
"2101",
"2102",
"2103",
"2104"
]
}
]
}
Responses
| Status | Meaning |
| 200 | Updated. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "insights_hub_setup" | |
data.attributes | object | |
data.attributes.connector_mappings | object[] | |
data.attributes.connector_mappings[].connector_id | string (uuid) | |
data.attributes.connector_mappings[].connector_name | string | |
data.attributes.connector_mappings[].connector_type | string | |
data.attributes.connector_mappings[].monitored_numbers | string[] | |
data.attributes.group_access | string (uuid)[] | |
data.attributes.available_connectors | object[] | |
data.attributes.available_connectors[].id | string (uuid) | |
data.attributes.available_connectors[].name | string | |
data.attributes.available_connectors[].type | string | |
data.attributes.groups | object[] | |
data.attributes.groups[].id | string (uuid) | |
data.attributes.groups[].group_name | string | |
data.attributes.groups[].has_access | boolean | |
200 example
{
"data": {
"type": "insights_hub_setup",
"attributes": {
"connector_mappings": [
{
"connector_id": "0193b6c2-0000-7000-8000-000000000000",
"connector_name": "string",
"connector_type": "string",
"monitored_numbers": [
"string"
]
}
],
"group_access": [
"0193b6c2-0000-7000-8000-000000000000"
],
"available_connectors": [
{
"id": "0193b6c2-0000-7000-8000-000000000000",
"name": "string",
"type": "string"
}
],
"groups": [
{
"id": "0193b6c2-0000-7000-8000-000000000000",
"group_name": "string",
"has_access": true
}
]
}
}
}
GET
/locations/{locationId}/insights-hub/config
Reseller admin
Read Insights Hub coverage
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | Coverage. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "insights_hub_config" | |
data.attributes | object | |
data.attributes.monitor_all_numbers | boolean | |
200 example
{
"data": {
"type": "insights_hub_config",
"attributes": {
"monitor_all_numbers": true
}
}
}
PATCH
/locations/{locationId}/insights-hub/config
Reseller admin
Set Insights Hub coverage
monitor_all_numbers: true lets Insights Hub users at the location see every call there.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
Request body
| Field | Type | Description |
|---|
monitor_all_numbers required | boolean | |
Example
{
"monitor_all_numbers": true
}
Responses
| Status | Meaning |
| 200 | Updated. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "insights_hub_config" | |
data.attributes | object | |
data.attributes.monitor_all_numbers | boolean | |
200 example
{
"data": {
"type": "insights_hub_config",
"attributes": {
"monitor_all_numbers": true
}
}
}
GET
/locations/{locationId}/users/{userId}/insights-hub/access
Reseller admin
Check a user's Insights Hub access
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
userId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | Access state. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "insights_hub_access" | |
data.attributes | object | |
data.attributes.enabled | boolean | |
data.attributes.group_name | string | null | |
200 example
{
"data": {
"type": "insights_hub_access",
"attributes": {
"enabled": true,
"group_name": "Insights Hub Access"
}
}
}
Customer lifecycle (admin credentials)
Users
People at a customer. Managers are frontline users on several locations, mapped to all lines at those locations. customer_admin users manage the company.
GET
/companies/{companyId}/users
Reseller admin
List a company's users
Filters combine with AND. Rows don't carry products or groups; use GET /locations/{locationId}/users for those. There is no product filter.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
search | query | string | Case-insensitive substring match on email, first name or last name (not the full name). |
status | query | "invited" | "active" | "deactivated" | Case-insensitive. Invalid values return 422. |
role | query | "customer_admin" | "frontline_user" | Invalid values return 422. |
location_id | query | string (uuid)[] (comma-separated) | One location id, or a comma-separated list of up to 100. Malformed values return 400. Admins with no location are excluded. max items 100 |
limit | query | integer | Page size. Invalid values fall back to the default. min 1, max 100, default 25 |
cursor | query | string | Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400. |
Responses
| Status | Meaning |
| 200 | One page of users. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object[] | |
data[].type | "company_user" | |
data[].attributes | object | |
data[].attributes.id | string (uuid) | |
data[].attributes.company_id | string (uuid) | |
data[].attributes.reseller_id | string (uuid) | |
data[].attributes.email | string (email) | |
data[].attributes.first_name | string | |
data[].attributes.last_name | string | |
data[].attributes.display_name | string | |
data[].attributes.phone_number | string | |
data[].attributes.department | string | |
data[].attributes.status | "invited" | "active" | "deactivated" | |
data[].attributes.role | "customer_admin" | "frontline_user" | |
data[].attributes.auth_method | "password" | "sso" | |
data[].attributes.invited_at | string (date-time) | null | |
data[].attributes.invite_expires_at | string (date-time) | null | |
data[].attributes.activated_at | string (date-time) | null | |
data[].attributes.last_login_at | string (date-time) | null | |
data[].attributes.locations | object[] | Single reads. |
data[].attributes.locations[].location_id | string (uuid) | |
data[].attributes.locations[].assigned_at | string (date-time) | |
data[].attributes.created_at | string (date-time) | |
data[].attributes.updated_at | string (date-time) | |
pagination | object | |
pagination.has_more | boolean | |
pagination.next_cursor | string | null | |
pagination.total_count | integer | |
200 example
{
"data": [
{
"type": "company_user",
"attributes": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"company_id": "0193b6c2-0000-7000-8000-000000000000",
"reseller_id": "0193b6c2-0000-7000-8000-000000000000",
"email": "user@example.com",
"first_name": "string",
"last_name": "string",
"display_name": "string",
"phone_number": "string",
"department": "string",
"status": "invited",
"role": "customer_admin",
"auth_method": "password",
"invited_at": "2026-11-02T15:04:05Z",
"invite_expires_at": "2026-11-02T15:04:05Z",
"activated_at": "2026-11-02T15:04:05Z",
"last_login_at": "2026-11-02T15:04:05Z",
"locations": [
{
"location_id": "0193b6c2-0000-7000-8000-000000000000",
"assigned_at": "2026-11-02T15:04:05Z"
}
],
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
],
"pagination": {
"has_more": true,
"next_cursor": "string",
"total_count": 0
}
}
POST
/companies/{companyId}/users
Reseller admin
Create a user
**Idempotency-Key is required** (400 without it). Send a new UUID per user and reuse it on retries: a replay returns the original response.
-
frontline_user needs location_ids. Managers are frontline users on several locations.
-
send_invitation: true emails the invitation (7-day expiry). For a new customer, create
with send_invitation: false, map the user's lines, then send the invitation with
POST /companies/{companyId}/users/{userId}/resend-invitation.
-
auth_method: sso for companies with single sign-on connected.
-
email is unique on the platform (409).
-
A 422 can leave the user behind. After a 422, look the user up with
GET /companies/{companyId}/users?search=<email> and fix it with PATCH rather than creating again.
-
The response can carry a one-time sign-in link for the invitee. Treat the whole response
as secret and never log it.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
Idempotency-Key required | header | string | A UUID per logical create. Reuse it when retrying the same create. |
Request body
| Field | Type | Description |
|---|
email required | string (email) | Unique on the platform. |
first_name required | string | min length 1, max length 100 |
last_name required | string | min length 1, max length 100 |
phone_number | string | max length 50 |
role required | "customer_admin" | "frontline_user" | |
location_ids | string (uuid)[] | Required for frontline_user. |
send_invitation | boolean | Email the invitation now. |
auth_method | "password" | "sso" | default "password" |
Example
{
"email": "sam.ortiz@example.com",
"first_name": "Sam",
"last_name": "Ortiz",
"phone_number": "+15555550143",
"role": "frontline_user",
"location_ids": [
"0193b6c2-6b29-7a51-b0e4-1c8f3d5e7a02"
],
"send_invitation": true,
"auth_method": "password"
}
Responses
| Status | Meaning |
| 201 | Created, status invited. |
| 400 | Missing Idempotency-Key (the body is {"error": "<message>"}), or a malformed field. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 409 | The email is already in use. |
| 422 | Invalid value (unknown location, role not assignable). The user may still have been created; see above. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
201 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "company_user" | |
data.attributes | object | |
data.attributes.id | string (uuid) | |
data.attributes.company_id | string (uuid) | |
data.attributes.reseller_id | string (uuid) | |
data.attributes.email | string (email) | |
data.attributes.first_name | string | |
data.attributes.last_name | string | |
data.attributes.display_name | string | |
data.attributes.phone_number | string | |
data.attributes.department | string | |
data.attributes.status | "invited" | "active" | "deactivated" | |
data.attributes.role | "customer_admin" | "frontline_user" | |
data.attributes.auth_method | "password" | "sso" | |
data.attributes.invited_at | string (date-time) | null | |
data.attributes.invite_expires_at | string (date-time) | null | |
data.attributes.activated_at | string (date-time) | null | |
data.attributes.last_login_at | string (date-time) | null | |
data.attributes.locations | object[] | Single reads. |
data.attributes.locations[].location_id | string (uuid) | |
data.attributes.locations[].assigned_at | string (date-time) | |
data.attributes.created_at | string (date-time) | |
data.attributes.updated_at | string (date-time) | |
201 example
{
"data": {
"type": "company_user",
"attributes": {
"id": "0193b6c2-7c44-7d12-a3f9-8e2b6c1d4f55",
"company_id": "0193b6c2-5a11-7c3e-8f20-6d4b9e1c2a77",
"reseller_id": "0193b6c2-41d8-7e0a-9c55-2f7d1e3a9b10",
"email": "sam.ortiz@example.com",
"first_name": "Sam",
"last_name": "Ortiz",
"display_name": "Sam Ortiz",
"phone_number": "+15555550143",
"status": "invited",
"role": "frontline_user",
"auth_method": "password",
"invited_at": "2026-11-02T15:20:00Z",
"invite_expires_at": "2026-11-09T15:20:00Z",
"created_at": "2026-11-02T15:20:00Z",
"updated_at": "2026-11-02T15:20:00Z"
}
}
}
GET
/companies/{companyId}/users/{userId}
Reseller admin
Read a user
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
userId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | The user, with locations[]. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "company_user" | |
data.attributes | object | |
data.attributes.id | string (uuid) | |
data.attributes.company_id | string (uuid) | |
data.attributes.reseller_id | string (uuid) | |
data.attributes.email | string (email) | |
data.attributes.first_name | string | |
data.attributes.last_name | string | |
data.attributes.display_name | string | |
data.attributes.phone_number | string | |
data.attributes.department | string | |
data.attributes.status | "invited" | "active" | "deactivated" | |
data.attributes.role | "customer_admin" | "frontline_user" | |
data.attributes.auth_method | "password" | "sso" | |
data.attributes.invited_at | string (date-time) | null | |
data.attributes.invite_expires_at | string (date-time) | null | |
data.attributes.activated_at | string (date-time) | null | |
data.attributes.last_login_at | string (date-time) | null | |
data.attributes.locations | object[] | Single reads. |
data.attributes.locations[].location_id | string (uuid) | |
data.attributes.locations[].assigned_at | string (date-time) | |
data.attributes.created_at | string (date-time) | |
data.attributes.updated_at | string (date-time) | |
200 example
{
"data": {
"type": "company_user",
"attributes": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"company_id": "0193b6c2-0000-7000-8000-000000000000",
"reseller_id": "0193b6c2-0000-7000-8000-000000000000",
"email": "user@example.com",
"first_name": "string",
"last_name": "string",
"display_name": "string",
"phone_number": "string",
"department": "string",
"status": "invited",
"role": "customer_admin",
"auth_method": "password",
"invited_at": "2026-11-02T15:04:05Z",
"invite_expires_at": "2026-11-02T15:04:05Z",
"activated_at": "2026-11-02T15:04:05Z",
"last_login_at": "2026-11-02T15:04:05Z",
"locations": [
{
"location_id": "0193b6c2-0000-7000-8000-000000000000",
"assigned_at": "2026-11-02T15:04:05Z"
}
],
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
}
PATCH
/companies/{companyId}/users/{userId}
Reseller admin
Update a user, role or locations
Every field is optional.
-
**
location_ids replaces the user's locations.** This is how you assign and move users.
-
Changing
frontline_user to customer_admin drops all location assignments.
-
Changing to
frontline_user needs location_ids in the same request (422 otherwise);
redo group membership afterwards.
-
The email address cannot be changed.
-
Works on a deactivated user.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
userId required | path | string (uuid) | |
Request body
| Field | Type | Description |
|---|
first_name | string | min length 1, max length 100 |
last_name | string | min length 1, max length 100 |
phone_number | string | max length 50 |
department | string | max length 255 |
role | "customer_admin" | "frontline_user" | |
location_ids | string (uuid)[] | Replaces the user's locations. |
Example
{
"location_ids": [
"0193b6c2-6b29-7a51-b0e4-1c8f3d5e7a02",
"0193b6c2-6b30-7a51-b0e4-1c8f3d5e7a03"
]
}
Responses
| Status | Meaning |
| 200 | Updated. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "company_user" | |
data.attributes | object | |
data.attributes.id | string (uuid) | |
data.attributes.company_id | string (uuid) | |
data.attributes.reseller_id | string (uuid) | |
data.attributes.email | string (email) | |
data.attributes.first_name | string | |
data.attributes.last_name | string | |
data.attributes.display_name | string | |
data.attributes.phone_number | string | |
data.attributes.department | string | |
data.attributes.status | "invited" | "active" | "deactivated" | |
data.attributes.role | "customer_admin" | "frontline_user" | |
data.attributes.auth_method | "password" | "sso" | |
data.attributes.invited_at | string (date-time) | null | |
data.attributes.invite_expires_at | string (date-time) | null | |
data.attributes.activated_at | string (date-time) | null | |
data.attributes.last_login_at | string (date-time) | null | |
data.attributes.locations | object[] | Single reads. |
data.attributes.locations[].location_id | string (uuid) | |
data.attributes.locations[].assigned_at | string (date-time) | |
data.attributes.created_at | string (date-time) | |
data.attributes.updated_at | string (date-time) | |
200 example
{
"data": {
"type": "company_user",
"attributes": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"company_id": "0193b6c2-0000-7000-8000-000000000000",
"reseller_id": "0193b6c2-0000-7000-8000-000000000000",
"email": "user@example.com",
"first_name": "string",
"last_name": "string",
"display_name": "string",
"phone_number": "string",
"department": "string",
"status": "invited",
"role": "customer_admin",
"auth_method": "password",
"invited_at": "2026-11-02T15:04:05Z",
"invite_expires_at": "2026-11-02T15:04:05Z",
"activated_at": "2026-11-02T15:04:05Z",
"last_login_at": "2026-11-02T15:04:05Z",
"locations": [
{
"location_id": "0193b6c2-0000-7000-8000-000000000000",
"assigned_at": "2026-11-02T15:04:05Z"
}
],
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
}
POST
/companies/{companyId}/users/{userId}/deactivate
Reseller admin
Deactivate a user
Deactivates the user company-wide and blocks sign-in. Products, group membership and number mappings are kept. For a leaver, also clear groups (PUT …/group-membership with []), disable products, and clear number mappings (PUT …/connector-mappings with []).
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
userId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | Deactivated. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 409 | Conflict (duplicate name or email, already active or inactive). Read the message. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "company_user" | |
data.attributes | object | |
data.attributes.id | string (uuid) | |
data.attributes.company_id | string (uuid) | |
data.attributes.reseller_id | string (uuid) | |
data.attributes.email | string (email) | |
data.attributes.first_name | string | |
data.attributes.last_name | string | |
data.attributes.display_name | string | |
data.attributes.phone_number | string | |
data.attributes.department | string | |
data.attributes.status | "invited" | "active" | "deactivated" | |
data.attributes.role | "customer_admin" | "frontline_user" | |
data.attributes.auth_method | "password" | "sso" | |
data.attributes.invited_at | string (date-time) | null | |
data.attributes.invite_expires_at | string (date-time) | null | |
data.attributes.activated_at | string (date-time) | null | |
data.attributes.last_login_at | string (date-time) | null | |
data.attributes.locations | object[] | Single reads. |
data.attributes.locations[].location_id | string (uuid) | |
data.attributes.locations[].assigned_at | string (date-time) | |
data.attributes.created_at | string (date-time) | |
data.attributes.updated_at | string (date-time) | |
200 example
{
"data": {
"type": "company_user",
"attributes": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"company_id": "0193b6c2-0000-7000-8000-000000000000",
"reseller_id": "0193b6c2-0000-7000-8000-000000000000",
"email": "user@example.com",
"first_name": "string",
"last_name": "string",
"display_name": "string",
"phone_number": "string",
"department": "string",
"status": "invited",
"role": "customer_admin",
"auth_method": "password",
"invited_at": "2026-11-02T15:04:05Z",
"invite_expires_at": "2026-11-02T15:04:05Z",
"activated_at": "2026-11-02T15:04:05Z",
"last_login_at": "2026-11-02T15:04:05Z",
"locations": [
{
"location_id": "0193b6c2-0000-7000-8000-000000000000",
"assigned_at": "2026-11-02T15:04:05Z"
}
],
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
}
POST
/companies/{companyId}/users/{userId}/reactivate
Reseller admin
Reactivate a user
A user who never accepted the invitation comes back as active with no password. Resend the invitation for them.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
userId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | Reactivated. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 409 | Conflict (duplicate name or email, already active or inactive). Read the message. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "company_user" | |
data.attributes | object | |
data.attributes.id | string (uuid) | |
data.attributes.company_id | string (uuid) | |
data.attributes.reseller_id | string (uuid) | |
data.attributes.email | string (email) | |
data.attributes.first_name | string | |
data.attributes.last_name | string | |
data.attributes.display_name | string | |
data.attributes.phone_number | string | |
data.attributes.department | string | |
data.attributes.status | "invited" | "active" | "deactivated" | |
data.attributes.role | "customer_admin" | "frontline_user" | |
data.attributes.auth_method | "password" | "sso" | |
data.attributes.invited_at | string (date-time) | null | |
data.attributes.invite_expires_at | string (date-time) | null | |
data.attributes.activated_at | string (date-time) | null | |
data.attributes.last_login_at | string (date-time) | null | |
data.attributes.locations | object[] | Single reads. |
data.attributes.locations[].location_id | string (uuid) | |
data.attributes.locations[].assigned_at | string (date-time) | |
data.attributes.created_at | string (date-time) | |
data.attributes.updated_at | string (date-time) | |
200 example
{
"data": {
"type": "company_user",
"attributes": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"company_id": "0193b6c2-0000-7000-8000-000000000000",
"reseller_id": "0193b6c2-0000-7000-8000-000000000000",
"email": "user@example.com",
"first_name": "string",
"last_name": "string",
"display_name": "string",
"phone_number": "string",
"department": "string",
"status": "invited",
"role": "customer_admin",
"auth_method": "password",
"invited_at": "2026-11-02T15:04:05Z",
"invite_expires_at": "2026-11-02T15:04:05Z",
"activated_at": "2026-11-02T15:04:05Z",
"last_login_at": "2026-11-02T15:04:05Z",
"locations": [
{
"location_id": "0193b6c2-0000-7000-8000-000000000000",
"assigned_at": "2026-11-02T15:04:05Z"
}
],
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
}
POST
/companies/{companyId}/users/{userId}/resend-invitation
Reseller admin
Resend the invitation email
Emails a fresh invitation with a new 7-day expiry. 409 when the user has no pending invitation.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
userId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 202 | Sent. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 409 | Conflict (duplicate name or email, already active or inactive). Read the message. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
202 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "invitation_resend" | |
data.attributes | object | |
data.attributes.user_id | string (uuid) | |
data.attributes.email | string (email) | |
data.attributes.invite_expires_at | string (date-time) | |
data.attributes.message | string | |
202 example
{
"data": {
"type": "invitation_resend",
"attributes": {
"user_id": "0193b6c2-7c44-7d12-a3f9-8e2b6c1d4f55",
"email": "sam.ortiz@example.com",
"invite_expires_at": "2026-11-09T15:30:00Z",
"message": "Invitation email resent successfully"
}
}
}
POST
/companies/{companyId}/users/{userId}/reset-password
Reseller admin
Send a password reset email
For active password users. An invited user returns 409; resend the invitation instead.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
userId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 202 | Reset email sent. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 409 | Conflict (duplicate name or email, already active or inactive). Read the message. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
202 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "password_reset" | |
data.attributes | object | |
data.attributes.user_id | string (uuid) | |
data.attributes.email | string (email) | |
data.attributes.message | string | |
202 example
{
"data": {
"type": "password_reset",
"attributes": {
"user_id": "0193b6c2-0000-7000-8000-000000000000",
"email": "user@example.com",
"message": "string"
}
}
}
GET
/companies/{companyId}/users/{userId}/connector-mappings
Reseller admin
Read a user's numbers
The lines whose calls this user sees.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
userId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | Mappings. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object[] | |
data[].connector_id | string (uuid) | |
data[].connector_name | string | |
data[].connector_type | string | |
data[].monitored_numbers | string[] | |
200 example
{
"data": [
{
"connector_id": "0193b6c2-0000-7000-8000-000000000000",
"connector_name": "string",
"connector_type": "string",
"monitored_numbers": [
"string"
]
}
]
}
PUT
/companies/{companyId}/users/{userId}/connector-mappings
Reseller admin
Set a user's numbers
Full replacement, company-wide for this user. mappings: [] clears.
-
Frontline users get their own extension; managers get every line at their locations.
-
Extensions come from the phone system: read them there with your own key. This API
cannot list them.
-
The connector must be
active (422 otherwise).
-
409: an extension is already monitored at another location. Release it there first.
Show your own message; don't display the response text.
Parameters
| Name | In | Type | Description |
companyId required | path | string (uuid) | |
userId required | path | string (uuid) | |
Request body
| Field | Type | Description |
|---|
mappings required | object[] | |
mappings[].connector_id required | string (uuid) | |
mappings[].monitored_numbers required | string[] | Extensions or DIDs, as the phone system shows them. |
Example
{
"mappings": [
{
"connector_id": "4b7e9d2c-1a3f-4e8b-9c6d-2f5a8e1b3c70",
"monitored_numbers": [
"2101"
]
}
]
}
Responses
| Status | Meaning |
| 200 | Saved. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 409 | An extension is already monitored at another location. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 503 | The extension check is briefly unavailable. Retry. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object[] | |
data[].connector_id | string (uuid) | |
data[].connector_name | string | |
data[].connector_type | string | |
data[].monitored_numbers | string[] | |
200 example
{
"data": [
{
"connector_id": "0193b6c2-0000-7000-8000-000000000000",
"connector_name": "string",
"connector_type": "string",
"monitored_numbers": [
"string"
]
}
]
}
GET
/locations/{locationId}/users
Reseller admin
List a location's users with products and groups
Rows include enabled_products[] and groups[] (names), so one call per location gives a full seat view. Returns 422 on an inactive location.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
search | query | string | Case-insensitive substring match on email, first name or last name. |
status | query | "invited" | "active" | "deactivated" | |
limit | query | integer | Page size. Send 100 and follow next_cursor. min 1, max 100, default 20 |
cursor | query | string | Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400. |
Responses
| Status | Meaning |
| 200 | One page of users. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object[] | |
data[].type | "location_user" | |
data[].attributes | object | |
data[].attributes.id | string (uuid) | |
data[].attributes.company_id | string (uuid) | |
data[].attributes.email | string (email) | |
data[].attributes.first_name | string | |
data[].attributes.last_name | string | |
data[].attributes.display_name | string | |
data[].attributes.phone_number | string | |
data[].attributes.role | "customer_admin" | "frontline_user" | |
data[].attributes.status | "invited" | "active" | "deactivated" | |
data[].attributes.invited_at | string (date-time) | null | |
data[].attributes.created_at | string (date-time) | |
data[].attributes.location_id | string (uuid) | |
data[].attributes.location_name | string | |
data[].attributes.assigned_at | string (date-time) | |
data[].attributes.locations | object[] | null | |
data[].attributes.locations[].location_id | string (uuid) | |
data[].attributes.locations[].assigned_at | string (date-time) | |
data[].attributes.groups | string[] | null | Group names. Filled on list rows. |
data[].attributes.enabled_products | "after-call-copilot" | "first-alert-copilot" | "insights-hub"[] | null | |
pagination | object | |
pagination.has_more | boolean | |
pagination.next_cursor | string | null | |
pagination.total_count | integer | |
200 example
{
"data": [
{
"type": "location_user",
"attributes": {
"id": "0193b6c2-7c45-7d12-a3f9-8e2b6c1d4f56",
"company_id": "0193b6c2-5a11-7c3e-8f20-6d4b9e1c2a77",
"email": "alex.kim@example.com",
"first_name": "Alex",
"last_name": "Kim",
"display_name": "Alex Kim",
"phone_number": "+15555550144",
"role": "frontline_user",
"status": "active",
"location_id": "0193b6c2-6b29-7a51-b0e4-1c8f3d5e7a02",
"groups": [
"Insights Hub Access",
"Upset Customers"
],
"enabled_products": [
"after-call-copilot",
"first-alert-copilot",
"insights-hub"
]
}
}
],
"pagination": {
"has_more": false
}
}
GET
/locations/{locationId}/users/{userId}
Reseller admin
Read a user at a location
Includes enabled_products[]. groups is null here; use the list or group membership.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
userId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | The user. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.type | "location_user" | |
data.attributes | object | |
data.attributes.id | string (uuid) | |
data.attributes.company_id | string (uuid) | |
data.attributes.email | string (email) | |
data.attributes.first_name | string | |
data.attributes.last_name | string | |
data.attributes.display_name | string | |
data.attributes.phone_number | string | |
data.attributes.role | "customer_admin" | "frontline_user" | |
data.attributes.status | "invited" | "active" | "deactivated" | |
data.attributes.invited_at | string (date-time) | null | |
data.attributes.created_at | string (date-time) | |
data.attributes.location_id | string (uuid) | |
data.attributes.location_name | string | |
data.attributes.assigned_at | string (date-time) | |
data.attributes.locations | object[] | null | |
data.attributes.locations[].location_id | string (uuid) | |
data.attributes.locations[].assigned_at | string (date-time) | |
data.attributes.groups | string[] | null | Group names. Filled on list rows. |
data.attributes.enabled_products | "after-call-copilot" | "first-alert-copilot" | "insights-hub"[] | null | |
200 example
{
"data": {
"type": "location_user",
"attributes": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"company_id": "0193b6c2-0000-7000-8000-000000000000",
"email": "user@example.com",
"first_name": "string",
"last_name": "string",
"display_name": "string",
"phone_number": "string",
"role": "customer_admin",
"status": "invited",
"invited_at": "2026-11-02T15:04:05Z",
"created_at": "2026-11-02T15:04:05Z",
"location_id": "0193b6c2-0000-7000-8000-000000000000",
"location_name": "string",
"assigned_at": "2026-11-02T15:04:05Z",
"locations": [
{
"location_id": "0193b6c2-0000-7000-8000-000000000000",
"assigned_at": "2026-11-02T15:04:05Z"
}
],
"groups": [
"string"
],
"enabled_products": [
"after-call-copilot"
]
}
}
}
Customer lifecycle (admin credentials)
After Call settings
Each user's After Call summary email, end-of-day recap and digest, and number mapping.
GET
/locations/{locationId}/users/{userId}/after-call-settings
Reseller admin
Read a user's After Call settings
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
userId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | Settings and number mappings. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.user_id | string (uuid) | |
data.eoc_enabled | boolean | |
data.eod_enabled | boolean | |
data.eod_timezone | string | null | |
data.eod_time | string | null | |
data.digest_frequency | string | |
data.digest_time_format | string | |
data.connector_mappings | object[] | |
data.connector_mappings[].connector_id | string (uuid) | |
data.connector_mappings[].connector_name | string | |
data.connector_mappings[].connector_status | "connecting" | "active" | "error" | "deactivating" | "inactive" | connecting → active (calls flow) or error. Deactivate: deactivating → inactive. Reactivate: back to connecting. |
data.connector_mappings[].monitored_numbers | string[] | |
data.last_changed_by | string (uuid) | null | |
data.last_changed_at | string (date-time) | null | |
200 example
{
"data": {
"user_id": "0193b6c2-7c44-7d12-a3f9-8e2b6c1d4f55",
"eoc_enabled": true,
"eod_enabled": true,
"eod_timezone": "America/Chicago",
"eod_time": "17:30",
"digest_frequency": "daily",
"digest_time_format": "12h",
"connector_mappings": [
{
"connector_id": "4b7e9d2c-1a3f-4e8b-9c6d-2f5a8e1b3c70",
"connector_name": "Riverbend phone system",
"connector_status": "active",
"monitored_numbers": [
"2101"
]
}
],
"last_changed_by": "0193b6c2-41d9-7e0a-9c55-2f7d1e3a9b11",
"last_changed_at": "2026-11-02T15:25:00Z"
}
}
PATCH
/locations/{locationId}/users/{userId}/after-call-settings
Reseller admin
Update a user's After Call settings
Partial update: omitted keys keep their value.
-
connector_mappings is a full replacement of the user's numbers (same store as
PUT /companies/{companyId}/users/{userId}/connector-mappings); [] clears. The connector
must be active (422 CONNECTOR_NOT_VALID). 409 means an extension is already monitored at
another location.
-
A
digest_frequency other than never needs eod_time and eod_timezone.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
userId required | path | string (uuid) | |
Request body
| Field | Type | Description |
|---|
eoc_enabled | boolean | Email a summary after each call. |
eod_enabled | boolean | Send the end-of-day recap. |
eod_time | string | 24-hour HH:MM. pattern ^\d{2}:\d{2}$ |
eod_timezone | string | IANA zone. |
digest_frequency | "daily" | "weekly" | "both" | "never" | |
digest_time_format | "12h" | "24h" | |
connector_mappings | object[] | Replaces the user's numbers. [] clears. |
connector_mappings[].connector_id required | string (uuid) | |
connector_mappings[].monitored_numbers required | string[] | Extensions or DIDs, as the phone system shows them. |
Example
{
"eoc_enabled": true,
"eod_enabled": true,
"eod_time": "17:30",
"eod_timezone": "America/Chicago",
"digest_frequency": "daily"
}
Responses
| Status | Meaning |
| 200 | Updated. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 409 | An extension is already monitored at another location. |
| 422 | CONNECTOR_NOT_VALID, INVALID_EOD_TIME, INVALID_TIMEZONE or INVALID_FREQUENCY. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | The extension check is briefly unavailable. Retry. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.user_id | string (uuid) | |
data.eoc_enabled | boolean | |
data.eod_enabled | boolean | |
data.eod_timezone | string | null | |
data.eod_time | string | null | |
data.digest_frequency | string | |
data.digest_time_format | string | |
data.connector_mappings | object[] | |
data.connector_mappings[].connector_id | string (uuid) | |
data.connector_mappings[].connector_name | string | |
data.connector_mappings[].connector_status | "connecting" | "active" | "error" | "deactivating" | "inactive" | connecting → active (calls flow) or error. Deactivate: deactivating → inactive. Reactivate: back to connecting. |
data.connector_mappings[].monitored_numbers | string[] | |
data.last_changed_by | string (uuid) | null | |
data.last_changed_at | string (date-time) | null | |
200 example
{
"data": {
"user_id": "0193b6c2-0000-7000-8000-000000000000",
"eoc_enabled": true,
"eod_enabled": true,
"eod_timezone": "string",
"eod_time": "string",
"digest_frequency": "string",
"digest_time_format": "string",
"connector_mappings": [
{
"connector_id": "0193b6c2-0000-7000-8000-000000000000",
"connector_name": "string",
"connector_status": "connecting",
"monitored_numbers": [
"string"
]
}
],
"last_changed_by": "0193b6c2-0000-7000-8000-000000000000",
"last_changed_at": "2026-11-02T15:04:05Z"
}
}
Conversation intelligence (frontline credentials)
Account
Who is signed in, and which locations the login can see.
GET
/me
Frontline useralso Customer adminalso Reseller admin
Who is signed in
Call at startup. Check role: conversation-data endpoints return empty lists to admin logins. scopes[] is the authoritative list of what this login may do.
Responses
| Status | Meaning |
| 200 | The signed-in user. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.id | string (uuid) | |
data.email | string (email) | |
data.first_name | string | |
data.last_name | string | |
data.display_name | string | |
data.user_type | "company_user" | "reseller_user" | |
data.role | "frontline_user" | "customer_admin" | "reseller_admin" | "reseller_support" | reseller_support has an admin's reach but is read-only. |
data.status | string | |
data.scopes | string[] | |
data.reseller_id | string (uuid) | null | |
data.company_id | string (uuid) | null | |
data.location_ids | string (uuid)[] | null | |
data.enabled_products | "after-call-copilot" | "first-alert-copilot" | "insights-hub"[] | null | |
data.mfa_available | boolean | |
200 example
{
"data": {
"id": "0193b6c2-7c46-7d12-a3f9-8e2b6c1d4f57",
"email": "integration@example.com",
"first_name": "Data",
"last_name": "Feed",
"display_name": "Data Feed",
"user_type": "company_user",
"role": "frontline_user",
"status": "active",
"scopes": [
"calls:read",
"alerts:read",
"insights:read"
],
"reseller_id": "0193b6c2-41d8-7e0a-9c55-2f7d1e3a9b10",
"company_id": "0193b6c2-5a11-7c3e-8f20-6d4b9e1c2a77",
"location_ids": [
"0193b6c2-6b29-7a51-b0e4-1c8f3d5e7a02"
],
"enabled_products": [
"after-call-copilot",
"first-alert-copilot",
"insights-hub"
],
"mfa_available": true
}
}
GET
/locations
Frontline useralso Customer adminalso Reseller admin
Locations this login can see
A frontline login sees its assigned locations; an admin login sees every location it manages. Use the ids for location_id filters.
Parameters
| Name | In | Type | Description |
search | query | string | Case-insensitive substring match on location_name. |
is_active | query | boolean | true or false. Other values return 422.
|
company_id | query | string (uuid) | |
limit | query | integer | Values above 100 are capped. min 1, max 100, default 20 |
cursor | query | string | Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400. |
offset | query | integer | Rows to skip. Prefer cursor. min 0 |
Responses
| Status | Meaning |
| 200 | One page of locations. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object[] | |
data[].type | "location" | |
data[].attributes | object | |
data[].attributes.id | string (uuid) | |
data[].attributes.company_id | string (uuid) | |
data[].attributes.company_name | string | |
data[].attributes.reseller_name | string | |
data[].attributes.location_name | string | |
data[].attributes.street | string | |
data[].attributes.city | string | |
data[].attributes.state | string | |
data[].attributes.country | string | |
data[].attributes.zipcode | string | |
data[].attributes.support_contact_name | string | |
data[].attributes.support_contact_email | string | |
data[].attributes.support_contact_phone | string | |
data[].attributes.vertical_id | string (uuid) | |
data[].attributes.vertical_name | string | |
data[].attributes.enabled_products | "after-call-copilot" | "first-alert-copilot" | "insights-hub"[] | |
data[].attributes.is_active | boolean | |
data[].attributes.user_count | integer | On list rows. |
data[].attributes.created_at | string (date-time) | |
data[].attributes.updated_at | string (date-time) | |
pagination | object | |
pagination.has_more | boolean | |
pagination.next_cursor | string | null | |
pagination.total_count | integer | |
200 example
{
"data": [
{
"type": "location",
"attributes": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"company_id": "0193b6c2-0000-7000-8000-000000000000",
"company_name": "string",
"reseller_name": "string",
"location_name": "string",
"street": "string",
"city": "string",
"state": "string",
"country": "string",
"zipcode": "string",
"support_contact_name": "string",
"support_contact_email": "string",
"support_contact_phone": "string",
"vertical_id": "0193b6c2-0000-7000-8000-000000000000",
"vertical_name": "string",
"enabled_products": [
"after-call-copilot"
],
"is_active": true,
"user_count": 0,
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
],
"pagination": {
"has_more": true,
"next_cursor": "string",
"total_count": 0
}
}
Conversation intelligence (frontline credentials)
Calls
Every conversation the login can see, with summary, sentiment, transcript and recording link.
GET
/calls
Frontline user
List calls
Every conversation the login can see, newest first. All filters combine with AND. Default window: 00:00 UTC seven days ago until now. Page with cursor until has_more is false. Admin logins get an empty list.
Parameters
| Name | In | Type | Description |
date_from | query | string (date-time) | Start of the window (inclusive), on the call date. Full RFC 3339 timestamp required, e.g. 2026-11-01T00:00:00Z or 2026-11-01T00:00:00-06:00; a date alone returns 400. Default: 00:00 UTC seven days ago. date_from after date_to returns 422; a span over 366 days returns 422 when both are sent. |
date_to | query | string (date-time) | End of the window (inclusive). Full RFC 3339 timestamp required. Default: now. A date_to alone that is older than the default start returns an empty list. |
status | query | "completed" | "missed" | "voicemail" | "failed" | "cancelled" | Call outcome. One value, case-sensitive. Invalid values return 422. |
sentiment | query | "crisis" | "very_negative" | "negative" | "mildly_negative" | "below_neutral" | "neutral" | "positive" | "none" | One sentiment band. Score bands: crisis ≤ −80; very_negative −79 to −60; negative −59 to −40; mildly_negative −39 to −20; below_neutral −19 to −1; neutral 0; positive ≥ 1. negative, neutral and positive also match records with that label and no score. none matches records with no sentiment. Invalid values return 422. |
has_open_tasks | query | "true" | Only true is recognised (calls with at least one open task). Any other value is ignored. |
multi_leg | query | boolean | true: calls with more than one leg (leg_count > 1). false: single-leg calls. Accepts true/false/1/0/t/f; other values return 400.
|
location_id | query | string (uuid)[] (comma-separated) | One location id or a comma-separated list. A location you can't see matches nothing. Malformed ids return 400. Keep lists to about 50 ids (URL length). max items 100 |
company_id | query | string (uuid) | Narrow to one company. |
search | query | string | Free text, at least 2 characters (shorter is ignored). Matches caller and callee names (typo-tolerant), numbers in any format including partial digits and extensions, the summary, key points and the transcript. Name and number matches come first. Call ids don't match; use GET /calls/{callId}. min length 2 |
cursor | query | string | Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400. |
limit | query | integer | Page size. Out-of-range values return 400. Use 100 for exports. min 1, max 100, default 10 |
Responses
| Status | Meaning |
| 200 | One page of calls with totals for the whole filter. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.summary | object | Totals for every call matching the filters (all pages). |
data.summary.total_calls | integer | |
data.summary.completed_calls | integer | |
data.summary.missed_calls | integer | |
data.summary.total_duration | integer | |
data.summary.tasks_done | integer | |
data.summary.pending | integer | |
data.summary.total_tasks | integer | |
data.calls | object[] | |
data.calls[].id | string (uuid) | |
data.calls[].location_id | string (uuid) | |
data.calls[].call_date | string (date-time) | |
data.calls[].caller_timezone | string | null | |
data.calls[].caller_name | string | null | |
data.calls[].caller_number | string | null | |
data.calls[].callee_name | string | null | |
data.calls[].callee_number | string | null | |
data.calls[].call_type | "inbound" | "outbound" | "internal" | "missed" | "forwarded" | "unknown" | |
data.calls[].status | "completed" | "missed" | "voicemail" | "failed" | "cancelled" | |
data.calls[].sentiment | "positive" | "neutral" | "negative" | null | |
data.calls[].sentiment_score | integer | null | min -100, max 100 |
data.calls[].sentiment_label | string | |
data.calls[].summary | string | null | |
data.calls[].top_highlight | string | null | |
data.calls[].highlights | string[] | |
data.calls[].duration | integer | Seconds. |
data.calls[].leg_count | integer | |
data.calls[].task_count | integer | |
data.calls[].completed_task_count | integer | |
meta | object | Paging for conversation data. Stop when has_more is false. |
meta.has_more | boolean | |
meta.next_cursor | string | null | |
meta.limit | integer | |
200 example
{
"data": {
"summary": {
"total_calls": 412,
"completed_calls": 361,
"missed_calls": 0,
"total_duration": 98140,
"tasks_done": 37,
"pending": 12,
"total_tasks": 49
},
"calls": [
{
"id": "0193b6d0-1e2f-7a3b-8c4d-5e6f7a8b9c01",
"location_id": "0193b6c2-6b29-7a51-b0e4-1c8f3d5e7a02",
"call_date": "2026-11-02T16:41:07Z",
"caller_timezone": "UTC",
"caller_name": "Morgan Diaz",
"caller_number": "+15555550142",
"callee_name": "Sam Ortiz",
"callee_number": "2101",
"call_type": "inbound",
"status": "completed",
"sentiment": "negative",
"sentiment_score": -46,
"sentiment_label": "negative",
"summary": "The caller's car was promised for Friday and is still not ready. Sam offered a loaner and a call back by noon.",
"top_highlight": "Car not ready on promised date",
"highlights": [
"Car not ready on promised date",
"Loaner offered",
"Call back by noon"
],
"duration": 284,
"leg_count": 1,
"task_count": 1,
"completed_task_count": 0
}
]
},
"meta": {
"has_more": true,
"next_cursor": "eyJkIjoiMjAyNi0xMS0wMlQxNjo0MTowN1oifQ==",
"limit": 10
}
}
GET
/calls/{callId}
Frontline user
Read a call
Full detail: analysis, tasks and the call's recording link (inside the conversation record, vcon.recording_url). A call outside the login's view returns 404 (admin logins always get 404). A call linked to an alert you can see opens.
Recording link: a signed HTTPS link to the WAV audio. Fetch it with a plain GET and no Authorization header; Range requests are supported. It expires 120 minutes after issue (recording_url_expires_at). The link is a secret: don't log it or store it, and call this endpoint again for a fresh link each time you need the audio.
Parameters
| Name | In | Type | Description |
callId required | path | string (uuid) | Call id. Malformed ids return 400. |
Responses
| Status | Meaning |
| 200 | The call. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.id | string (uuid) | |
data.call_date | string (date-time) | |
data.caller_timezone | string | null | |
data.caller_name | string | null | |
data.caller_number | string | null | |
data.callee_name | string | null | |
data.callee_number | string | null | |
data.call_type | string | |
data.call_outcome | string | Same values as status on the list. |
data.duration | integer | |
data.leg_count | integer | |
data.platform | string | Phone system type, e.g. netsapiens. |
data.sentiment | "positive" | "neutral" | "negative" | null | |
data.sentiment_score | integer | null | |
data.sentiment_label | string | |
data.summary | string | null | |
data.analysis | object | null | |
data.analysis.summary | object | |
data.analysis.summary.text | string | |
data.analysis.summary.key_points | string[] | |
data.analysis.summary.action_items | string[] | |
data.analysis.sentiment | object | |
data.analysis.sentiment.overall | string | |
data.analysis.topics | object[] | null | |
data.analysis.topics[].name | string | |
data.vcon | object | The call's recording link (inside the conversation record). Only the fields below are documented; ignore anything else in this object. |
data.vcon.recording_url | string (uri) | null | Signed HTTPS link to the call audio (WAV). Plain GET, no Authorization header; Range requests supported. Expires 120 minutes after issue. A secret: never log or store it; request the call again for a fresh link. Null when the call has no recording. |
data.vcon.recording_url_expires_at | string (date-time) | null | When recording_url stops working. |
data.vcon.recording_mime_type | string | null | audio/wav. |
data.tasks | object[] | Up to 100. See has_more_tasks. |
data.tasks[].id | string (uuid) | |
data.tasks[].title | string | |
data.tasks[].description | string | null | |
data.tasks[].status | string | |
data.tasks[].source | string | |
data.tasks[].assignee_user | object | null | |
data.tasks[].assignee_user.id | string (uuid) | |
data.tasks[].assignee_user.display_name | string | |
data.tasks[].assignee_user.email | string (email) | |
data.tasks[].due_date | string | null | |
data.task_count | integer | |
data.has_more_tasks | boolean | |
200 example
{
"data": {
"id": "0193b6d0-1e2f-7a3b-8c4d-5e6f7a8b9c01",
"call_date": "2026-11-02T16:41:07Z",
"caller_timezone": "UTC",
"caller_name": "Morgan Diaz",
"caller_number": "+15555550142",
"callee_name": "Sam Ortiz",
"callee_number": "2101",
"call_type": "inbound",
"call_outcome": "completed",
"duration": 284,
"leg_count": 1,
"platform": "netsapiens",
"sentiment": "negative",
"sentiment_score": -46,
"sentiment_label": "negative",
"summary": "The caller's car was promised for Friday and is still not ready. Sam offered a loaner and a call back by noon.",
"analysis": {
"summary": {
"text": "The caller's car was promised for Friday and is still not ready. Sam offered a loaner and a call back by noon.",
"key_points": [
"Car not ready on promised date",
"Loaner offered"
],
"action_items": [
"Call Morgan back by noon with a new date"
]
},
"sentiment": {
"overall": "negative"
},
"topics": [
{
"name": "Service delay"
}
]
},
"vcon": {
"recording_url": "https://recordings.example.com/r/0193b6d0.wav?sig=EXAMPLE-SIGNATURE",
"recording_url_expires_at": "2026-11-02T18:45:00Z",
"recording_mime_type": "audio/wav"
},
"tasks": [
{
"id": "0193b6d0-3a4b-7c5d-8e6f-7a8b9c0d1e23",
"title": "Call Morgan back by noon with a new date",
"description": null,
"status": "pending",
"source": "ai",
"assignee_user": {
"id": "0193b6c2-7c44-7d12-a3f9-8e2b6c1d4f55",
"display_name": "Sam Ortiz",
"email": "sam.ortiz@example.com"
},
"due_date": "2026-11-03"
}
],
"task_count": 1,
"has_more_tasks": false
}
}
GET
/calls/{callId}/transcript
Frontline user
Read a call's transcript
Speakers are labelled "Speaker 1" … "Speaker N"; name carries the person when known.
Parameters
| Name | In | Type | Description |
callId required | path | string (uuid) | Call id. Malformed ids return 400. |
Responses
| Status | Meaning |
| 200 | Transcript lines in order. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.transcript | object[] | |
data.transcript[].time | number | Seconds from the start of the call. |
data.transcript[].speaker | string | "Speaker 1" … "Speaker N". |
data.transcript[].name | string | |
data.transcript[].text | string | |
200 example
{
"data": {
"transcript": [
{
"time": 0.4,
"speaker": "Speaker 1",
"name": "Sam Ortiz",
"text": "Riverbend service, this is Sam."
},
{
"time": 2.9,
"speaker": "Speaker 2",
"name": "Morgan Diaz",
"text": "Hi Sam, I'm calling about my car. It was supposed to be ready Friday."
}
]
}
}
Conversation intelligence (frontline credentials)
Alerts
First Alert hits, for look-ups by number, rule, date and location. Alerts as they fire arrive on the First Alert webhook.
GET
/alerts
Frontline user
List alerts
First Alert hits the login can see, newest first. All filters combine with AND. Default window: 00:00 UTC seven days ago until now. Use it for look-ups by number, rule, date and location, not as a feed: alerts as they fire arrive on the First Alert webhook. After your receiver was unavailable, read the missed window once (date_from 30 minutes before it went down, date_to when it came back) and de-duplicate on id. To read one alert, GET /alerts?search=<alert id> (lowercase id; no date window needed). Admin logins get an empty list.
Parameters
| Name | In | Type | Description |
date_from | query | string (date-time) | Start of the window (inclusive), on the call date. Full RFC 3339 timestamp required, e.g. 2026-11-01T00:00:00Z or 2026-11-01T00:00:00-06:00; a date alone returns 400. Default: 00:00 UTC seven days ago. date_from after date_to returns 422; a span over 366 days returns 422 when both are sent. |
date_to | query | string (date-time) | End of the window (inclusive). Full RFC 3339 timestamp required. Default: now. A date_to alone that is older than the default start returns an empty list. |
keyword | query | string | Exact alert rule name, case-sensitive, one value. This is how you filter by rule. |
topic | query | string | Exact topic slug, one value. |
numbers | query | string[] (comma-separated) | Comma-separated, up to 25 entries. Each entry is letters, digits, @ or # only (no +, - or spaces; strip to digits first). Each entry is a substring match on the caller or callee number; entries are OR'ed together. max items 25 |
sentiment | query | "crisis" | "very_negative" | "negative" | "mildly_negative" | "below_neutral" | "neutral" | "positive" | "none" | One sentiment band. Score bands: crisis ≤ −80; very_negative −79 to −60; negative −59 to −40; mildly_negative −39 to −20; below_neutral −19 to −1; neutral 0; positive ≥ 1. negative, neutral and positive also match records with that label and no score. none matches records with no sentiment. Invalid values return 422. |
search | query | string | Matches caller or callee name or number, summary text, or an exact lowercase alert id. Rule names don't match; use keyword. |
location_id | query | string (uuid)[] (comma-separated) | One location id or a comma-separated list. A location you can't see matches nothing. Malformed ids return 400. Keep lists to about 50 ids (URL length). max items 100 |
company_id | query | string (uuid) | Narrow to one company. |
cursor | query | string | Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400. |
limit | query | integer | Page size. Out-of-range values return 400. Use 100 for exports. min 1, max 100, default 10 |
Responses
| Status | Meaning |
| 200 | One page of alerts. summary.total counts every match. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.summary | object | |
data.summary.total | integer | Every match, all pages. |
data.alerts | object[] | |
data.alerts[].id | string (uuid) | |
data.alerts[].call_id | string (uuid) | Open with GET /calls/{callId}. |
data.alerts[].call_date | string (date-time) | |
data.alerts[].caller_timezone | string | |
data.alerts[].caller_name | string | |
data.alerts[].caller_number | string | |
data.alerts[].callee_name | string | |
data.alerts[].callee_number | string | |
data.alerts[].summary | string | |
data.alerts[].sentiment | string | |
data.alerts[].sentiment_score | integer | null | |
data.alerts[].sentiment_label | string | |
data.alerts[].keywords | string[] | Names of the rules that fired. |
data.alerts[].topics | string[] | |
meta | object | Paging for conversation data. Stop when has_more is false. |
meta.has_more | boolean | |
meta.next_cursor | string | null | |
meta.limit | integer | |
200 example
{
"data": {
"summary": {
"total": 3
},
"alerts": [
{
"id": "0193b6d0-2f3a-7b4c-9d5e-6f7a8b9c0d12",
"call_id": "0193b6d0-1e2f-7a3b-8c4d-5e6f7a8b9c01",
"call_date": "2026-11-02T16:41:07Z",
"caller_timezone": "UTC",
"caller_name": "Morgan Diaz",
"caller_number": "+15555550142",
"callee_name": "Sam Ortiz",
"callee_number": "2101",
"summary": "The caller's car was promised for Friday and is still not ready.",
"sentiment": "negative",
"sentiment_score": -46,
"sentiment_label": "negative",
"keywords": [
"Upset Customer"
],
"topics": []
}
]
},
"meta": {
"has_more": false,
"next_cursor": null,
"limit": 10
}
}
GET
/alerts/dashboard
Frontline user
Alert totals
Counts for the window. Default window as /alerts. Other /alerts filters don't apply here.
Parameters
| Name | In | Type | Description |
date_from | query | string (date-time) | Start of the window (inclusive), on the call date. Full RFC 3339 timestamp required, e.g. 2026-11-01T00:00:00Z or 2026-11-01T00:00:00-06:00; a date alone returns 400. Default: 00:00 UTC seven days ago. date_from after date_to returns 422; a span over 366 days returns 422 when both are sent. |
date_to | query | string (date-time) | End of the window (inclusive). Full RFC 3339 timestamp required. Default: now. A date_to alone that is older than the default start returns an empty list. |
location_id | query | string (uuid)[] (comma-separated) | One location id or a comma-separated list. A location you can't see matches nothing. Malformed ids return 400. Keep lists to about 50 ids (URL length). max items 100 |
company_id | query | string (uuid) | Narrow to one company. |
Responses
| Status | Meaning |
| 200 | Totals. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.kpis | object | |
data.kpis.new_alerts | integer | |
data.kpis.monitored | integer | Calls in the window. |
data.kpis.alert_rate | number | new_alerts / monitored × 100. |
data.top_triggered | object[] | max items 10 |
data.top_triggered[].keyword | string | Rule name. |
data.top_triggered[].count | integer | |
data.recent_alerts | object[] | max items 5 |
data.recent_alerts[].id | string (uuid) | |
data.recent_alerts[].call_id | string (uuid) | Open with GET /calls/{callId}. |
data.recent_alerts[].call_date | string (date-time) | |
data.recent_alerts[].caller_timezone | string | |
data.recent_alerts[].caller_name | string | |
data.recent_alerts[].caller_number | string | |
data.recent_alerts[].callee_name | string | |
data.recent_alerts[].callee_number | string | |
data.recent_alerts[].summary | string | |
data.recent_alerts[].sentiment | string | |
data.recent_alerts[].sentiment_score | integer | null | |
data.recent_alerts[].sentiment_label | string | |
data.recent_alerts[].keywords | string[] | Names of the rules that fired. |
data.recent_alerts[].topics | string[] | |
200 example
{
"data": {
"kpis": {
"new_alerts": 3,
"monitored": 412,
"alert_rate": 0.73
},
"top_triggered": [
{
"keyword": "Upset Customer",
"count": 2
},
{
"keyword": "Customer Threat",
"count": 1
}
],
"recent_alerts": []
}
}
Conversation intelligence (frontline credentials)
Tasks
Follow-up tasks from calls.
GET
/tasks
Frontline user
List tasks
Follow-up tasks from calls, newest first. Filters combine with AND. No default window. Errors on this endpoint use error.type instead of error.code, and bad values return 400. Admin logins get an empty list.
Parameters
| Name | In | Type | Description |
status | query | "pending" | "in_progress" | "done" | "overdue" | "open" | Display status: done (completed); pending (not done, no due date); in_progress (not done, due today or later); overdue (not done, due before today); open (not done). summary counts ignore this filter. |
today_start | query | string (date-time) | Your local midnight as a full RFC 3339 timestamp, e.g. 2026-11-02T00:00:00-06:00. Sets the boundary for overdue and in_progress. |
call_id | query | string (uuid) | Tasks of one call. |
task_id | query | string (uuid) | One task. Can't be combined with due_on. |
due_on | query | string (date) | Tasks due on this calendar date (YYYY-MM-DD). |
date_from | query | string (date-time) | Created at or after. Full RFC 3339 timestamp required. No default. |
date_to | query | string (date-time) | Created at or before. Full RFC 3339 timestamp required. date_from after date_to returns an empty list. |
search | query | string | Substring match on title and description. |
location_id | query | string (uuid)[] (comma-separated) | One location id or a comma-separated list. A location you can't see matches nothing. Malformed ids return 400. Keep lists to about 50 ids (URL length). max items 100 |
company_id | query | string (uuid) | Narrow to one company. |
cursor | query | string | Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400. |
limit | query | integer | Page size. Send 100 and follow next_cursor. min 1, max 100, default 20 |
Responses
| Status | Meaning |
| 200 | One page of tasks. |
| 400 | Malformed or invalid parameter. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object[] | |
data[].id | string (uuid) | |
data[].call_id | string (uuid) | |
data[].company_id | string (uuid) | |
data[].location_id | string (uuid) | |
data[].title | string | |
data[].description | string | null | |
data[].status | "pending" | "in_progress" | "completed" | "cancelled" | Stored status. |
data[].source | "ai" | "manual" | |
data[].assignee_user | object | null | |
data[].assignee_user.id | string (uuid) | |
data[].assignee_user.display_name | string | |
data[].assignee_user.email | string (email) | |
data[].due_date | string | null | |
data[].completed_at | string (date-time) | null | |
data[].created_at | string (date-time) | |
data[].updated_at | string (date-time) | |
meta | object | Paging for conversation data. Stop when has_more is false. |
meta.has_more | boolean | |
meta.next_cursor | string | null | |
meta.limit | integer | |
summary | object | Counts by display status. Honours every filter except status. |
summary.total | integer | |
summary.done | integer | |
summary.in_progress | integer | |
summary.pending | integer | |
summary.overdue | integer | |
200 example
{
"data": [
{
"id": "0193b6d0-3a4b-7c5d-8e6f-7a8b9c0d1e23",
"call_id": "0193b6d0-1e2f-7a3b-8c4d-5e6f7a8b9c01",
"company_id": "0193b6c2-5a11-7c3e-8f20-6d4b9e1c2a77",
"location_id": "0193b6c2-6b29-7a51-b0e4-1c8f3d5e7a02",
"title": "Call Morgan back by noon with a new date",
"description": null,
"status": "pending",
"source": "ai",
"assignee_user": {
"id": "0193b6c2-7c44-7d12-a3f9-8e2b6c1d4f55",
"display_name": "Sam Ortiz",
"email": "sam.ortiz@example.com"
},
"due_date": "2026-11-03",
"completed_at": null,
"created_at": "2026-11-02T16:46:00Z",
"updated_at": "2026-11-02T16:46:00Z"
}
],
"meta": {
"has_more": false,
"next_cursor": null,
"limit": 20
},
"summary": {
"total": 49,
"done": 37,
"in_progress": 4,
"pending": 6,
"overdue": 2
}
}
Conversation intelligence (frontline credentials)
Insights
Insights Hub dashboard and topic drill-down.
GET
/insights/dashboard
Frontline user
Insights Hub dashboard
Call volume, trending topics and topic volumes for a window. start and end are required.
Parameters
| Name | In | Type | Description |
start required | query | string (date-time) | Window start. Full RFC 3339 timestamp required. |
end required | query | string (date-time) | Window end. Full RFC 3339 timestamp required. At most 366 days after start (422). |
trending_limit | query | integer | Number of trending topics, 1 to 10. Values above 10 return 10; values below 1, or not a number, fall back to the default of 4. Neither returns an error. min 1, max 10, default 4 |
location_id | query | string (uuid)[] (comma-separated) | One location id or a comma-separated list. A location you can't see matches nothing. Malformed ids return 400. Keep lists to about 50 ids (URL length). max items 100 |
company_id | query | string (uuid) | Narrow to one company. |
Responses
| Status | Meaning |
| 200 | Dashboard. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.stats | object | |
data.stats.total_calls | integer | |
data.stats.answered_calls | integer | |
data.stats.unanswered_calls | integer | |
data.trending_topics | object[] | |
data.trending_topics[].slug | string | |
data.trending_topics[].name | string | |
data.trending_topics[].call_count | integer | |
data.trending_topics[].previous_call_count | integer | |
data.trending_topics[].percentage_change | integer | |
data.trending_topics[].trend_data | object[] | |
data.trending_topics[].trend_data[].day | string | |
data.trending_topics[].trend_data[].current | integer | |
data.trending_topics[].trend_data[].previous | integer | |
data.topic_call_volumes | object[] | |
data.topic_call_volumes[].slug | string | |
data.topic_call_volumes[].name | string | |
data.topic_call_volumes[].call_count | integer | |
200 example
{
"data": {
"stats": {
"total_calls": 412,
"answered_calls": 361,
"unanswered_calls": 51
},
"trending_topics": [
{
"slug": "service-delay",
"name": "Service delay",
"call_count": 38,
"previous_call_count": 22,
"percentage_change": 73,
"trend_data": [
{
"day": "2026-10-27",
"current": 4,
"previous": 3
}
]
}
],
"topic_call_volumes": [
{
"slug": "service-delay",
"name": "Service delay",
"call_count": 38
}
]
}
}
GET
/insights/topics/{slug}/calls
Frontline user
Calls for one topic
Default window 00:00 UTC seven days ago until now. Filters combine with AND.
Parameters
| Name | In | Type | Description |
slug required | path | string | Topic slug from the dashboard's topic_call_volumes[].slug. An unknown slug returns an empty list. |
date_from | query | string (date-time) | Start of the window, on the call date. Full RFC 3339 timestamp required, e.g. 2026-11-01T00:00:00Z or 2026-11-01T00:00:00-06:00; a date alone returns 400. Default: 00:00 UTC seven days ago. |
date_to | query | string (date-time) | End of the window. Full RFC 3339 timestamp required; a date alone returns 400. Default: now. |
sentiment | query | "positive" | "neutral" | "negative" | Coarse band only. Other values return 422. |
outcome | query | "completed" | "missed" | "pending" | Other values return 422. |
search | query | string | Same matching as /calls search. |
location_id | query | string (uuid)[] (comma-separated) | One location id or a comma-separated list. A location you can't see matches nothing. Malformed ids return 400. Keep lists to about 50 ids (URL length). max items 100 |
company_id | query | string (uuid) | Narrow to one company. |
cursor | query | string | Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400. |
limit | query | integer | min 1, max 100, default 25 |
Responses
| Status | Meaning |
| 200 | One page of calls. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object[] | |
data[].id | string (uuid) | |
data[].date | string (date-time) | |
data[].caller_name | string | null | |
data[].summary | string | null | |
data[].phone_number | string | null | |
data[].sentiment | string | null | |
data[].sentiment_label | string | |
data[].outcome | string | |
meta | object | |
meta.total | integer | |
meta.has_more | boolean | |
meta.next_cursor | string | null | |
200 example
{
"data": [
{
"id": "0193b6c2-0000-7000-8000-000000000000",
"date": "2026-11-02T15:04:05Z",
"caller_name": "string",
"summary": "string",
"phone_number": "string",
"sentiment": "string",
"sentiment_label": "string",
"outcome": "string"
}
],
"meta": {
"total": 0,
"has_more": true,
"next_cursor": "string"
}
}
Conversation intelligence (frontline credentials)
Events and webhooks
The After Call webhook (one URL per location, every call at the location) and the First Alert location webhook. Both are configured with admin credentials. Payloads are listed under Webhooks.
GET
/locations/{locationId}/after-call/automation
Reseller adminalso Customer admin
Read the After Call webhook
{"data": null} when no webhook is set. Read it with admin credentials. Rotate the address's path token every 90 days and when someone with access to the location leaves.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | The webhook, or null. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | null | |
data.id | string (uuid) | |
data.location_id | string (uuid) | |
data.webhook_url | string | |
data.enabled | boolean | |
data.created_at | string (date-time) | |
data.updated_at | string (date-time) | |
200 example
{
"data": {
"id": "0193b6c4-0a1b-7c2d-8e3f-4a5b6c7d8e90",
"location_id": "0193b6c2-6b29-7a51-b0e4-1c8f3d5e7a02",
"webhook_url": "https://hooks.example.com/riverbend/calls",
"enabled": true,
"created_at": "2026-11-02T15:30:00Z",
"updated_at": "2026-11-02T15:30:00Z"
}
}
PUT
/locations/{locationId}/after-call/automation
Reseller adminalso Customer admin
Set the After Call webhook
One HTTPS URL per location. It receives every call at the location, whatever users' number mappings say. enabled defaults to true. There is no delete: pause with enabled: false. Frontline logins get 403. Treat the URL as a secret.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
Request body
| Field | Type | Description |
|---|
webhook_url required | string (uri) | HTTPS only. Private and loopback addresses are refused. max length 2048 |
enabled | boolean | default true |
Example
{
"webhook_url": "https://hooks.example.com/riverbend/calls",
"enabled": true
}
Responses
| Status | Meaning |
| 200 | Saved. |
| 400 | Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field). |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 403 | This login's role cannot do this (FORBIDDEN). |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 422 | Valid shape, invalid value (enum, date order, range, unknown reference). |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | null | |
data.id | string (uuid) | |
data.location_id | string (uuid) | |
data.webhook_url | string | |
data.enabled | boolean | |
data.created_at | string (date-time) | |
data.updated_at | string (date-time) | |
200 example
{
"data": {
"id": "0193b6c2-0000-7000-8000-000000000000",
"location_id": "0193b6c2-0000-7000-8000-000000000000",
"webhook_url": "string",
"enabled": true,
"created_at": "2026-11-02T15:04:05Z",
"updated_at": "2026-11-02T15:04:05Z"
}
}
POST
/locations/{locationId}/after-call/automation/test
Reseller adminalso Customer admin
Send a test After Call event
Sends the test payload (is_test: true) to the saved URL, even while paused. A URL in the request body is ignored.
Parameters
| Name | In | Type | Description |
locationId required | path | string (uuid) | |
Responses
| Status | Meaning |
| 200 | Test result. |
| 401 | Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape. |
| 403 | This login's role cannot do this (FORBIDDEN). |
| 404 | Not found, or outside what this login may see. Treat as absent. |
| 429 | Rate limited. Back off with jitter, and honour Retry-After if it is present. |
| 503 | Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present. |
200 response fields
| Field | Type | Description |
|---|
data | object | |
data.success | boolean | |
data.http_status | integer | HTTP status your endpoint returned. |
data.response_time_ms | integer | |
200 example
{
"data": {
"success": true,
"http_status": 200,
"response_time_ms": 182
}
}
Payloads are listed under Webhook payloads.
Events
Webhook payloads
Intelligence Cloud calls your endpoint with these requests.
POST
webhook: afterCallSummary
Reseller admin
After Call summary (end_of_call_summary)
Sent to the location's After Call webhook URL after each call is processed, for every call at the location.
-
POST with Content-Type: application/json and User-Agent: IntelligenceCloud-ACCWebhook/1.0.
-
Answer 2xx within 2 seconds; queue the work. Redirects (3xx) count as failures.
-
Don't authenticate on the
User-Agent: anyone can send it. The path token is the credential.
-
Three attempts in all (backoff 1 s, then 2 s), then the delivery is dropped. There is no replay.
-
Requests are not signed. Use a long, unguessable URL and treat it as a secret.
-
No ordering guarantee. Expect repeats (retries, and calls with several legs): upsert on
call.id, and when an id repeats, read the call again and update your record.
-
Treat the event as a notification: read
GET /calls/{call.id} before you write anything from
it into another system. A 404 means drop it.
-
Answer 2xx to any JSON body and ignore event types you don't handle.
Request body (webhook payload)
| Field | Type | Description |
|---|
version required | "1.0" | |
type required | "end_of_call_summary" | |
is_test required | boolean | true only for test sends. |
location_id required | string (uuid) | |
timestamp required | string (date-time) | When Intelligence Cloud created the conversation record (UTC). Not the call time or the delivery time. |
call required | object | |
call.id required | string (uuid) | Same id as GET /calls/{callId} and an alert's call_id. Upsert on it. |
call.caller_name | string | Omitted when empty. |
call.caller_number | string | Omitted when empty. |
call.callee_name | string | Omitted when empty. |
call.callee_number | string | Omitted when empty. |
call.call_type required | "inbound" | "outbound" | "internal" | "missed" | "forwarded" | "unknown" | |
call.duration_seconds required | integer | |
call.call_date required | string (date) | Date only (UTC). |
call.platform | string | Phone system type. Omitted when empty. |
summary | object | Omitted when the call has no summary. |
summary.text | string | |
summary.sentiment | string | Usually positive, neutral or negative. |
summary.key_points | string[] | Test sends only. |
summary.action_items | string[] | Test sends only. |
location required | object | |
location.id | string (uuid) | |
location.company_id | string (uuid) | |
location.connector_id | string (uuid) | |
Example
{
"version": "1.0",
"type": "end_of_call_summary",
"is_test": false,
"location_id": "0193b6c2-6b29-7a51-b0e4-1c8f3d5e7a02",
"timestamp": "2026-11-02T16:46:12Z",
"call": {
"id": "0193b6d0-1e2f-7a3b-8c4d-5e6f7a8b9c01",
"caller_name": "Morgan Diaz",
"caller_number": "+15555550142",
"callee_name": "Sam Ortiz",
"callee_number": "2101",
"call_type": "inbound",
"duration_seconds": 284,
"call_date": "2026-11-02",
"platform": "netsapiens"
},
"summary": {
"text": "The caller's car was promised for Friday and is still not ready. Sam offered a loaner and a call back by noon.",
"sentiment": "negative"
},
"location": {
"id": "0193b6c2-6b29-7a51-b0e4-1c8f3d5e7a02",
"company_id": "0193b6c2-5a11-7c3e-8f20-6d4b9e1c2a77",
"connector_id": "4b7e9d2c-1a3f-4e8b-9c6d-2f5a8e1b3c70"
}
}
Responses
| Status | Meaning |
| 200 | Any 2xx acknowledges the delivery. |
POST
webhook: firstAlert
Reseller admin
First Alert (location webhook)
Sent to the webhook_url in the location's First Alert configuration (PUT /locations/{locationId}/first-alert/config) when an alert fires at the location. Test it with POST /locations/{locationId}/first-alert/config/test-webhook.
The payload describes the alert: alert id, rule, location, call and time. Answer 2xx quickly, then read the alert with GET /alerts?search=<alert id> and the call with GET /calls/{callId}. De-duplicate on the alert id. If your receiver was unavailable, read the missed window of GET /alerts once and skip ids you have already handled.
Request body (webhook payload)
The alert that fired (alert id, rule, location, call, time).
Responses
| Status | Meaning |
| 200 | Any 2xx acknowledges the delivery. |