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": "…"}.

StatusMeaning
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
403This login's role cannot do this (FORBIDDEN).
404Not found, or outside what this login may see. Treat as absent.
409Conflict (duplicate name or email, already active or inactive). Read the message.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate 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

FieldTypeDescription
email requiredstring (email)
password requiredstring (password)
Example
{
  "email": "integration@example.com",
  "password": "<password>"
}

Responses

StatusMeaning
200Signed in, or a second factor is required.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401invalid_credentials, account_deactivated or account_not_activated.
409federated_address: this address signs in through the company's identity provider.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily 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

FieldTypeDescription
refresh_token requiredstring
Example
{
  "refresh_token": "<refresh token>"
}

Responses

StatusMeaning
200Renewed. Same body as login.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401refresh_token_invalid, refresh_token_expired, session_revoked or renewal_replayed. Sign in again.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
access_token requiredstringSend as Authorization: Bearer <access_token>. Never log it.
refresh_token requiredstringSingle use. Store the new one after every refresh. Never log it.
token_type required"Bearer"
expires_in requiredintegerSeconds until the access token expires (about 900).
user requiredobject
user.idstring (uuid)
user.user_type"company_user" | "reseller_user"
user.reseller_idstring (uuid) | null
user.emailstring (email)
user.first_namestring
user.last_namestring
user.display_namestring
user.role"frontline_user" | "customer_admin" | "reseller_admin" | "reseller_support"reseller_support has an admin's reach but is read-only.
user.scopesstring[]
password_expiredbooleanPresent 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

StatusMeaning
200Signed out everywhere.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
messagestring
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

NameInTypeDescription
resellerId requiredpathstring (uuid)

Your reseller id (reseller_id from GET /me).

Responses

StatusMeaning
200Branding. Unset fields are null.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.typestring
data.attributesobject
data.attributes.reseller_idstring (uuid)
data.attributes.display_namestring | null
data.attributes.primary_accent_colorstring | null
data.attributes.secondary_accent_colorstring | null
data.attributes.support_emailstring | null
data.attributes.support_portal_urlstring | null
data.attributes.privacy_policy_urlstring | null
data.attributes.terms_of_service_urlstring | null
data.attributes.copyright_textstring | null
data.attributes.main_logo_urlstring | nullSet in the Admin UI
data.attributes.favicon_urlstring | nullSet in the Admin UI
data.attributes.email_logo_urlstring | nullSet in the Admin UI
data.attributes.created_atstring (date-time) | null
data.attributes.updated_atstring (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

NameInTypeDescription
resellerId requiredpathstring (uuid)

Your reseller id (reseller_id from GET /me).

Request body

FieldTypeDescription
display_namestringProduct name shown in the app and in emails.
max length 200
primary_accent_colorstring
pattern ^#[0-9A-Fa-f]{6}$
secondary_accent_colorstring
pattern ^#[0-9A-Fa-f]{6}$
support_emailstring (email)
max length 255
support_portal_urlstring (uri)
max length 2048
privacy_policy_urlstring (uri)
max length 2048
terms_of_service_urlstring (uri)
max length 2048
copyright_textstring
max length 500
Example
{
  "display_name": "Harborview Intelligence",
  "primary_accent_color": "#1F6FB2",
  "support_email": "support@example.com"
}

Responses

StatusMeaning
200Updated branding.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.typestring
data.attributesobject
data.attributes.reseller_idstring (uuid)
data.attributes.display_namestring | null
data.attributes.primary_accent_colorstring | null
data.attributes.secondary_accent_colorstring | null
data.attributes.support_emailstring | null
data.attributes.support_portal_urlstring | null
data.attributes.privacy_policy_urlstring | null
data.attributes.terms_of_service_urlstring | null
data.attributes.copyright_textstring | null
data.attributes.main_logo_urlstring | nullSet in the Admin UI
data.attributes.favicon_urlstring | nullSet in the Admin UI
data.attributes.email_logo_urlstring | nullSet in the Admin UI
data.attributes.created_atstring (date-time) | null
data.attributes.updated_atstring (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

NameInTypeDescription
resellerId requiredpathstring (uuid)

Your reseller id (reseller_id from GET /me).

Responses

StatusMeaning
200Settings.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404No SMTP settings are configured.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.typestring
data.attributesobject
data.attributes.reseller_idstring (uuid)
data.attributes.smtp_hoststring
data.attributes.smtp_portinteger
data.attributes.smtp_usernamestring
data.attributes.smtp_passwordstringAlways masked.
data.attributes.sender_namestring
data.attributes.sender_emailstring (email)
data.attributes.created_atstring (date-time)
data.attributes.updated_atstring (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

NameInTypeDescription
resellerId requiredpathstring (uuid)

Your reseller id (reseller_id from GET /me).

Request body

FieldTypeDescription
smtp_host requiredstring
smtp_port requiredinteger587 (STARTTLS) is recommended; 465 is implicit TLS.
min 1, max 65535
smtp_usernamestring
smtp_passwordstring (password)Stored encrypted. Never returned.
sender_name requiredstring
max length 200
sender_email requiredstring (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

StatusMeaning
200Tested and saved (updated).
201Tested and saved (first time).
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
422The connection test failed. Nothing was saved.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.typestring
data.attributesobject
data.attributes.reseller_idstring (uuid)
data.attributes.smtp_hoststring
data.attributes.smtp_portinteger
data.attributes.smtp_usernamestring
data.attributes.smtp_passwordstringAlways masked.
data.attributes.sender_namestring
data.attributes.sender_emailstring (email)
data.attributes.created_atstring (date-time)
data.attributes.updated_atstring (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

NameInTypeDescription
resellerId requiredpathstring (uuid)

Your reseller id (reseller_id from GET /me).

Responses

StatusMeaning
204Removed.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily 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

NameInTypeDescription
resellerId requiredpathstring (uuid)

Your reseller id (reseller_id from GET /me).

searchquerystring

Case-insensitive prefix match on company_name only. "Riverbend" matches "Riverbend Auto Group"; "Auto Group" does not.

is_activequeryboolean

true for active companies, false for deactivated ones.

limitqueryinteger

Page size. Send 100 and follow next_cursor.


min 1, max 100, default 20
cursorquerystring

Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400.

Responses

StatusMeaning
200One page of companies.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject[]
data[].type"company"
data[].attributesobject
data[].attributes.idstring (uuid)
data[].attributes.reseller_idstring (uuid)
data[].attributes.reseller_namestringEmpty in the create response.
data[].attributes.company_namestring
data[].attributes.company_codestring | null
data[].attributes.verticalstring | null
data[].attributes.addressstring | null
data[].attributes.primary_admin_contact_namestring
data[].attributes.primary_admin_contact_emailstring (email)
data[].attributes.primary_admin_contact_phonestring
data[].attributes.enabled_products"after-call-copilot" | "first-alert-copilot" | "insights-hub"[]
data[].attributes.is_activeboolean
data[].attributes.mfa_enforcedboolean
data[].attributes.mfa_availablebooleanSingle read only.
data[].attributes.location_countintegerCorrect on list rows; 0 on single reads.
data[].attributes.user_countintegerCorrect on list rows; 0 on single reads.
data[].attributes.created_atstring (date-time)
data[].attributes.updated_atstring (date-time)
has_moreboolean
next_cursorstring | null
total_countinteger
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

NameInTypeDescription
resellerId requiredpathstring (uuid)

Your reseller id (reseller_id from GET /me).

Request body

FieldTypeDescription
company_name requiredstring
min length 2, max length 200
company_codestring
max length 50
primary_admin_contact_name requiredstring
min length 2, max length 100
primary_admin_contact_email requiredstring (email)Unique on the platform. This person is invited as customer admin.
primary_admin_contact_phone requiredstring
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

StatusMeaning
201Created. invited_user is the primary contact.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
409The contact email is already in use on the platform (this also catches a retried create).
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
201 response fields
FieldTypeDescription
dataobject
data.type"company"
data.attributesobject
data.attributes.idstring (uuid)
data.attributes.reseller_idstring (uuid)
data.attributes.reseller_namestringEmpty in the create response.
data.attributes.company_namestring
data.attributes.company_codestring | null
data.attributes.verticalstring | null
data.attributes.addressstring | null
data.attributes.primary_admin_contact_namestring
data.attributes.primary_admin_contact_emailstring (email)
data.attributes.primary_admin_contact_phonestring
data.attributes.enabled_products"after-call-copilot" | "first-alert-copilot" | "insights-hub"[]
data.attributes.is_activeboolean
data.attributes.mfa_enforcedboolean
data.attributes.mfa_availablebooleanSingle read only.
data.attributes.location_countintegerCorrect on list rows; 0 on single reads.
data.attributes.user_countintegerCorrect on list rows; 0 on single reads.
data.attributes.created_atstring (date-time)
data.attributes.updated_atstring (date-time)
invited_userobject
invited_user.idstring (uuid)
invited_user.emailstring (email)
invited_user.display_namestring
invited_user.status"invited"
invited_user.role"customer_admin"
invited_user.invited_atstring (date-time)
invited_user.invite_expires_atstring (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

NameInTypeDescription
resellerId requiredpathstring (uuid)

Your reseller id (reseller_id from GET /me).

Responses

StatusMeaning
200MFA summary.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.total_activeinteger
data.with_mfa_requiredinteger
data.companies_mfa_defaultboolean
data.mfa_availableboolean
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

NameInTypeDescription
companyId requiredpathstring (uuid)

Responses

StatusMeaning
200The company.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.type"company"
data.attributesobject
data.attributes.idstring (uuid)
data.attributes.reseller_idstring (uuid)
data.attributes.reseller_namestringEmpty in the create response.
data.attributes.company_namestring
data.attributes.company_codestring | null
data.attributes.verticalstring | null
data.attributes.addressstring | null
data.attributes.primary_admin_contact_namestring
data.attributes.primary_admin_contact_emailstring (email)
data.attributes.primary_admin_contact_phonestring
data.attributes.enabled_products"after-call-copilot" | "first-alert-copilot" | "insights-hub"[]
data.attributes.is_activeboolean
data.attributes.mfa_enforcedboolean
data.attributes.mfa_availablebooleanSingle read only.
data.attributes.location_countintegerCorrect on list rows; 0 on single reads.
data.attributes.user_countintegerCorrect on list rows; 0 on single reads.
data.attributes.created_atstring (date-time)
data.attributes.updated_atstring (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

NameInTypeDescription
companyId requiredpathstring (uuid)

Request body

FieldTypeDescription
company_namestring
min length 2, max length 200
company_codestring
max length 50
primary_admin_contact_namestring
min length 2, max length 100
primary_admin_contact_emailstring (email)
primary_admin_contact_phonestring
enabled_products"after-call-copilot" | "first-alert-copilot" | "insights-hub"[]Full replacement.
min items 1
verticalstringFree text label.
max length 100
addressstring
max length 500
mfa_enforcedbooleanMust be a JSON boolean.
Example
{
  "mfa_enforced": false,
  "vertical": "Auto dealership",
  "address": "100 River Rd, Springfield, IL 62701"
}

Responses

StatusMeaning
200Updated company.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.type"company"
data.attributesobject
data.attributes.idstring (uuid)
data.attributes.reseller_idstring (uuid)
data.attributes.reseller_namestringEmpty in the create response.
data.attributes.company_namestring
data.attributes.company_codestring | null
data.attributes.verticalstring | null
data.attributes.addressstring | null
data.attributes.primary_admin_contact_namestring
data.attributes.primary_admin_contact_emailstring (email)
data.attributes.primary_admin_contact_phonestring
data.attributes.enabled_products"after-call-copilot" | "first-alert-copilot" | "insights-hub"[]
data.attributes.is_activeboolean
data.attributes.mfa_enforcedboolean
data.attributes.mfa_availablebooleanSingle read only.
data.attributes.location_countintegerCorrect on list rows; 0 on single reads.
data.attributes.user_countintegerCorrect on list rows; 0 on single reads.
data.attributes.created_atstring (date-time)
data.attributes.updated_atstring (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

NameInTypeDescription
companyId requiredpathstring (uuid)

Responses

StatusMeaning
200Deactivated (is_active: false).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
409Conflict (duplicate name or email, already active or inactive). Read the message.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.type"company"
data.attributesobject
data.attributes.idstring (uuid)
data.attributes.reseller_idstring (uuid)
data.attributes.reseller_namestringEmpty in the create response.
data.attributes.company_namestring
data.attributes.company_codestring | null
data.attributes.verticalstring | null
data.attributes.addressstring | null
data.attributes.primary_admin_contact_namestring
data.attributes.primary_admin_contact_emailstring (email)
data.attributes.primary_admin_contact_phonestring
data.attributes.enabled_products"after-call-copilot" | "first-alert-copilot" | "insights-hub"[]
data.attributes.is_activeboolean
data.attributes.mfa_enforcedboolean
data.attributes.mfa_availablebooleanSingle read only.
data.attributes.location_countintegerCorrect on list rows; 0 on single reads.
data.attributes.user_countintegerCorrect on list rows; 0 on single reads.
data.attributes.created_atstring (date-time)
data.attributes.updated_atstring (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

NameInTypeDescription
companyId requiredpathstring (uuid)

Responses

StatusMeaning
200Reactivated.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
409Conflict (duplicate name or email, already active or inactive). Read the message.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.type"company"
data.attributesobject
data.attributes.idstring (uuid)
data.attributes.reseller_idstring (uuid)
data.attributes.reseller_namestringEmpty in the create response.
data.attributes.company_namestring
data.attributes.company_codestring | null
data.attributes.verticalstring | null
data.attributes.addressstring | null
data.attributes.primary_admin_contact_namestring
data.attributes.primary_admin_contact_emailstring (email)
data.attributes.primary_admin_contact_phonestring
data.attributes.enabled_products"after-call-copilot" | "first-alert-copilot" | "insights-hub"[]
data.attributes.is_activeboolean
data.attributes.mfa_enforcedboolean
data.attributes.mfa_availablebooleanSingle read only.
data.attributes.location_countintegerCorrect on list rows; 0 on single reads.
data.attributes.user_countintegerCorrect on list rows; 0 on single reads.
data.attributes.created_atstring (date-time)
data.attributes.updated_atstring (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

NameInTypeDescription
companyId requiredpathstring (uuid)

Responses

StatusMeaning
200The company's security settings.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
403This login's role cannot do this (FORBIDDEN).
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.min_password_lengthintegerMinimum password length.
data.require_uppercaseboolean
data.require_numbersboolean
data.require_special_charsboolean
data.password_expiry_daysinteger | nullDays until a password expires; null when passwords don't expire.
data.session_timeout_minutesintegerIdle minutes before a web sign-in ends.
data.allowed_ip_rangesstring[]CIDR ranges allowed to sign in. Empty means any address.
data.password_policy_sourcestringreseller when the policy is inherited from the reseller, otherwise company.
data.password_policy_inherited_fieldsstring[]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

NameInTypeDescription
companyId requiredpathstring (uuid)

Responses

StatusMeaning
200Company branding.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.type"company_branding"
data.attributesobject
data.attributes.company_idstring (uuid)
data.attributes.display_namestring | null
data.attributes.primary_accent_colorstring | null
data.attributes.secondary_accent_colorstring | null
data.attributes.support_emailstring | null
data.attributes.privacy_policy_urlstring | null
data.attributes.terms_of_service_urlstring | null
data.attributes.copyright_textstring | null
data.attributes.company_logo_urlstring | nullSet in the Admin UI
data.attributes.favicon_urlstring | nullSet in the Admin UI
data.attributes.email_header_logo_urlstring | nullSet in the Admin UI
data.attributes.created_atstring (date-time) | null
data.attributes.updated_atstring (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

NameInTypeDescription
companyId requiredpathstring (uuid)

Request body

FieldTypeDescription
display_namestring
max length 200
primary_accent_colorstring
pattern ^#[0-9A-Fa-f]{6}$
secondary_accent_colorstring
pattern ^#[0-9A-Fa-f]{6}$
support_emailstring (email)
max length 255
privacy_policy_urlstring (uri)
max length 2048
terms_of_service_urlstring (uri)
max length 2048
copyright_textstring
max length 500
Example
{
  "display_name": "Riverbend Insights",
  "primary_accent_color": "#0B5D3B"
}

Responses

StatusMeaning
200Updated.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.type"company_branding"
data.attributesobject
data.attributes.company_idstring (uuid)
data.attributes.display_namestring | null
data.attributes.primary_accent_colorstring | null
data.attributes.secondary_accent_colorstring | null
data.attributes.support_emailstring | null
data.attributes.privacy_policy_urlstring | null
data.attributes.terms_of_service_urlstring | null
data.attributes.copyright_textstring | null
data.attributes.company_logo_urlstring | nullSet in the Admin UI
data.attributes.favicon_urlstring | nullSet in the Admin UI
data.attributes.email_header_logo_urlstring | nullSet in the Admin UI
data.attributes.created_atstring (date-time) | null
data.attributes.updated_atstring (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

NameInTypeDescription
companyId requiredpathstring (uuid)

Responses

StatusMeaning
200Domains.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject[]
data[].idstring (uuid)
data[].domainstring
data[].statusstringpending until the TXT record is found, then verified.
data[].verificationobject
data[].verification.type"TXT"
data[].verification.namestringRecord name, _ic-verify.<domain>.
data[].verification.valuestring
data[].verified_atstring (date-time) | null
data[].last_checked_atstring (date-time) | null
data[].last_failure_reasonstring | 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

NameInTypeDescription
companyId requiredpathstring (uuid)

Request body

FieldTypeDescription
domain requiredstring
max length 253
Example
{
  "domain": "riverbendauto.example.com"
}

Responses

StatusMeaning
200Already claimed. Same record.
201Claimed. Pending verification.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
409Conflict (duplicate name or email, already active or inactive). Read the message.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.idstring (uuid)
data.domainstring
data.statusstringpending until the TXT record is found, then verified.
data.verificationobject
data.verification.type"TXT"
data.verification.namestringRecord name, _ic-verify.<domain>.
data.verification.valuestring
data.verified_atstring (date-time) | null
data.last_checked_atstring (date-time) | null
data.last_failure_reasonstring | 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

NameInTypeDescription
companyId requiredpathstring (uuid)
domainId requiredpathstring (uuid)

Responses

StatusMeaning
204Removed.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily 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

NameInTypeDescription
companyId requiredpathstring (uuid)
domainId requiredpathstring (uuid)

Responses

StatusMeaning
200History, newest first.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject[]
data[].checked_atstring (date-time)
data[].statusstring
data[].failure_reasonstring | 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

NameInTypeDescription
companyId requiredpathstring (uuid)
domainId requiredpathstring (uuid)

Responses

StatusMeaning
200Check result.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.checked_atstring (date-time)
data.statusstring
data.failure_reasonstring | 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

NameInTypeDescription
companyId requiredpathstring (uuid)

Responses

StatusMeaning
200The connection. The client secret is never returned.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.idstring (uuid)
data.display_namestring
data.typestring
data.is_activeboolean
data.issuerstring
data.well_known_endpointstring
data.client_idstring
data.client_auth_methodstring
data.supported_client_auth_methodsstring[]
data.secret_heldboolean
data.link_callback_uristringThe reply URL the customer registers with its provider.
data.instructionsstring[]Steps for the customer's IdP admin.
data.created_atstring (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

NameInTypeDescription
companyId requiredpathstring (uuid)

Request body

FieldTypeDescription
type required"oidc"OpenID Connect only.
display_name requiredstring
max length 200
issuer requiredstring
well_known_endpoint requiredstring (uri)Full HTTPS address of the provider's /.well-known/openid-configuration.
client_id requiredstring
client_auth_method"client_secret" | "none"none for a public client (PKCE only).
default "client_secret"
client_secretstring (password)Required with client_secret. Write-only.
secret_expires_atstring (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

StatusMeaning
201Connected.
400invalid_request, acknowledgement_required or unsafe_endpoint.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
409already_connected or issuer_already_in_use.
422no_verified_domain.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
201 response fields
FieldTypeDescription
dataobject
data.idstring (uuid)
data.display_namestring
data.typestring
data.is_activeboolean
data.issuerstring
data.well_known_endpointstring
data.client_idstring
data.client_auth_methodstring
data.supported_client_auth_methodsstring[]
data.secret_heldboolean
data.link_callback_uristringThe reply URL the customer registers with its provider.
data.instructionsstring[]Steps for the customer's IdP admin.
data.created_atstring (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

NameInTypeDescription
companyId requiredpathstring (uuid)

Responses

StatusMeaning
204Disconnected.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily 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

NameInTypeDescription
companyId requiredpathstring (uuid)

Responses

StatusMeaning
200Test result.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.reachableboolean
data.checksobject[]
data.checks[].namestring
data.checks[].outcomestring
data.checks[].detailstring
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

StatusMeaning
200Product catalogue.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject[]
data[].key"after-call-copilot" | "first-alert-copilot" | "insights-hub"
data[].namestring
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

NameInTypeDescription
companyId requiredpathstring (uuid)

Responses

StatusMeaning
200Each product and whether it is on.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject[]
data[].product_key"after-call-copilot" | "first-alert-copilot" | "insights-hub"
data[].namestring
data[].enabledboolean
data[].enabled_atstring (date-time) | null
data[].enabled_bystring (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

NameInTypeDescription
companyId requiredpathstring (uuid)
userId requiredpathstring (uuid)

Responses

StatusMeaning
200Each product and whether it is on for the user.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject[]
data[].product_key"after-call-copilot" | "first-alert-copilot" | "insights-hub"
data[].namestring
data[].enabledboolean
data[].enabled_atstring (date-time) | null
data[].enabled_bystring (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

NameInTypeDescription
locationId requiredpathstring (uuid)
userId requiredpathstring (uuid)
productKey requiredpath"after-call-copilot" | "first-alert-copilot" | "insights-hub"

Responses

StatusMeaning
200Product state.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
409Conflict (duplicate name or email, already active or inactive). Read the message.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.product_key"after-call-copilot" | "first-alert-copilot" | "insights-hub"
data.namestring
data.enabledboolean
data.enabled_atstring (date-time) | null
data.enabled_bystring (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

NameInTypeDescription
locationId requiredpathstring (uuid)
userId requiredpathstring (uuid)
productKey requiredpath"after-call-copilot" | "first-alert-copilot" | "insights-hub"

Responses

StatusMeaning
200Product state.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.product_key"after-call-copilot" | "first-alert-copilot" | "insights-hub"
data.namestring
data.enabledboolean
data.enabled_atstring (date-time) | null
data.enabled_bystring (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

StatusMeaning
200Industries.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject[]
data[].idstring (uuid)
data[].keystring
data[].namestring
data[].descriptionstring
data[].is_activeboolean
data[].display_orderinteger
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

NameInTypeDescription
companyId requiredpathstring (uuid)
searchquerystring

Case-insensitive substring match on location_name.

is_activequeryboolean
limitqueryinteger

Page size. Send 100 and follow next_cursor.


min 1, max 100, default 20
cursorquerystring

Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400.

offsetqueryinteger

Rows to skip. Prefer cursor.


min 0

Responses

StatusMeaning
200One page of locations.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject[]
data[].type"location"
data[].attributesobject
data[].attributes.idstring (uuid)
data[].attributes.company_idstring (uuid)
data[].attributes.company_namestring
data[].attributes.reseller_namestring
data[].attributes.location_namestring
data[].attributes.streetstring
data[].attributes.citystring
data[].attributes.statestring
data[].attributes.countrystring
data[].attributes.zipcodestring
data[].attributes.support_contact_namestring
data[].attributes.support_contact_emailstring
data[].attributes.support_contact_phonestring
data[].attributes.vertical_idstring (uuid)
data[].attributes.vertical_namestring
data[].attributes.enabled_products"after-call-copilot" | "first-alert-copilot" | "insights-hub"[]
data[].attributes.is_activeboolean
data[].attributes.user_countintegerOn list rows.
data[].attributes.created_atstring (date-time)
data[].attributes.updated_atstring (date-time)
paginationobject
pagination.has_moreboolean
pagination.next_cursorstring | null
pagination.total_countinteger
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

NameInTypeDescription
companyId requiredpathstring (uuid)

Request body

FieldTypeDescription
location_name requiredstringUnique within the company.
min length 2, max length 200
street requiredstring
min length 1, max length 200
city requiredstring
min length 1, max length 100
state requiredstring
min length 1, max length 100
country requiredstring
min length 1, max length 100
zipcode requiredstring
min length 1, max length 20
vertical_id requiredstring (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

StatusMeaning
201Created. Name fields (company_name, reseller_name, vertical_name) are empty here; GET fills them.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Unknown vertical_id, or company not found.
409Conflict (duplicate name or email, already active or inactive). Read the message.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
201 response fields
FieldTypeDescription
dataobject
data.type"location"
data.attributesobject
data.attributes.idstring (uuid)
data.attributes.company_idstring (uuid)
data.attributes.company_namestring
data.attributes.reseller_namestring
data.attributes.location_namestring
data.attributes.streetstring
data.attributes.citystring
data.attributes.statestring
data.attributes.countrystring
data.attributes.zipcodestring
data.attributes.support_contact_namestring
data.attributes.support_contact_emailstring
data.attributes.support_contact_phonestring
data.attributes.vertical_idstring (uuid)
data.attributes.vertical_namestring
data.attributes.enabled_products"after-call-copilot" | "first-alert-copilot" | "insights-hub"[]
data.attributes.is_activeboolean
data.attributes.user_countintegerOn list rows.
data.attributes.created_atstring (date-time)
data.attributes.updated_atstring (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

NameInTypeDescription
companyId requiredpathstring (uuid)
locationId requiredpathstring (uuid)

Responses

StatusMeaning
200The location.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.type"location"
data.attributesobject
data.attributes.idstring (uuid)
data.attributes.company_idstring (uuid)
data.attributes.company_namestring
data.attributes.reseller_namestring
data.attributes.location_namestring
data.attributes.streetstring
data.attributes.citystring
data.attributes.statestring
data.attributes.countrystring
data.attributes.zipcodestring
data.attributes.support_contact_namestring
data.attributes.support_contact_emailstring
data.attributes.support_contact_phonestring
data.attributes.vertical_idstring (uuid)
data.attributes.vertical_namestring
data.attributes.enabled_products"after-call-copilot" | "first-alert-copilot" | "insights-hub"[]
data.attributes.is_activeboolean
data.attributes.user_countintegerOn list rows.
data.attributes.created_atstring (date-time)
data.attributes.updated_atstring (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

NameInTypeDescription
companyId requiredpathstring (uuid)
locationId requiredpathstring (uuid)

Request body

FieldTypeDescription
location_namestring
min length 2, max length 200
streetstring
max length 200
citystring
max length 100
statestring
max length 100
countrystring
max length 100
zipcodestring
max length 20
vertical_idstring (uuid)
enabled_products"after-call-copilot" | "first-alert-copilot" | "insights-hub"[]Full replacement.
Example
{
  "location_name": "Riverbend - Service Department"
}

Responses

StatusMeaning
200Updated.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
409Conflict (duplicate name or email, already active or inactive). Read the message.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.type"location"
data.attributesobject
data.attributes.idstring (uuid)
data.attributes.company_idstring (uuid)
data.attributes.company_namestring
data.attributes.reseller_namestring
data.attributes.location_namestring
data.attributes.streetstring
data.attributes.citystring
data.attributes.statestring
data.attributes.countrystring
data.attributes.zipcodestring
data.attributes.support_contact_namestring
data.attributes.support_contact_emailstring
data.attributes.support_contact_phonestring
data.attributes.vertical_idstring (uuid)
data.attributes.vertical_namestring
data.attributes.enabled_products"after-call-copilot" | "first-alert-copilot" | "insights-hub"[]
data.attributes.is_activeboolean
data.attributes.user_countintegerOn list rows.
data.attributes.created_atstring (date-time)
data.attributes.updated_atstring (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

NameInTypeDescription
companyId requiredpathstring (uuid)
locationId requiredpathstring (uuid)

Responses

StatusMeaning
200Deactivated.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
409Conflict (duplicate name or email, already active or inactive). Read the message.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.type"location"
data.attributesobject
data.attributes.idstring (uuid)
data.attributes.company_idstring (uuid)
data.attributes.company_namestring
data.attributes.reseller_namestring
data.attributes.location_namestring
data.attributes.streetstring
data.attributes.citystring
data.attributes.statestring
data.attributes.countrystring
data.attributes.zipcodestring
data.attributes.support_contact_namestring
data.attributes.support_contact_emailstring
data.attributes.support_contact_phonestring
data.attributes.vertical_idstring (uuid)
data.attributes.vertical_namestring
data.attributes.enabled_products"after-call-copilot" | "first-alert-copilot" | "insights-hub"[]
data.attributes.is_activeboolean
data.attributes.user_countintegerOn list rows.
data.attributes.created_atstring (date-time)
data.attributes.updated_atstring (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

NameInTypeDescription
companyId requiredpathstring (uuid)
locationId requiredpathstring (uuid)

Responses

StatusMeaning
200Reactivated.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
409Conflict (duplicate name or email, already active or inactive). Read the message.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.type"location"
data.attributesobject
data.attributes.idstring (uuid)
data.attributes.company_idstring (uuid)
data.attributes.company_namestring
data.attributes.reseller_namestring
data.attributes.location_namestring
data.attributes.streetstring
data.attributes.citystring
data.attributes.statestring
data.attributes.countrystring
data.attributes.zipcodestring
data.attributes.support_contact_namestring
data.attributes.support_contact_emailstring
data.attributes.support_contact_phonestring
data.attributes.vertical_idstring (uuid)
data.attributes.vertical_namestring
data.attributes.enabled_products"after-call-copilot" | "first-alert-copilot" | "insights-hub"[]
data.attributes.is_activeboolean
data.attributes.user_countintegerOn list rows.
data.attributes.created_atstring (date-time)
data.attributes.updated_atstring (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

NameInTypeDescription
locationId requiredpathstring (uuid)
searchquerystring

Case-insensitive substring match on group_name.

limitqueryinteger

Page size. Send 100 and follow next_cursor.


min 1, max 100, default 20
cursorquerystring

Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400.

Responses

StatusMeaning
200One page of groups.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject[]
data[].type"user_group"
data[].attributesobject
data[].attributes.idstring (uuid)
data[].attributes.location_idstring (uuid)
data[].attributes.group_namestring
data[].attributes.user_countinteger
data[].attributes.membersobject[]On single reads.
data[].attributes.members[].idstring (uuid)
data[].attributes.members[].emailstring (email)
data[].attributes.members[].first_namestring
data[].attributes.members[].last_namestring
data[].attributes.members[].display_namestring
data[].attributes.created_atstring (date-time)
data[].attributes.updated_atstring (date-time)
paginationobject
pagination.has_moreboolean
pagination.next_cursorstring | null
pagination.total_countinteger
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

NameInTypeDescription
locationId requiredpathstring (uuid)

Request body

FieldTypeDescription
group_name requiredstring
min length 2, max length 200
member_idsstring (uuid)[]Users assigned to this location.
Example
{
  "group_name": "Upset Customers"
}

Responses

StatusMeaning
201Created.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
409Conflict (duplicate name or email, already active or inactive). Read the message.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
201 response fields
FieldTypeDescription
dataobject
data.type"user_group"
data.attributesobject
data.attributes.idstring (uuid)
data.attributes.location_idstring (uuid)
data.attributes.group_namestring
data.attributes.user_countinteger
data.attributes.membersobject[]On single reads.
data.attributes.members[].idstring (uuid)
data.attributes.members[].emailstring (email)
data.attributes.members[].first_namestring
data.attributes.members[].last_namestring
data.attributes.members[].display_namestring
data.attributes.created_atstring (date-time)
data.attributes.updated_atstring (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

NameInTypeDescription
locationId requiredpathstring (uuid)
groupId requiredpathstring (uuid)

Responses

StatusMeaning
200The group and members[].
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.type"user_group"
data.attributesobject
data.attributes.idstring (uuid)
data.attributes.location_idstring (uuid)
data.attributes.group_namestring
data.attributes.user_countinteger
data.attributes.membersobject[]On single reads.
data.attributes.members[].idstring (uuid)
data.attributes.members[].emailstring (email)
data.attributes.members[].first_namestring
data.attributes.members[].last_namestring
data.attributes.members[].display_namestring
data.attributes.created_atstring (date-time)
data.attributes.updated_atstring (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

NameInTypeDescription
locationId requiredpathstring (uuid)
groupId requiredpathstring (uuid)

Request body

FieldTypeDescription
group_namestring
min length 2, max length 200
member_idsstring (uuid)[]
Example
{
  "member_ids": [
    "0193b6c2-7c45-7d12-a3f9-8e2b6c1d4f56"
  ]
}

Responses

StatusMeaning
200Updated.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
409Conflict (duplicate name or email, already active or inactive). Read the message.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.type"user_group"
data.attributesobject
data.attributes.idstring (uuid)
data.attributes.location_idstring (uuid)
data.attributes.group_namestring
data.attributes.user_countinteger
data.attributes.membersobject[]On single reads.
data.attributes.members[].idstring (uuid)
data.attributes.members[].emailstring (email)
data.attributes.members[].first_namestring
data.attributes.members[].last_namestring
data.attributes.members[].display_namestring
data.attributes.created_atstring (date-time)
data.attributes.updated_atstring (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

NameInTypeDescription
locationId requiredpathstring (uuid)
groupId requiredpathstring (uuid)
forcequeryboolean

Delete even when alert rules still route to the group.


default false

Responses

StatusMeaning
204Deleted.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
409Conflict (duplicate name or email, already active or inactive). Read the message.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily 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

NameInTypeDescription
locationId requiredpathstring (uuid)
userId requiredpathstring (uuid)

Responses

StatusMeaning
200Groups.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject[]
data[].idstring (uuid)
data[].namestring
data[].is_memberboolean
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

NameInTypeDescription
locationId requiredpathstring (uuid)
userId requiredpathstring (uuid)

Request body

FieldTypeDescription
group_ids requiredstring (uuid)[]
Example
{
  "group_ids": [
    "0193b6c2-8d51-74e0-9b6a-2c7e1f3d5a10",
    "0193b6c2-8d52-74e0-9b6a-2c7e1f3d5a11"
  ]
}

Responses

StatusMeaning
200The user's groups after the change.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject[]
data[].idstring (uuid)
data[].namestring
data[].is_memberboolean
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

StatusMeaning
200Connector types.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject[]
data[].keystring
data[].namestring
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

NameInTypeDescription
locationId requiredpathstring (uuid)

Request body

FieldTypeDescription
type required"netsapiens"
config requiredobject
config.api_url requiredstring (uri)Full API root ending in /ns-api/v2.
config.domain requiredstringThe customer's phone-system domain.
config.api_key requiredstring (password)Read/write key. Write-only; never returned.
connector_idstring (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

StatusMeaning
200Test result.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.successboolean
200 example
{
  "data": {
    "success": true
  }
}
GET /locations/{locationId}/connectors Reseller admin List a location's connectors

Parameters

NameInTypeDescription
locationId requiredpathstring (uuid)
searchquerystring

Substring match on the connector name.

statusquery"connecting" | "active" | "error" | "deactivating" | "inactive"

One status. Invalid values return 400.

limitqueryinteger

Page size. Send 100 and follow next_cursor.


min 1, max 100, default 20
cursorquerystring

Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400.

Responses

StatusMeaning
200One page of connectors.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject[]
data[].idstring (uuid)
data[].location_idstring (uuid)Company list only.
data[].location_namestringCompany list only.
data[].namestring
data[].typestring
data[].type_display_namestring
data[].status"connecting" | "active" | "error" | "deactivating" | "inactive"connecting → active (calls flow) or error. Deactivate: deactivating → inactive. Reactivate: back to connecting.
data[].status_displaystring
data[].status_messagestring | null
data[].state_reasonstring
data[].last_synced_atstring (date-time) | null
data[].created_atstring (date-time)
data[].updated_atstring (date-time)
paginationobject
pagination.has_moreboolean
pagination.next_cursorstring | null
pagination.total_countinteger
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

NameInTypeDescription
locationId requiredpathstring (uuid)

Request body

FieldTypeDescription
name requiredstring
type required"netsapiens"
config requiredobject
config.api_url requiredstring (uri)Full API root ending in /ns-api/v2.
config.domain requiredstringThe customer's phone-system domain.
config.api_key requiredstring (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

StatusMeaning
202Accepted. Connecting in the background.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
409Conflict (duplicate name or email, already active or inactive). Read the message.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
202 response fields
FieldTypeDescription
dataobject
data.idstring (uuid)
data.location_idstring (uuid)
data.namestring
data.typestring
data.type_display_namestring
data.configobjectSettings without the key.
data.config.api_urlstring
data.config.domainstring
data.status"connecting" | "active" | "error" | "deactivating" | "inactive"connecting → active (calls flow) or error. Deactivate: deactivating → inactive. Reactivate: back to connecting.
data.status_displaystring
data.status_messagestring | nullWhat went wrong, when status is error.
data.state_reasonstringWhy the connector is in this status, e.g. invalid_permissions. Omitted when there is none.
data.last_synced_atstring (date-time) | null
data.created_atstring (date-time)
data.updated_atstring (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

NameInTypeDescription
locationId requiredpathstring (uuid)
connectorId requiredpathstring (uuid)

Responses

StatusMeaning
200The connector.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.idstring (uuid)
data.location_idstring (uuid)
data.namestring
data.typestring
data.type_display_namestring
data.configobjectSettings without the key.
data.config.api_urlstring
data.config.domainstring
data.status"connecting" | "active" | "error" | "deactivating" | "inactive"connecting → active (calls flow) or error. Deactivate: deactivating → inactive. Reactivate: back to connecting.
data.status_displaystring
data.status_messagestring | nullWhat went wrong, when status is error.
data.state_reasonstringWhy the connector is in this status, e.g. invalid_permissions. Omitted when there is none.
data.last_synced_atstring (date-time) | null
data.created_atstring (date-time)
data.updated_atstring (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

NameInTypeDescription
locationId requiredpathstring (uuid)
connectorId requiredpathstring (uuid)

Request body

FieldTypeDescription
namestring
configobject
config.api_url requiredstring (uri)Full API root ending in /ns-api/v2.
config.domain requiredstringThe customer's phone-system domain.
config.api_key requiredstring (password)Read/write key. Write-only; never returned.
Example
{
  "name": "Riverbend phone system (main)"
}

Responses

StatusMeaning
200Updated.
202Accepted. Reconnecting in the background.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.idstring (uuid)
data.location_idstring (uuid)
data.namestring
data.typestring
data.type_display_namestring
data.configobjectSettings without the key.
data.config.api_urlstring
data.config.domainstring
data.status"connecting" | "active" | "error" | "deactivating" | "inactive"connecting → active (calls flow) or error. Deactivate: deactivating → inactive. Reactivate: back to connecting.
data.status_displaystring
data.status_messagestring | nullWhat went wrong, when status is error.
data.state_reasonstringWhy the connector is in this status, e.g. invalid_permissions. Omitted when there is none.
data.last_synced_atstring (date-time) | null
data.created_atstring (date-time)
data.updated_atstring (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

NameInTypeDescription
locationId requiredpathstring (uuid)
connectorId requiredpathstring (uuid)

Responses

StatusMeaning
202Stopping.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
409Conflict (duplicate name or email, already active or inactive). Read the message.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
202 response fields
FieldTypeDescription
dataobject
data.idstring (uuid)
data.location_idstring (uuid)
data.namestring
data.typestring
data.type_display_namestring
data.configobjectSettings without the key.
data.config.api_urlstring
data.config.domainstring
data.status"connecting" | "active" | "error" | "deactivating" | "inactive"connecting → active (calls flow) or error. Deactivate: deactivating → inactive. Reactivate: back to connecting.
data.status_displaystring
data.status_messagestring | nullWhat went wrong, when status is error.
data.state_reasonstringWhy the connector is in this status, e.g. invalid_permissions. Omitted when there is none.
data.last_synced_atstring (date-time) | null
data.created_atstring (date-time)
data.updated_atstring (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

NameInTypeDescription
locationId requiredpathstring (uuid)
connectorId requiredpathstring (uuid)

Responses

StatusMeaning
202Restarting.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
409Conflict (duplicate name or email, already active or inactive). Read the message.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
202 response fields
FieldTypeDescription
dataobject
data.idstring (uuid)
data.location_idstring (uuid)
data.namestring
data.typestring
data.type_display_namestring
data.configobjectSettings without the key.
data.config.api_urlstring
data.config.domainstring
data.status"connecting" | "active" | "error" | "deactivating" | "inactive"connecting → active (calls flow) or error. Deactivate: deactivating → inactive. Reactivate: back to connecting.
data.status_displaystring
data.status_messagestring | nullWhat went wrong, when status is error.
data.state_reasonstringWhy the connector is in this status, e.g. invalid_permissions. Omitted when there is none.
data.last_synced_atstring (date-time) | null
data.created_atstring (date-time)
data.updated_atstring (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

NameInTypeDescription
companyId requiredpathstring (uuid)
searchquerystring

Substring match on the connector name.

statusquery"connecting" | "active" | "error" | "deactivating" | "inactive"

connecting → active (calls flow) or error. Deactivate: deactivating → inactive. Reactivate: back to connecting.

typequery"netsapiens"

Connector type key. Invalid values return 400.

limitqueryinteger

Page size. Send 100 and follow next_cursor.


min 1, max 100, default 20
cursorquerystring

Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400.

Responses

StatusMeaning
200One page of connectors.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject[]
data[].idstring (uuid)
data[].location_idstring (uuid)Company list only.
data[].location_namestringCompany list only.
data[].namestring
data[].typestring
data[].type_display_namestring
data[].status"connecting" | "active" | "error" | "deactivating" | "inactive"connecting → active (calls flow) or error. Deactivate: deactivating → inactive. Reactivate: back to connecting.
data[].status_displaystring
data[].status_messagestring | null
data[].state_reasonstring
data[].last_synced_atstring (date-time) | null
data[].created_atstring (date-time)
data[].updated_atstring (date-time)
paginationobject
pagination.has_moreboolean
pagination.next_cursorstring | null
pagination.total_countinteger
errorsobject[]Connectors in error.
errors[].idstring (uuid)
errors[].namestring
errors[].typestring
errors[].location_namestring
errors[].status_messagestring | 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

NameInTypeDescription
locationId requiredpathstring (uuid)
limitqueryinteger
min 1, max 100, default 25
cursorquerystring

Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400.

Responses

StatusMeaning
200One page of rules.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject[]
data[].type"first_alert_rule"
data[].attributesobject
data[].attributes.idstring (uuid)
data[].attributes.location_idstring (uuid)
data[].attributes.namestring
data[].attributes.priority"critical" | "high" | "medium" | "low"
data[].attributes.match_logicstring
data[].attributes.enabledboolean
data[].attributes.is_defaultbooleanA platform default rule (can't be deleted).
data[].attributes.triggersobject[]Single reads.
data[].attributes.triggers[].idstring (uuid)In responses.
data[].attributes.triggers[].trigger_type required"sentiment" | "keyword_match" | "conversation_topic"
data[].attributes.triggers[].config requiredobject | object | object
data[].attributes.trigger_typesstring[]List rows.
data[].attributes.groupsobject[]
data[].attributes.groups[].idstring (uuid)
data[].attributes.groups[].group_namestring
data[].attributes.created_atstring (date-time)
data[].attributes.updated_atstring (date-time)
paginationobject
pagination.has_moreboolean
pagination.next_cursorstring | null
pagination.total_countinteger
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

NameInTypeDescription
locationId requiredpathstring (uuid)

Request body

FieldTypeDescription
name requiredstring
min length 1, max length 200
priority required"critical" | "high" | "medium" | "low"
match_logic"any" | "all"How the rule's triggers combine.
default "any"
enabledboolean
triggers requiredobject[]
min items 1
triggers[].idstring (uuid)In responses.
triggers[].trigger_type required"sentiment" | "keyword_match" | "conversation_topic"
triggers[].config requiredobject | object | object
group_idsstring (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

StatusMeaning
201Created.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
409Conflict (duplicate name or email, already active or inactive). Read the message.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
201 response fields
FieldTypeDescription
dataobject
data.type"first_alert_rule"
data.attributesobject
data.attributes.idstring (uuid)
data.attributes.location_idstring (uuid)
data.attributes.namestring
data.attributes.priority"critical" | "high" | "medium" | "low"
data.attributes.match_logicstring
data.attributes.enabledboolean
data.attributes.is_defaultbooleanA platform default rule (can't be deleted).
data.attributes.triggersobject[]Single reads.
data.attributes.triggers[].idstring (uuid)In responses.
data.attributes.triggers[].trigger_type required"sentiment" | "keyword_match" | "conversation_topic"
data.attributes.triggers[].config requiredobject | object | object
data.attributes.trigger_typesstring[]List rows.
data.attributes.groupsobject[]
data.attributes.groups[].idstring (uuid)
data.attributes.groups[].group_namestring
data.attributes.created_atstring (date-time)
data.attributes.updated_atstring (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

NameInTypeDescription
locationId requiredpathstring (uuid)
ruleId requiredpathstring (uuid)

Responses

StatusMeaning
200The full rule.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.type"first_alert_rule"
data.attributesobject
data.attributes.idstring (uuid)
data.attributes.location_idstring (uuid)
data.attributes.namestring
data.attributes.priority"critical" | "high" | "medium" | "low"
data.attributes.match_logicstring
data.attributes.enabledboolean
data.attributes.is_defaultbooleanA platform default rule (can't be deleted).
data.attributes.triggersobject[]Single reads.
data.attributes.triggers[].idstring (uuid)In responses.
data.attributes.triggers[].trigger_type required"sentiment" | "keyword_match" | "conversation_topic"
data.attributes.triggers[].config requiredobject | object | object
data.attributes.trigger_typesstring[]List rows.
data.attributes.groupsobject[]
data.attributes.groups[].idstring (uuid)
data.attributes.groups[].group_namestring
data.attributes.created_atstring (date-time)
data.attributes.updated_atstring (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

NameInTypeDescription
locationId requiredpathstring (uuid)
ruleId requiredpathstring (uuid)

Request body

FieldTypeDescription
namestring
min length 1, max length 200
priority"critical" | "high" | "medium" | "low"
match_logic"any" | "all"
enabledboolean
triggersobject[]Replaces every trigger.
min items 1
triggers[].idstring (uuid)In responses.
triggers[].trigger_type required"sentiment" | "keyword_match" | "conversation_topic"
triggers[].config requiredobject | object | object
group_idsstring (uuid)[]Replaces the groups. [] clears.
Example
{
  "enabled": true
}

Responses

StatusMeaning
200Updated.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
409Conflict (duplicate name or email, already active or inactive). Read the message.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.type"first_alert_rule"
data.attributesobject
data.attributes.idstring (uuid)
data.attributes.location_idstring (uuid)
data.attributes.namestring
data.attributes.priority"critical" | "high" | "medium" | "low"
data.attributes.match_logicstring
data.attributes.enabledboolean
data.attributes.is_defaultbooleanA platform default rule (can't be deleted).
data.attributes.triggersobject[]Single reads.
data.attributes.triggers[].idstring (uuid)In responses.
data.attributes.triggers[].trigger_type required"sentiment" | "keyword_match" | "conversation_topic"
data.attributes.triggers[].config requiredobject | object | object
data.attributes.trigger_typesstring[]List rows.
data.attributes.groupsobject[]
data.attributes.groups[].idstring (uuid)
data.attributes.groups[].group_namestring
data.attributes.created_atstring (date-time)
data.attributes.updated_atstring (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

NameInTypeDescription
locationId requiredpathstring (uuid)
ruleId requiredpathstring (uuid)

Responses

StatusMeaning
204Deleted.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
409Conflict (duplicate name or email, already active or inactive). Read the message.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily 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

NameInTypeDescription
locationId requiredpathstring (uuid)
ruleId requiredpathstring (uuid)

Responses

StatusMeaning
201The copy.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
409Conflict (duplicate name or email, already active or inactive). Read the message.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
201 response fields
FieldTypeDescription
dataobject
data.type"first_alert_rule"
data.attributesobject
data.attributes.idstring (uuid)
data.attributes.location_idstring (uuid)
data.attributes.namestring
data.attributes.priority"critical" | "high" | "medium" | "low"
data.attributes.match_logicstring
data.attributes.enabledboolean
data.attributes.is_defaultbooleanA platform default rule (can't be deleted).
data.attributes.triggersobject[]Single reads.
data.attributes.triggers[].idstring (uuid)In responses.
data.attributes.triggers[].trigger_type required"sentiment" | "keyword_match" | "conversation_topic"
data.attributes.triggers[].config requiredobject | object | object
data.attributes.trigger_typesstring[]List rows.
data.attributes.groupsobject[]
data.attributes.groups[].idstring (uuid)
data.attributes.groups[].group_namestring
data.attributes.created_atstring (date-time)
data.attributes.updated_atstring (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

NameInTypeDescription
locationId requiredpathstring (uuid)

Responses

StatusMeaning
200Location First Alert configuration.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.webhook_urlstring | null
data.connector_mappingsobject[]
data.connector_mappings[].connector_idstring (uuid)
data.connector_mappings[].connector_namestring
data.connector_mappings[].connector_typestring
data.connector_mappings[].monitored_numbersstring[]
data.connector_mappings[].idstring (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

NameInTypeDescription
locationId requiredpathstring (uuid)

Request body

FieldTypeDescription
webhook_urlstring (uri) | nullHTTPS only. Send it on every PUT or it is cleared.
connector_mappings requiredobject[]
connector_mappings[].connector_id requiredstring (uuid)
connector_mappings[].monitored_numbers requiredstring[]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

StatusMeaning
200Saved.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.webhook_urlstring | null
data.connector_mappingsobject[]
data.connector_mappings[].connector_idstring (uuid)
data.connector_mappings[].connector_namestring
data.connector_mappings[].connector_typestring
data.connector_mappings[].monitored_numbersstring[]
data.connector_mappings[].idstring (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

NameInTypeDescription
locationId requiredpathstring (uuid)

Request body

FieldTypeDescription
url requiredstring (uri)
Example
{
  "url": "https://hooks.example.com/riverbend/alerts"
}

Responses

StatusMeaning
200Test result.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.successboolean
data.status_codeintegerHTTP 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

NameInTypeDescription
locationId requiredpathstring (uuid)
userId requiredpathstring (uuid)

Responses

StatusMeaning
200Preferences.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
emailNotificationsobject
emailNotifications.masterEnabledboolean
emailNotifications.alertsobject[]
emailNotifications.alerts[].alertIdstring (uuid)
emailNotifications.alerts[].alertNamestring
emailNotifications.alerts[].triggerstringReadable summary of the rule's triggers.
emailNotifications.alerts[].severitystring
emailNotifications.alerts[].descriptionstring
emailNotifications.alerts[].emailEnabledboolean
digestobject
digest.enabledboolean
digest.frequencystring
digest.sendTimestring
digest.timezonestring
digest.timeFormatstring
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

NameInTypeDescription
locationId requiredpathstring (uuid)
userId requiredpathstring (uuid)

Request body

FieldTypeDescription
masterEnabled requiredboolean
alertsobject[]
alerts[].alertId requiredstring (uuid)Alert rule id.
alerts[].emailEnabled requiredboolean
Example
{
  "masterEnabled": true,
  "alerts": [
    {
      "alertId": "6f1c2e8a-3b4d-4c9e-a7f2-1d5e8b9c0a31",
      "emailEnabled": true
    },
    {
      "alertId": "6f1c2e8a-3b4d-4c9e-a7f2-1d5e8b9c0a32",
      "emailEnabled": true
    }
  ]
}

Responses

StatusMeaning
200The full preferences object.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
emailNotificationsobject
emailNotifications.masterEnabledboolean
emailNotifications.alertsobject[]
emailNotifications.alerts[].alertIdstring (uuid)
emailNotifications.alerts[].alertNamestring
emailNotifications.alerts[].triggerstringReadable summary of the rule's triggers.
emailNotifications.alerts[].severitystring
emailNotifications.alerts[].descriptionstring
emailNotifications.alerts[].emailEnabledboolean
digestobject
digest.enabledboolean
digest.frequencystring
digest.sendTimestring
digest.timezonestring
digest.timeFormatstring
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

NameInTypeDescription
locationId requiredpathstring (uuid)
userId requiredpathstring (uuid)

Request body

FieldTypeDescription
enabled requiredboolean
frequency required"daily" | "weekly" | "both" | "never"
sendTime requiredstring24-hour HH:MM.
pattern ^\d{2}:\d{2}$
timezone requiredstringIANA zone, e.g. America/Chicago.
timeFormat"12h" | "24h"
Example
{
  "enabled": true,
  "frequency": "daily",
  "sendTime": "08:00",
  "timezone": "America/Chicago",
  "timeFormat": "12h"
}

Responses

StatusMeaning
200The full preferences object.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
emailNotificationsobject
emailNotifications.masterEnabledboolean
emailNotifications.alertsobject[]
emailNotifications.alerts[].alertIdstring (uuid)
emailNotifications.alerts[].alertNamestring
emailNotifications.alerts[].triggerstringReadable summary of the rule's triggers.
emailNotifications.alerts[].severitystring
emailNotifications.alerts[].descriptionstring
emailNotifications.alerts[].emailEnabledboolean
digestobject
digest.enabledboolean
digest.frequencystring
digest.sendTimestring
digest.timezonestring
digest.timeFormatstring
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

NameInTypeDescription
locationId requiredpathstring (uuid)

Responses

StatusMeaning
200Numbers covered and groups with access.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.type"insights_hub_setup"
data.attributesobject
data.attributes.connector_mappingsobject[]
data.attributes.connector_mappings[].connector_idstring (uuid)
data.attributes.connector_mappings[].connector_namestring
data.attributes.connector_mappings[].connector_typestring
data.attributes.connector_mappings[].monitored_numbersstring[]
data.attributes.group_accessstring (uuid)[]
data.attributes.available_connectorsobject[]
data.attributes.available_connectors[].idstring (uuid)
data.attributes.available_connectors[].namestring
data.attributes.available_connectors[].typestring
data.attributes.groupsobject[]
data.attributes.groups[].idstring (uuid)
data.attributes.groups[].group_namestring
data.attributes.groups[].has_accessboolean
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

NameInTypeDescription
locationId requiredpathstring (uuid)

Request body

FieldTypeDescription
connector_mappings requiredobject[]
connector_mappings[].connector_id requiredstring (uuid)
connector_mappings[].monitored_numbers requiredstring[]Extensions or DIDs, as the phone system shows them.
group_access requiredstring (uuid)[]
Example
{
  "connector_mappings": [
    {
      "connector_id": "4b7e9d2c-1a3f-4e8b-9c6d-2f5a8e1b3c70",
      "monitored_numbers": [
        "2101",
        "2102",
        "2103"
      ]
    }
  ],
  "group_access": [
    "0193b6c2-8d52-74e0-9b6a-2c7e1f3d5a11"
  ]
}

Responses

StatusMeaning
201Saved.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
201 response fields
FieldTypeDescription
dataobject
data.type"insights_hub_setup"
data.attributesobject
data.attributes.connector_mappingsobject[]
data.attributes.connector_mappings[].connector_idstring (uuid)
data.attributes.connector_mappings[].connector_namestring
data.attributes.connector_mappings[].connector_typestring
data.attributes.connector_mappings[].monitored_numbersstring[]
data.attributes.group_accessstring (uuid)[]
data.attributes.available_connectorsobject[]
data.attributes.available_connectors[].idstring (uuid)
data.attributes.available_connectors[].namestring
data.attributes.available_connectors[].typestring
data.attributes.groupsobject[]
data.attributes.groups[].idstring (uuid)
data.attributes.groups[].group_namestring
data.attributes.groups[].has_accessboolean
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

NameInTypeDescription
locationId requiredpathstring (uuid)

Request body

FieldTypeDescription
connector_mappingsobject[]
connector_mappings[].connector_id requiredstring (uuid)
connector_mappings[].monitored_numbers requiredstring[]Extensions or DIDs, as the phone system shows them.
group_accessstring (uuid)[]
Example
{
  "connector_mappings": [
    {
      "connector_id": "4b7e9d2c-1a3f-4e8b-9c6d-2f5a8e1b3c70",
      "monitored_numbers": [
        "2101",
        "2102",
        "2103",
        "2104"
      ]
    }
  ]
}

Responses

StatusMeaning
200Updated.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.type"insights_hub_setup"
data.attributesobject
data.attributes.connector_mappingsobject[]
data.attributes.connector_mappings[].connector_idstring (uuid)
data.attributes.connector_mappings[].connector_namestring
data.attributes.connector_mappings[].connector_typestring
data.attributes.connector_mappings[].monitored_numbersstring[]
data.attributes.group_accessstring (uuid)[]
data.attributes.available_connectorsobject[]
data.attributes.available_connectors[].idstring (uuid)
data.attributes.available_connectors[].namestring
data.attributes.available_connectors[].typestring
data.attributes.groupsobject[]
data.attributes.groups[].idstring (uuid)
data.attributes.groups[].group_namestring
data.attributes.groups[].has_accessboolean
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

NameInTypeDescription
locationId requiredpathstring (uuid)

Responses

StatusMeaning
200Coverage.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.type"insights_hub_config"
data.attributesobject
data.attributes.monitor_all_numbersboolean
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

NameInTypeDescription
locationId requiredpathstring (uuid)

Request body

FieldTypeDescription
monitor_all_numbers requiredboolean
Example
{
  "monitor_all_numbers": true
}

Responses

StatusMeaning
200Updated.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.type"insights_hub_config"
data.attributesobject
data.attributes.monitor_all_numbersboolean
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

NameInTypeDescription
locationId requiredpathstring (uuid)
userId requiredpathstring (uuid)

Responses

StatusMeaning
200Access state.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.type"insights_hub_access"
data.attributesobject
data.attributes.enabledboolean
data.attributes.group_namestring | 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

NameInTypeDescription
companyId requiredpathstring (uuid)
searchquerystring

Case-insensitive substring match on email, first name or last name (not the full name).

statusquery"invited" | "active" | "deactivated"

Case-insensitive. Invalid values return 422.

rolequery"customer_admin" | "frontline_user"

Invalid values return 422.

location_idquerystring (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
limitqueryinteger

Page size. Invalid values fall back to the default.


min 1, max 100, default 25
cursorquerystring

Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400.

Responses

StatusMeaning
200One page of users.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject[]
data[].type"company_user"
data[].attributesobject
data[].attributes.idstring (uuid)
data[].attributes.company_idstring (uuid)
data[].attributes.reseller_idstring (uuid)
data[].attributes.emailstring (email)
data[].attributes.first_namestring
data[].attributes.last_namestring
data[].attributes.display_namestring
data[].attributes.phone_numberstring
data[].attributes.departmentstring
data[].attributes.status"invited" | "active" | "deactivated"
data[].attributes.role"customer_admin" | "frontline_user"
data[].attributes.auth_method"password" | "sso"
data[].attributes.invited_atstring (date-time) | null
data[].attributes.invite_expires_atstring (date-time) | null
data[].attributes.activated_atstring (date-time) | null
data[].attributes.last_login_atstring (date-time) | null
data[].attributes.locationsobject[]Single reads.
data[].attributes.locations[].location_idstring (uuid)
data[].attributes.locations[].assigned_atstring (date-time)
data[].attributes.created_atstring (date-time)
data[].attributes.updated_atstring (date-time)
paginationobject
pagination.has_moreboolean
pagination.next_cursorstring | null
pagination.total_countinteger
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

NameInTypeDescription
companyId requiredpathstring (uuid)
Idempotency-Key requiredheaderstring

A UUID per logical create. Reuse it when retrying the same create.

Request body

FieldTypeDescription
email requiredstring (email)Unique on the platform.
first_name requiredstring
min length 1, max length 100
last_name requiredstring
min length 1, max length 100
phone_numberstring
max length 50
role required"customer_admin" | "frontline_user"
location_idsstring (uuid)[]Required for frontline_user.
send_invitationbooleanEmail 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

StatusMeaning
201Created, status invited.
400Missing Idempotency-Key (the body is {"error": "<message>"}), or a malformed field.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
409The email is already in use.
422Invalid value (unknown location, role not assignable). The user may still have been created; see above.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
201 response fields
FieldTypeDescription
dataobject
data.type"company_user"
data.attributesobject
data.attributes.idstring (uuid)
data.attributes.company_idstring (uuid)
data.attributes.reseller_idstring (uuid)
data.attributes.emailstring (email)
data.attributes.first_namestring
data.attributes.last_namestring
data.attributes.display_namestring
data.attributes.phone_numberstring
data.attributes.departmentstring
data.attributes.status"invited" | "active" | "deactivated"
data.attributes.role"customer_admin" | "frontline_user"
data.attributes.auth_method"password" | "sso"
data.attributes.invited_atstring (date-time) | null
data.attributes.invite_expires_atstring (date-time) | null
data.attributes.activated_atstring (date-time) | null
data.attributes.last_login_atstring (date-time) | null
data.attributes.locationsobject[]Single reads.
data.attributes.locations[].location_idstring (uuid)
data.attributes.locations[].assigned_atstring (date-time)
data.attributes.created_atstring (date-time)
data.attributes.updated_atstring (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

NameInTypeDescription
companyId requiredpathstring (uuid)
userId requiredpathstring (uuid)

Responses

StatusMeaning
200The user, with locations[].
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.type"company_user"
data.attributesobject
data.attributes.idstring (uuid)
data.attributes.company_idstring (uuid)
data.attributes.reseller_idstring (uuid)
data.attributes.emailstring (email)
data.attributes.first_namestring
data.attributes.last_namestring
data.attributes.display_namestring
data.attributes.phone_numberstring
data.attributes.departmentstring
data.attributes.status"invited" | "active" | "deactivated"
data.attributes.role"customer_admin" | "frontline_user"
data.attributes.auth_method"password" | "sso"
data.attributes.invited_atstring (date-time) | null
data.attributes.invite_expires_atstring (date-time) | null
data.attributes.activated_atstring (date-time) | null
data.attributes.last_login_atstring (date-time) | null
data.attributes.locationsobject[]Single reads.
data.attributes.locations[].location_idstring (uuid)
data.attributes.locations[].assigned_atstring (date-time)
data.attributes.created_atstring (date-time)
data.attributes.updated_atstring (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

NameInTypeDescription
companyId requiredpathstring (uuid)
userId requiredpathstring (uuid)

Request body

FieldTypeDescription
first_namestring
min length 1, max length 100
last_namestring
min length 1, max length 100
phone_numberstring
max length 50
departmentstring
max length 255
role"customer_admin" | "frontline_user"
location_idsstring (uuid)[]Replaces the user's locations.
Example
{
  "location_ids": [
    "0193b6c2-6b29-7a51-b0e4-1c8f3d5e7a02",
    "0193b6c2-6b30-7a51-b0e4-1c8f3d5e7a03"
  ]
}

Responses

StatusMeaning
200Updated.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.type"company_user"
data.attributesobject
data.attributes.idstring (uuid)
data.attributes.company_idstring (uuid)
data.attributes.reseller_idstring (uuid)
data.attributes.emailstring (email)
data.attributes.first_namestring
data.attributes.last_namestring
data.attributes.display_namestring
data.attributes.phone_numberstring
data.attributes.departmentstring
data.attributes.status"invited" | "active" | "deactivated"
data.attributes.role"customer_admin" | "frontline_user"
data.attributes.auth_method"password" | "sso"
data.attributes.invited_atstring (date-time) | null
data.attributes.invite_expires_atstring (date-time) | null
data.attributes.activated_atstring (date-time) | null
data.attributes.last_login_atstring (date-time) | null
data.attributes.locationsobject[]Single reads.
data.attributes.locations[].location_idstring (uuid)
data.attributes.locations[].assigned_atstring (date-time)
data.attributes.created_atstring (date-time)
data.attributes.updated_atstring (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

NameInTypeDescription
companyId requiredpathstring (uuid)
userId requiredpathstring (uuid)

Responses

StatusMeaning
200Deactivated.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
409Conflict (duplicate name or email, already active or inactive). Read the message.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.type"company_user"
data.attributesobject
data.attributes.idstring (uuid)
data.attributes.company_idstring (uuid)
data.attributes.reseller_idstring (uuid)
data.attributes.emailstring (email)
data.attributes.first_namestring
data.attributes.last_namestring
data.attributes.display_namestring
data.attributes.phone_numberstring
data.attributes.departmentstring
data.attributes.status"invited" | "active" | "deactivated"
data.attributes.role"customer_admin" | "frontline_user"
data.attributes.auth_method"password" | "sso"
data.attributes.invited_atstring (date-time) | null
data.attributes.invite_expires_atstring (date-time) | null
data.attributes.activated_atstring (date-time) | null
data.attributes.last_login_atstring (date-time) | null
data.attributes.locationsobject[]Single reads.
data.attributes.locations[].location_idstring (uuid)
data.attributes.locations[].assigned_atstring (date-time)
data.attributes.created_atstring (date-time)
data.attributes.updated_atstring (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

NameInTypeDescription
companyId requiredpathstring (uuid)
userId requiredpathstring (uuid)

Responses

StatusMeaning
200Reactivated.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
409Conflict (duplicate name or email, already active or inactive). Read the message.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.type"company_user"
data.attributesobject
data.attributes.idstring (uuid)
data.attributes.company_idstring (uuid)
data.attributes.reseller_idstring (uuid)
data.attributes.emailstring (email)
data.attributes.first_namestring
data.attributes.last_namestring
data.attributes.display_namestring
data.attributes.phone_numberstring
data.attributes.departmentstring
data.attributes.status"invited" | "active" | "deactivated"
data.attributes.role"customer_admin" | "frontline_user"
data.attributes.auth_method"password" | "sso"
data.attributes.invited_atstring (date-time) | null
data.attributes.invite_expires_atstring (date-time) | null
data.attributes.activated_atstring (date-time) | null
data.attributes.last_login_atstring (date-time) | null
data.attributes.locationsobject[]Single reads.
data.attributes.locations[].location_idstring (uuid)
data.attributes.locations[].assigned_atstring (date-time)
data.attributes.created_atstring (date-time)
data.attributes.updated_atstring (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

NameInTypeDescription
companyId requiredpathstring (uuid)
userId requiredpathstring (uuid)

Responses

StatusMeaning
202Sent.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
409Conflict (duplicate name or email, already active or inactive). Read the message.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
202 response fields
FieldTypeDescription
dataobject
data.type"invitation_resend"
data.attributesobject
data.attributes.user_idstring (uuid)
data.attributes.emailstring (email)
data.attributes.invite_expires_atstring (date-time)
data.attributes.messagestring
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

NameInTypeDescription
companyId requiredpathstring (uuid)
userId requiredpathstring (uuid)

Responses

StatusMeaning
202Reset email sent.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
409Conflict (duplicate name or email, already active or inactive). Read the message.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
202 response fields
FieldTypeDescription
dataobject
data.type"password_reset"
data.attributesobject
data.attributes.user_idstring (uuid)
data.attributes.emailstring (email)
data.attributes.messagestring
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

NameInTypeDescription
companyId requiredpathstring (uuid)
userId requiredpathstring (uuid)

Responses

StatusMeaning
200Mappings.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject[]
data[].connector_idstring (uuid)
data[].connector_namestring
data[].connector_typestring
data[].monitored_numbersstring[]
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

NameInTypeDescription
companyId requiredpathstring (uuid)
userId requiredpathstring (uuid)

Request body

FieldTypeDescription
mappings requiredobject[]
mappings[].connector_id requiredstring (uuid)
mappings[].monitored_numbers requiredstring[]Extensions or DIDs, as the phone system shows them.
Example
{
  "mappings": [
    {
      "connector_id": "4b7e9d2c-1a3f-4e8b-9c6d-2f5a8e1b3c70",
      "monitored_numbers": [
        "2101"
      ]
    }
  ]
}

Responses

StatusMeaning
200Saved.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
409An extension is already monitored at another location.
422Valid shape, invalid value (enum, date order, range, unknown reference).
503The extension check is briefly unavailable. Retry.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject[]
data[].connector_idstring (uuid)
data[].connector_namestring
data[].connector_typestring
data[].monitored_numbersstring[]
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

NameInTypeDescription
locationId requiredpathstring (uuid)
searchquerystring

Case-insensitive substring match on email, first name or last name.

statusquery"invited" | "active" | "deactivated"
limitqueryinteger

Page size. Send 100 and follow next_cursor.


min 1, max 100, default 20
cursorquerystring

Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400.

Responses

StatusMeaning
200One page of users.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject[]
data[].type"location_user"
data[].attributesobject
data[].attributes.idstring (uuid)
data[].attributes.company_idstring (uuid)
data[].attributes.emailstring (email)
data[].attributes.first_namestring
data[].attributes.last_namestring
data[].attributes.display_namestring
data[].attributes.phone_numberstring
data[].attributes.role"customer_admin" | "frontline_user"
data[].attributes.status"invited" | "active" | "deactivated"
data[].attributes.invited_atstring (date-time) | null
data[].attributes.created_atstring (date-time)
data[].attributes.location_idstring (uuid)
data[].attributes.location_namestring
data[].attributes.assigned_atstring (date-time)
data[].attributes.locationsobject[] | null
data[].attributes.locations[].location_idstring (uuid)
data[].attributes.locations[].assigned_atstring (date-time)
data[].attributes.groupsstring[] | nullGroup names. Filled on list rows.
data[].attributes.enabled_products"after-call-copilot" | "first-alert-copilot" | "insights-hub"[] | null
paginationobject
pagination.has_moreboolean
pagination.next_cursorstring | null
pagination.total_countinteger
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

NameInTypeDescription
locationId requiredpathstring (uuid)
userId requiredpathstring (uuid)

Responses

StatusMeaning
200The user.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.type"location_user"
data.attributesobject
data.attributes.idstring (uuid)
data.attributes.company_idstring (uuid)
data.attributes.emailstring (email)
data.attributes.first_namestring
data.attributes.last_namestring
data.attributes.display_namestring
data.attributes.phone_numberstring
data.attributes.role"customer_admin" | "frontline_user"
data.attributes.status"invited" | "active" | "deactivated"
data.attributes.invited_atstring (date-time) | null
data.attributes.created_atstring (date-time)
data.attributes.location_idstring (uuid)
data.attributes.location_namestring
data.attributes.assigned_atstring (date-time)
data.attributes.locationsobject[] | null
data.attributes.locations[].location_idstring (uuid)
data.attributes.locations[].assigned_atstring (date-time)
data.attributes.groupsstring[] | nullGroup 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

NameInTypeDescription
locationId requiredpathstring (uuid)
userId requiredpathstring (uuid)

Responses

StatusMeaning
200Settings and number mappings.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.user_idstring (uuid)
data.eoc_enabledboolean
data.eod_enabledboolean
data.eod_timezonestring | null
data.eod_timestring | null
data.digest_frequencystring
data.digest_time_formatstring
data.connector_mappingsobject[]
data.connector_mappings[].connector_idstring (uuid)
data.connector_mappings[].connector_namestring
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_numbersstring[]
data.last_changed_bystring (uuid) | null
data.last_changed_atstring (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

NameInTypeDescription
locationId requiredpathstring (uuid)
userId requiredpathstring (uuid)

Request body

FieldTypeDescription
eoc_enabledbooleanEmail a summary after each call.
eod_enabledbooleanSend the end-of-day recap.
eod_timestring24-hour HH:MM.
pattern ^\d{2}:\d{2}$
eod_timezonestringIANA zone.
digest_frequency"daily" | "weekly" | "both" | "never"
digest_time_format"12h" | "24h"
connector_mappingsobject[]Replaces the user's numbers. [] clears.
connector_mappings[].connector_id requiredstring (uuid)
connector_mappings[].monitored_numbers requiredstring[]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

StatusMeaning
200Updated.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
409An extension is already monitored at another location.
422CONNECTOR_NOT_VALID, INVALID_EOD_TIME, INVALID_TIMEZONE or INVALID_FREQUENCY.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503The extension check is briefly unavailable. Retry.
200 response fields
FieldTypeDescription
dataobject
data.user_idstring (uuid)
data.eoc_enabledboolean
data.eod_enabledboolean
data.eod_timezonestring | null
data.eod_timestring | null
data.digest_frequencystring
data.digest_time_formatstring
data.connector_mappingsobject[]
data.connector_mappings[].connector_idstring (uuid)
data.connector_mappings[].connector_namestring
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_numbersstring[]
data.last_changed_bystring (uuid) | null
data.last_changed_atstring (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

StatusMeaning
200The signed-in user.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.idstring (uuid)
data.emailstring (email)
data.first_namestring
data.last_namestring
data.display_namestring
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.statusstring
data.scopesstring[]
data.reseller_idstring (uuid) | null
data.company_idstring (uuid) | null
data.location_idsstring (uuid)[] | null
data.enabled_products"after-call-copilot" | "first-alert-copilot" | "insights-hub"[] | null
data.mfa_availableboolean
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

NameInTypeDescription
searchquerystring

Case-insensitive substring match on location_name.

is_activequeryboolean

true or false. Other values return 422.

company_idquerystring (uuid)
limitqueryinteger

Values above 100 are capped.


min 1, max 100, default 20
cursorquerystring

Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400.

offsetqueryinteger

Rows to skip. Prefer cursor.


min 0

Responses

StatusMeaning
200One page of locations.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject[]
data[].type"location"
data[].attributesobject
data[].attributes.idstring (uuid)
data[].attributes.company_idstring (uuid)
data[].attributes.company_namestring
data[].attributes.reseller_namestring
data[].attributes.location_namestring
data[].attributes.streetstring
data[].attributes.citystring
data[].attributes.statestring
data[].attributes.countrystring
data[].attributes.zipcodestring
data[].attributes.support_contact_namestring
data[].attributes.support_contact_emailstring
data[].attributes.support_contact_phonestring
data[].attributes.vertical_idstring (uuid)
data[].attributes.vertical_namestring
data[].attributes.enabled_products"after-call-copilot" | "first-alert-copilot" | "insights-hub"[]
data[].attributes.is_activeboolean
data[].attributes.user_countintegerOn list rows.
data[].attributes.created_atstring (date-time)
data[].attributes.updated_atstring (date-time)
paginationobject
pagination.has_moreboolean
pagination.next_cursorstring | null
pagination.total_countinteger
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

NameInTypeDescription
date_fromquerystring (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_toquerystring (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.

statusquery"completed" | "missed" | "voicemail" | "failed" | "cancelled"

Call outcome. One value, case-sensitive. Invalid values return 422.

sentimentquery"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_tasksquery"true"

Only true is recognised (calls with at least one open task). Any other value is ignored.

multi_legqueryboolean

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_idquerystring (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_idquerystring (uuid)

Narrow to one company.

searchquerystring

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
cursorquerystring

Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400.

limitqueryinteger

Page size. Out-of-range values return 400. Use 100 for exports.


min 1, max 100, default 10

Responses

StatusMeaning
200One page of calls with totals for the whole filter.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.summaryobjectTotals for every call matching the filters (all pages).
data.summary.total_callsinteger
data.summary.completed_callsinteger
data.summary.missed_callsinteger
data.summary.total_durationinteger
data.summary.tasks_doneinteger
data.summary.pendinginteger
data.summary.total_tasksinteger
data.callsobject[]
data.calls[].idstring (uuid)
data.calls[].location_idstring (uuid)
data.calls[].call_datestring (date-time)
data.calls[].caller_timezonestring | null
data.calls[].caller_namestring | null
data.calls[].caller_numberstring | null
data.calls[].callee_namestring | null
data.calls[].callee_numberstring | 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_scoreinteger | null
min -100, max 100
data.calls[].sentiment_labelstring
data.calls[].summarystring | null
data.calls[].top_highlightstring | null
data.calls[].highlightsstring[]
data.calls[].durationintegerSeconds.
data.calls[].leg_countinteger
data.calls[].task_countinteger
data.calls[].completed_task_countinteger
metaobjectPaging for conversation data. Stop when has_more is false.
meta.has_moreboolean
meta.next_cursorstring | null
meta.limitinteger
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

NameInTypeDescription
callId requiredpathstring (uuid)

Call id. Malformed ids return 400.

Responses

StatusMeaning
200The call.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.idstring (uuid)
data.call_datestring (date-time)
data.caller_timezonestring | null
data.caller_namestring | null
data.caller_numberstring | null
data.callee_namestring | null
data.callee_numberstring | null
data.call_typestring
data.call_outcomestringSame values as status on the list.
data.durationinteger
data.leg_countinteger
data.platformstringPhone system type, e.g. netsapiens.
data.sentiment"positive" | "neutral" | "negative" | null
data.sentiment_scoreinteger | null
data.sentiment_labelstring
data.summarystring | null
data.analysisobject | null
data.analysis.summaryobject
data.analysis.summary.textstring
data.analysis.summary.key_pointsstring[]
data.analysis.summary.action_itemsstring[]
data.analysis.sentimentobject
data.analysis.sentiment.overallstring
data.analysis.topicsobject[] | null
data.analysis.topics[].namestring
data.vconobjectThe call's recording link (inside the conversation record). Only the fields below are documented; ignore anything else in this object.
data.vcon.recording_urlstring (uri) | nullSigned 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_atstring (date-time) | nullWhen recording_url stops working.
data.vcon.recording_mime_typestring | nullaudio/wav.
data.tasksobject[]Up to 100. See has_more_tasks.
data.tasks[].idstring (uuid)
data.tasks[].titlestring
data.tasks[].descriptionstring | null
data.tasks[].statusstring
data.tasks[].sourcestring
data.tasks[].assignee_userobject | null
data.tasks[].assignee_user.idstring (uuid)
data.tasks[].assignee_user.display_namestring
data.tasks[].assignee_user.emailstring (email)
data.tasks[].due_datestring | null
data.task_countinteger
data.has_more_tasksboolean
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

NameInTypeDescription
callId requiredpathstring (uuid)

Call id. Malformed ids return 400.

Responses

StatusMeaning
200Transcript lines in order.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.transcriptobject[]
data.transcript[].timenumberSeconds from the start of the call.
data.transcript[].speakerstring"Speaker 1" … "Speaker N".
data.transcript[].namestring
data.transcript[].textstring
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

NameInTypeDescription
date_fromquerystring (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_toquerystring (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.

keywordquerystring

Exact alert rule name, case-sensitive, one value. This is how you filter by rule.

topicquerystring

Exact topic slug, one value.

numbersquerystring[] (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
sentimentquery"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.

searchquerystring

Matches caller or callee name or number, summary text, or an exact lowercase alert id. Rule names don't match; use keyword.

location_idquerystring (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_idquerystring (uuid)

Narrow to one company.

cursorquerystring

Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400.

limitqueryinteger

Page size. Out-of-range values return 400. Use 100 for exports.


min 1, max 100, default 10

Responses

StatusMeaning
200One page of alerts. summary.total counts every match.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.summaryobject
data.summary.totalintegerEvery match, all pages.
data.alertsobject[]
data.alerts[].idstring (uuid)
data.alerts[].call_idstring (uuid)Open with GET /calls/{callId}.
data.alerts[].call_datestring (date-time)
data.alerts[].caller_timezonestring
data.alerts[].caller_namestring
data.alerts[].caller_numberstring
data.alerts[].callee_namestring
data.alerts[].callee_numberstring
data.alerts[].summarystring
data.alerts[].sentimentstring
data.alerts[].sentiment_scoreinteger | null
data.alerts[].sentiment_labelstring
data.alerts[].keywordsstring[]Names of the rules that fired.
data.alerts[].topicsstring[]
metaobjectPaging for conversation data. Stop when has_more is false.
meta.has_moreboolean
meta.next_cursorstring | null
meta.limitinteger
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

NameInTypeDescription
date_fromquerystring (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_toquerystring (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_idquerystring (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_idquerystring (uuid)

Narrow to one company.

Responses

StatusMeaning
200Totals.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.kpisobject
data.kpis.new_alertsinteger
data.kpis.monitoredintegerCalls in the window.
data.kpis.alert_ratenumbernew_alerts / monitored × 100.
data.top_triggeredobject[]
max items 10
data.top_triggered[].keywordstringRule name.
data.top_triggered[].countinteger
data.recent_alertsobject[]
max items 5
data.recent_alerts[].idstring (uuid)
data.recent_alerts[].call_idstring (uuid)Open with GET /calls/{callId}.
data.recent_alerts[].call_datestring (date-time)
data.recent_alerts[].caller_timezonestring
data.recent_alerts[].caller_namestring
data.recent_alerts[].caller_numberstring
data.recent_alerts[].callee_namestring
data.recent_alerts[].callee_numberstring
data.recent_alerts[].summarystring
data.recent_alerts[].sentimentstring
data.recent_alerts[].sentiment_scoreinteger | null
data.recent_alerts[].sentiment_labelstring
data.recent_alerts[].keywordsstring[]Names of the rules that fired.
data.recent_alerts[].topicsstring[]
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

NameInTypeDescription
statusquery"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_startquerystring (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_idquerystring (uuid)

Tasks of one call.

task_idquerystring (uuid)

One task. Can't be combined with due_on.

due_onquerystring (date)

Tasks due on this calendar date (YYYY-MM-DD).

date_fromquerystring (date-time)

Created at or after. Full RFC 3339 timestamp required. No default.

date_toquerystring (date-time)

Created at or before. Full RFC 3339 timestamp required. date_from after date_to returns an empty list.

searchquerystring

Substring match on title and description.

location_idquerystring (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_idquerystring (uuid)

Narrow to one company.

cursorquerystring

Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400.

limitqueryinteger

Page size. Send 100 and follow next_cursor.


min 1, max 100, default 20

Responses

StatusMeaning
200One page of tasks.
400Malformed or invalid parameter.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject[]
data[].idstring (uuid)
data[].call_idstring (uuid)
data[].company_idstring (uuid)
data[].location_idstring (uuid)
data[].titlestring
data[].descriptionstring | null
data[].status"pending" | "in_progress" | "completed" | "cancelled"Stored status.
data[].source"ai" | "manual"
data[].assignee_userobject | null
data[].assignee_user.idstring (uuid)
data[].assignee_user.display_namestring
data[].assignee_user.emailstring (email)
data[].due_datestring | null
data[].completed_atstring (date-time) | null
data[].created_atstring (date-time)
data[].updated_atstring (date-time)
metaobjectPaging for conversation data. Stop when has_more is false.
meta.has_moreboolean
meta.next_cursorstring | null
meta.limitinteger
summaryobjectCounts by display status. Honours every filter except status.
summary.totalinteger
summary.doneinteger
summary.in_progressinteger
summary.pendinginteger
summary.overdueinteger
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

NameInTypeDescription
start requiredquerystring (date-time)

Window start. Full RFC 3339 timestamp required.

end requiredquerystring (date-time)

Window end. Full RFC 3339 timestamp required. At most 366 days after start (422).

trending_limitqueryinteger

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_idquerystring (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_idquerystring (uuid)

Narrow to one company.

Responses

StatusMeaning
200Dashboard.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.statsobject
data.stats.total_callsinteger
data.stats.answered_callsinteger
data.stats.unanswered_callsinteger
data.trending_topicsobject[]
data.trending_topics[].slugstring
data.trending_topics[].namestring
data.trending_topics[].call_countinteger
data.trending_topics[].previous_call_countinteger
data.trending_topics[].percentage_changeinteger
data.trending_topics[].trend_dataobject[]
data.trending_topics[].trend_data[].daystring
data.trending_topics[].trend_data[].currentinteger
data.trending_topics[].trend_data[].previousinteger
data.topic_call_volumesobject[]
data.topic_call_volumes[].slugstring
data.topic_call_volumes[].namestring
data.topic_call_volumes[].call_countinteger
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

NameInTypeDescription
slug requiredpathstring

Topic slug from the dashboard's topic_call_volumes[].slug. An unknown slug returns an empty list.

date_fromquerystring (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_toquerystring (date-time)

End of the window. Full RFC 3339 timestamp required; a date alone returns 400. Default: now.

sentimentquery"positive" | "neutral" | "negative"

Coarse band only. Other values return 422.

outcomequery"completed" | "missed" | "pending"

Other values return 422.

searchquerystring

Same matching as /calls search.

location_idquerystring (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_idquerystring (uuid)

Narrow to one company.

cursorquerystring

Opaque next_cursor from the previous page. URL-encode it (it can contain +, / and =). A malformed cursor returns 400.

limitqueryinteger
min 1, max 100, default 25

Responses

StatusMeaning
200One page of calls.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject[]
data[].idstring (uuid)
data[].datestring (date-time)
data[].caller_namestring | null
data[].summarystring | null
data[].phone_numberstring | null
data[].sentimentstring | null
data[].sentiment_labelstring
data[].outcomestring
metaobject
meta.totalinteger
meta.has_moreboolean
meta.next_cursorstring | 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

NameInTypeDescription
locationId requiredpathstring (uuid)

Responses

StatusMeaning
200The webhook, or null.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject | null
data.idstring (uuid)
data.location_idstring (uuid)
data.webhook_urlstring
data.enabledboolean
data.created_atstring (date-time)
data.updated_atstring (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

NameInTypeDescription
locationId requiredpathstring (uuid)

Request body

FieldTypeDescription
webhook_url requiredstring (uri)HTTPS only. Private and loopback addresses are refused.
max length 2048
enabledboolean
default true
Example
{
  "webhook_url": "https://hooks.example.com/riverbend/calls",
  "enabled": true
}

Responses

StatusMeaning
200Saved.
400Malformed request (bad UUID, bad cursor, date without time, limit out of range, missing field).
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
403This login's role cannot do this (FORBIDDEN).
404Not found, or outside what this login may see. Treat as absent.
422Valid shape, invalid value (enum, date order, range, unknown reference).
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject | null
data.idstring (uuid)
data.location_idstring (uuid)
data.webhook_urlstring
data.enabledboolean
data.created_atstring (date-time)
data.updated_atstring (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

NameInTypeDescription
locationId requiredpathstring (uuid)

Responses

StatusMeaning
200Test result.
401Token missing, invalid or expired. Refresh or sign in again, then retry once. Rejections before the service use the flat edge shape.
403This login's role cannot do this (FORBIDDEN).
404Not found, or outside what this login may see. Treat as absent.
429Rate limited. Back off with jitter, and honour Retry-After if it is present.
503Temporarily unavailable. Back off with jitter and retry, honouring Retry-After if it is present.
200 response fields
FieldTypeDescription
dataobject
data.successboolean
data.http_statusintegerHTTP status your endpoint returned.
data.response_time_msinteger
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)

FieldTypeDescription
version required"1.0"
type required"end_of_call_summary"
is_test requiredbooleantrue only for test sends.
location_id requiredstring (uuid)
timestamp requiredstring (date-time)When Intelligence Cloud created the conversation record (UTC). Not the call time or the delivery time.
call requiredobject
call.id requiredstring (uuid)Same id as GET /calls/{callId} and an alert's call_id. Upsert on it.
call.caller_namestringOmitted when empty.
call.caller_numberstringOmitted when empty.
call.callee_namestringOmitted when empty.
call.callee_numberstringOmitted when empty.
call.call_type required"inbound" | "outbound" | "internal" | "missed" | "forwarded" | "unknown"
call.duration_seconds requiredinteger
call.call_date requiredstring (date)Date only (UTC).
call.platformstringPhone system type. Omitted when empty.
summaryobjectOmitted when the call has no summary.
summary.textstring
summary.sentimentstringUsually positive, neutral or negative.
summary.key_pointsstring[]Test sends only.
summary.action_itemsstring[]Test sends only.
location requiredobject
location.idstring (uuid)
location.company_idstring (uuid)
location.connector_idstring (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

StatusMeaning
200Any 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

StatusMeaning
200Any 2xx acknowledges the delivery.
Reseller Admin Guide · API and Integration Guide · Integration Recipes · Partner Launch Guide© 2026 Creo Solutions, Inc. d/b/a Tresic · API and SDK Terms · Other names are trademarks of their respective owners.