{ "openapi": "3.1.0", "info": { "title": "Nuacom API Reference", "version": "0.3794.1", "description": "V2 is the current, stable NUACOM API and the one to build new integrations against. It covers the whole product: account and users, extensions, numbers and call routing, IVR, call logs and recordings, SMS, contacts, billing and more.\n\n- Base URL: `https://api.api-nuacom.com/v2`\n- Reference: [/v2/ref](/v2/ref), generated from the deployed code, so it always matches what is running. Use the search box (Ctrl+K / \u2318K) to jump to an endpoint.\n- Authentication: the `Authorization: Bearer` header, see the [Authentication guide](/v2/docs/authentication).\n\n## Stability\n\n- Existing endpoints, parameters and response fields are not removed or renamed within V2. New optional fields and endpoints can appear at any time: read responses by key and ignore keys you do not know.\n- Dates are returned as `Y-m-d H:i:s` by default; accounts can opt into ISO 8601 output. Send `X-Timezone` with an IANA timezone name on endpoints that take date filters, otherwise the user's profile timezone is used.\n- Rate limit: 3000 requests per minute per token; above that the API answers `429` with a `Retry-After` header.\n\n## Endpoints under `/v3/\u2026`\n\nSome resources are served from a `/v3/\u2026` path. These are not a separate API: the same token works on both, one integration mixes `/v2/\u2026` and `/v3/\u2026` calls freely, and every one of them is listed in this reference alongside the `/v2/\u2026` endpoints. Copy the path from the reference as it is shown there.\n\nA handful of resources \u2014 contacts, call tags, call notes, users, queues and number blocking \u2014 have an endpoint on both paths. They are not duplicates: each operation in the reference says what it does and, where a close counterpart exists on the other path, how the two differ. The stability rules above apply to the `/v3/\u2026` endpoints too, except that validation rules there are stricter and may be tightened further between releases." }, "servers": [ { "url": "https://api.api-nuacom.com", "description": "production" } ], "tags": [ { "name": "Auth", "description": "The Auth group holds the login endpoints and the password endpoints that go with them. Every token they issue is sent as `Authorization: Bearer `, described in the [Authentication guide](/v2/docs/authentication).\n\n## Which token to use\n\n**Preferred: an API key.** An account admin issues it on the portal's **Settings \u2192 API Keys** page. The key acts as the admin who created it, so it reaches everything an account admin can, never expires, and needs none of the endpoints below. Use it for integrations, scripts and servers.\n\n**When you need a token scoped to one specific user** (with that user's narrower permissions and call-log visibility rather than an admin's), log in as that user with [`POST /v2/auth/login`](/v2/ref#/operations/auth.loginV1): it takes `email`, the plain-text password in `pass` (the API hashes it), `remember` and `two_fa_code`, and answers with a session token. A session token expires (30 days, or 90 with `remember`), so a long-running integration that does not need per-user restrictions should still prefer an API key.\n\n## Workflow\n\n```mermaid\nflowchart TD\n login[\"POST /v2/auth/login
email, pass, remember\"] --> answer{Answer}\n answer -- \"200, two_fa_enabled: true\" --> code[\"Ask the user for the emailed code\"]\n code --> retry[\"POST /v2/auth/login
+ two_fa_code\"] --> answer\n answer -- \"401, code: 4001\" --> password[\"POST /v2/auth/update-password\"] --> login\n answer -- \"200, session_token\" --> calls[\"Authorization: Bearer on every call
for expire_in seconds\"]\n calls --> logout[\"POST /v2/logout\"]\n calls -- \"401 from any endpoint\" --> login\n```\n\n1. [`POST /v2/auth/login`](/v2/ref#/operations/auth.loginV1) with `email`, the password in `pass` and `remember`.\n2. If the answer is `200` with `two_fa_enabled: true`, a code has been emailed to the user: ask for it and repeat the same call with `two_fa_code`.\n3. If the answer is `401` with `code: 4001`, the password has expired: collect a new one, call [`POST /v2/auth/update-password`](/v2/ref#/operations/auth.update-password) with the plain-text `password`, `new_password` and `new_password_confirmation`, then log in again with the `two_fa_code` that call returns.\n4. Store `session_token` and send it as `Authorization: Bearer `. Store `expire_in` too: the session is fixed-length (30 days, or 90 with `remember`) and is not extended by use.\n5. Call [`POST /v2/logout`](/v2/ref#/operations/auth.logout) when you are done. A `401` from any endpoint means the session is gone: log in again.\n\n## Roles and access\n\n- No token is needed for the login and password endpoints; `update-password` identifies the user by `email`.\n- No account-admin requirement.\n- An account can enforce 2FA for every user, restrict logins to an IP allow-list (`code: 4004`) or disable password logins in favour of single sign-on (`code: 4002`).\n\n## Pitfalls\n\n- Send these calls to the central host `https://api.api-nuacom.com`. On an account subdomain they answer `404`.\n- `login` and `update-password` take the password in plain text; send them over HTTPS only.\n- \"2FA needed\" is HTTP `200`, not an error. Only a wrong or expired code is a `401`.\n- Five failed logins from one IP address within five minutes lock that address for a few minutes.\n- `update-password` expires every existing session of the user, on every device." }, { "name": "Account", "description": "The account is the organization your token belongs to: its id (`IE-00123`), company and billing details, primary user, timezone and balances. [`GET /v2/account_info`](/v2/ref#/operations/account.view) is the one endpoint of this group and the first call to make with a new API key (see [Quickstart](/v2/docs/quickstart)). Beside it sit three sub-groups of account-wide settings that an account admin manages in the portal's account settings: **Account / Settings** (the password policy and the read-only security settings), **Account / Language Config** (the languages AI transcription uses) and **Account / AI Config** (the call recap email).\n\n## Account info and its sub-configs\n\n```mermaid\nflowchart TD\n info[\"GET /v2/account_info\"] --> security[\"Account / Settings
GET /v2/account-security-settings\"]\n info --> language[\"Account / Language Config
GET/POST /v2/account-language-config\"]\n info --> ai[\"Account / AI Config
GET/POST /v2/account-ai-config\"]\n```\n\n## Workflow (what the portal does)\n\n1. **Account info**: [`GET /v2/account_info`](/v2/ref#/operations/account.view), any user. The fields are described below.\n2. **Password policy**: [`GET /v2/account-password-requirements`](/v2/ref#/operations/v2.getPasswordRequirements), any user, returns the rules a new password must meet, keyed by rule, each with a `value` and a ready-to-show `text`. `password_min_length` (the minimum length, `8` by default) and `no_reuse` are always present; `password_must_mixed_case`, `password_must_include_numbers`, `password_must_include_symbols` and `password_is_uncompromised` appear only when enabled, with `value: true`. The change-password form validates against it before calling [`POST /v2/auth/update-password`](/v2/ref#/operations/auth.update-password), and the same object comes back as `requirements` when a login fails with code `4001` (see [Authentication](/v2/docs/authentication)).\n3. **Security settings** (account admin): [`GET /v2/account-security-settings`](/v2/ref#/operations/account-security-settings.index) returns the settings in the table below plus `oauth` and `ip_whitelist`. They are read-only here: changing them, 2FA and the IP allow-list included, is done in the portal's account settings.\n4. **Transcription languages**: [`GET /v2/language-options`](/v2/ref#/operations/v2.languageOptions), any user, lists the 58 supported languages as `{\"data\": [{\"code\": \"en\", \"label\": \"English\"}, \u2026]}` with two-letter codes. [`GET /v2/account-language-config`](/v2/ref#/operations/account-language-config.index) returns the account's defaults and overrides and [`POST /v2/account-language-config`](/v2/ref#/operations/account-language-config.store) replaces them (account admin, where the feature is enabled). Details below.\n5. **AI call recap** (account admin): [`GET /v2/account-ai-config`](/v2/ref#/operations/account-ai-config.index) and [`POST /v2/account-ai-config`](/v2/ref#/operations/account-ai-config.store), described below.\n\n## Reading the account info\n\n| Field | Meaning |\n|---|---|\n| `account_id` | The account id (`IE-00123`), the same value `POST /v2/auth/login` returns |\n| `company_name`, `company_email`, `billing_email` | As set in the portal; `null` when unset |\n| `address` | `address_1`, `address_2`, `city`, `county`, `country_iso_code`, `post_code`, `coordinates`; every key is present, `\"\"` when unset |\n| `account_holder` | The primary user: `user_id`, `user_email`, `user_name`, `last_login` (`null` if they never signed in); `null` when the account has no primary user |\n| `account_country_code` | ISO 3166-1 alpha-2 country of the account: the address country, or the account's own country when the address has none |\n| `created_at` | When the account was set up; see [Dates and timezones](/v2/docs/dates-and-timezones) for the two formats |\n| `time_zone` | The account's timezone as an IANA name (`Europe/Dublin`). Each user has their own, and the user's is what the API applies to the dates it formats for them |\n| `billing.billing_currency` | The currency code (`EUR`) |\n| `billing.billing_type` | `bill_pay`, `pre_pay` or `mixed` |\n| `billing.sms_billing_type` | `bill_pay` or `pre_pay`: how SMS is charged |\n| `billing.account_balance` | The balance in `billing_currency`, two decimals |\n| `billing.sms_balance` | SMS credits available, rounded to a whole number: top-up credits plus, on a pre-pay account with a positive balance, what the balance buys at the account's SMS rate. `0` when the account is not active |\n\n## Security settings\n\n| Setting | Default | Effect |\n|---|---|---|\n| `allow_local_login` | `true` | `false` rejects every email-and-password login with code `4002`; users sign in with SSO only |\n| `allow_sso_logins` | `true` | `false` rejects Google and Microsoft sign-ins |\n| `oauth` | both providers enabled, `config` `[]` | One entry per provider: `provider`, `provider_name` (`GOOGLE`, `MICROSOFT`), `is_enabled`, `config` |\n| `enable_ip_restrictions` | `false` | With a non-empty `ip_whitelist`, logins from any other address are rejected with code `4004`. With an empty list the restriction is not applied |\n| `ip_whitelist` | `[]` | Entries as `id` and `ip_address` |\n| `require_2fa` | `false` | Every user must confirm a new device with the emailed code, whatever their own two-factor setting |\n| `should_periodically_reset` | `false` | A password expires `reset_period_months` after it was last changed; login then fails with code `4001` until it is changed |\n| `reset_period_months` | `6` | `1` to `12` |\n| `password_min_length` | `8` | `8` to `32` |\n| `password_must_mixed_case` | `true` | At least one upper-case and one lower-case letter |\n| `password_must_include_numbers` | `true` | At least one digit |\n| `password_must_include_symbols` | `true` | At least one symbol |\n| `password_is_uncompromised` | `false` | Rejects passwords found in public data leaks |\n\nUntil the settings have been saved in the portal, `GET` returns these defaults with `account_id`; after a save it also carries `created_at` and `updated_at`. The password rules apply when a password is changed, and the same rules are what [`GET /v2/account-password-requirements`](/v2/ref#/operations/v2.getPasswordRequirements) describes. Switching `should_periodically_reset` on records every user's current password at that moment, so the first expiry falls `reset_period_months` later for everyone.\n\n## Transcription languages\n\nThe language config decides which language [Speech To Text](/v2/docs/groups/speech-to-text) transcribes calls and voicemails in; the AI data in [Call AI](/v2/docs/groups/call-ai) is built from that transcript. `GET` answers, and `POST` takes, the same four keys:\n\n- `number_languages`: the default for calls, a list of codes from `GET /v2/language-options`. Required on `POST`, with at least one code.\n- `voicemail_languages`: the default for voicemails. On `POST`, `null` or omitted leaves it as it is; a list (`[]` included) replaces it.\n- `number_overrides`: one entry per number, `{\"in_ext\": \"35350534456\", \"languages\": [\"pl\"]}`. `in_ext` is the number as digits with the country code and no `+`, at most 20 characters. On `POST`, `null` or omitted leaves the overrides as they are; a list (`[]` included) replaces them all.\n- `voicemail_overrides`: one entry per voicemail box, `{\"voicemail_box\": 10, \"languages\": [\"en\"]}`, with the same replace-or-leave rule.\n\n`POST` answers `200` with the saved config. A call is transcribed in the language of the override for the number that handled it (the dialled number on an inbound call, the caller ID on an outbound one; after a transfer, the last number that took the call), otherwise in the account's default call language, otherwise in English. A voicemail uses its box's override, otherwise the default voicemail language, otherwise English. Voicemail languages and overrides need the Unlimited AI Call Analysis add-on (see [Speech To Text](/v2/docs/groups/speech-to-text)): without it `GET` returns them empty, `POST` ignores what you send for them and clears what was stored, and voicemails are transcribed in English.\n\n## AI call recap\n\nWhen enabled, every call that received an AI summary is followed by an email, *Nuacom AI: Your Call Recap*, to the configured recipients whose extension was on the call. The config has three keys:\n\n- `is_recap_email_enabled`: send `true` or `false`; it is returned as `1` or `0`.\n- `recipients`: a list of strings, each a user id (`\"12\"`) or a team id prefixed with `d` (`\"d431\"`, every member of the team). Every entry must be an active user or a team of your account, otherwise `422` with `One or more of the recipients are not available for your account.`. Send it on every call; `[]` clears the list. Users who are no longer active are dropped from the answer.\n- `extra_config`: `isDurationLimited` (`true` skips calls shorter than the limit), `durationLimitMinutes` (`0` to `15`), `durationLimitSeconds` (`0` to `59`), `shouldForwardToAdmins` and `forwardToAdminsIds` (account admins copied on every recap; a non-admin id answers `422` with `One or more of the selected admins are not account admins.`). The answer adds `durationTotalLimitSeconds`, computed from the minutes and seconds; a value you send for it, and any other key, is ignored.\n\n`POST` answers `200` with the saved config. The first `GET` on an account that never saved one answers the defaults: recap off, no recipients, no duration limit.\n\n## Roles and access\n\n- `GET /v2/account_info`, `GET /v2/account-password-requirements` and `GET /v2/language-options`: any authenticated user.\n- Security settings and AI config: account admins only; anyone else gets `403` `\"Forbidden\"`.\n- Language config, both endpoints: account admins, and only on accounts where NUACOM has enabled multilingual AI; otherwise `403`. Voicemail languages additionally need the Unlimited AI Call Analysis add-on, as described above.\n- The ISO dates option (per account) changes the format of `created_at` and `account_holder.last_login` in the account info and of `created_at` and `updated_at` in the security settings \u2014 see [Dates and timezones](/v2/docs/dates-and-timezones).\n\n## Pitfalls\n\n- The account info carries no add-ons: read the AI add-on from [`GET /v2/speech-to-text/active`](/v2/ref#/operations/accountAddonStt.currentAddon).\n- Enabling `enable_ip_restrictions` with an empty `ip_whitelist` restricts nothing; add the address you sign in from before enabling it, or the next login from elsewhere fails with code `4004`.\n- Only the first code of each language list is used; the rest is stored and returned but has no effect.\n- Store `in_ext` as digits without `+` (`35350534456`). A leading `+` passes validation but the number is looked up in the digits-only form, so such an override never matches a call.\n- `number_overrides` and `voicemail_overrides` are replaced wholesale whenever you send them: an entry left out is deleted.\n- `recipients` must be present on every `POST /v2/account-ai-config`; a request without it fails with `500`, not `422`. Send `[]` to clear the list.\n- A recipient receives the recap only for calls their own extension handled. To copy someone on every recap, list them, as an account admin, in `forwardToAdminsIds` with `shouldForwardToAdmins` on." }, { "name": "Account / Settings" }, { "name": "Account / Language Config" }, { "name": "Account / AI Config" }, { "name": "Account / Billing Info" }, { "name": "Users", "description": "A user is a person who signs in to the NUACOM portal and apps: a name, email, mobile number and timezone, plus one **membership** per account they belong to that carries the account-level settings \u2014 admin or regular user, portal access, mobile extension, call-recording access, status and permissions. This group holds the legacy pair [`GET /v2/users_list`](/v2/ref#/operations/account.users) and [`GET /v2/user_info`](/v2/ref#/operations/user.view) and the v3 family: the paginated list, one user, the update, and the caller's own profile. A user is linked to at most one extension per account (managed in [Extensions](/v2/docs/groups/extensions)) and belongs to any number of teams; creating, suspending and deleting users is done in the portal.\n\n## Workflow (what the portal does)\n\n1. **Who is calling**: [`GET /v2/user_info`](/v2/ref#/operations/user.view) answers the session context the apps load at start-up: `user_id`, `user_name`, `account_id`, `account_name`, `user_country`, `time_zone`, `user_shared_accounts` (the other accounts the user is active in), `user_admin`, `recording_access`, `outbound_cli`, `user_extension` (only when the user has an extension) and `call_events`. With an API key this describes the user the key acts as (see [Authentication](/v2/docs/authentication)).\n2. **My profile**: [`GET /v3/users/me`](/v2/ref#/operations/v3.users.me) returns the caller's own user record: `user_id`, `user_name`, `user_email`, `mobile`, `country_dial_code`, `time_zone`, `last_login`, `extension` (the number, or `\"\"` when none), `user_active` and `account` (one membership row per account the user is active in).\n3. **List**: [`GET /v3/users`](/v2/ref#/operations/v3.users.users.index) with `page` and `per_page` (default 25, no maximum), newest first. Each row is `user_id`, `user_name`, `user_email`, `mobile`, `last_login`, `extension`, `user_active` and `departments` (the user's teams, `id` and `name`); the response is `{\"data\": [...], \"links\": {...}, \"meta\": {...}}`. Active, suspended and awaiting-activation members are listed; deleted ones are not.\n [`GET /v2/users_list`](/v2/ref#/operations/account.users) is the same set as one flat, unpaginated array in the V1 shape: each row adds the membership flags (`account_admin`, `web_access`, `call_recording`, `mobile_extension`, `user_active`, `active_in_account`), `country_iso_code`, `country_dial_code`, `is_auth_2fa_enabled`, `user_extension` and `outbound_cli`. Two optional switches: `checkAdmin=1` makes a regular user receive only their own row, and `enterprise_only=true` keeps only users whose extension has an Enterprise or Unlimited subscription.\n4. **One user**: [`GET /v3/users/{user}`](/v2/ref#/operations/v3.users.users.show) by `user_id` answers `{\"user\": {...}}`: the profile with its `departments` and an `account` array listing every membership the user has, each carrying the flags above. A user who is not a member of your account, or was deleted, answers `404`.\n5. **Edit** (what the Users screen saves): [`PUT /v3/users/{user}`](/v2/ref#/operations/v3.users.users.update) with the complete form:\n - `user.user_name` (required, at most 64 characters), `user.mobile` (at most 30), `user.country_dial_code` (integer), `user.time_zone` (IANA name, at most 20 characters), `user.is_auth_2fa_enabled` (boolean);\n - the membership flags as `0`/`1`: `user.account_admin`, `user.web_access`, `user.mobile_extension`, `user.call_recording`;\n - `user.departments`: the teams as `[{\"value\": }]` \u2014 the list replaces the user's teams;\n - `pages`: the ids of the portal pages the user may open \u2014 pages left out are revoked. Page ids are assigned in the portal (**Settings \u2192 Users \u2192 Permissions**); the API has no public catalogue of them.\n The answer is `{\"success\": true}`. `user.extension` is accepted but ignored, and permissions are not part of the form: both are set in the portal.\n7. **Teams**: a user's `departments` are the account's teams. Add or remove a member with [`PUT /v3/teams/{teamId}/users/{user}`](/v2/ref#/operations/v3.teams.users.update) and [`DELETE /v3/teams/{teamId}/users/{user}`](/v2/ref#/operations/v3.teams.users.destroy), list a team's members with [`GET /v3/teams/{teamId}/users`](/v2/ref#/operations/v3.teams.users.index) and the teams themselves with [`GET /v3/teams`](/v2/ref#/operations/v3.teams.teams.index). The v2 [`GET /v2/departments`](/v2/ref#/operations/departments.index) endpoints work on the same objects under the older name.\n\nCreating, suspending and deleting users is done in the portal (**Settings \u2192 Users**); there is no public endpoint for it. Deleting a user there offers to hand their private contacts to a colleague first.\n\n## Reading a user\n\n- **Admin or regular user**: `account_admin` on the membership (`user_admin` in `/v2/user_info`). An admin sees the whole account and may call the admin-only endpoints; a regular user sees their own extension plus what their permissions grant, and admin-only endpoints answer `403`. The flag is per account: the same person can be an admin in one account and a regular user in another.\n- **Call recording access**: `call_recording` is the portal's \"Call Recording Access\" toggle. Through the API every user, admins included, needs it on to play recordings, and the account's recording add-on or the extension's subscription must include recording; `recording_access` in `/v2/user_info` is that combined answer.\n- **Status**: `user_active` is `0` suspended, `1` active or `2` awaiting activation (the user has not completed sign-up). Deleted users never appear.\n- **Portal and mobile**: `web_access` \u2014 may sign in to the web portal; `mobile_extension` \u2014 may use a mobile extension.\n- **Extension**: `extension` (v3) or `user_extension` (v2) is the number of the user's extension in this account, and `outbound_cli` the caller ID that extension presents. Linking is done by an admin in the portal's Users screen; the extension itself is managed in [Extensions](/v2/docs/groups/extensions).\n- **Timezone**: `time_zone` is the user's IANA timezone. It is the default for every date the API formats for that user when you send no `X-Timezone` header.\n- **last_login**: `null` when the user has never signed in. With the account's ISO dates option the value is ISO 8601 in the `X-Timezone` you send, UTC by default (`2024-08-28T09:15:00+01:00`); without it, `/v2/users_list` gives wall-clock `Y-m-d H:i:s` and the v3 endpoints keep only the day (midnight, serialised as a UTC timestamp). See [Dates and timezones](/v2/docs/dates-and-timezones).\n- **Several accounts**: a user may belong to more than one account. `active_in_account` marks the one they are currently working in, `user_shared_accounts` lists the others, and the `account` array of the v3 profile has one row per membership \u2014 pick yours by `account_id`.\n- **API keys**: a key acts as the user who created it; that user's admin flag, permissions and recording access decide what the key sees, and `GET /v2/user_info` with the key tells you who that is. See [Authentication](/v2/docs/authentication).\n\n## Roles and access\n\n- Every endpoint in this group accepts any authenticated user; none is restricted to account admins. The lists are not filtered by the caller's permissions either: a regular user sees every member, except with `checkAdmin=1` on `/v2/users_list`.\n- The ISO dates option (per account) changes the `last_login` format as described above. \n- A user outside your account answers `404` from `/v3/users/{user}`.\n\n## Pitfalls\n\n- The pagination links of `GET /v3/users` use `users=` as the page parameter, but the endpoint reads `page`: following `links.next` returns the first page again. Build the URL yourself from `meta.current_page` and `meta.last_page`.\n- `/v2/users_list` returns `user_id`, `user_active` and `country_dial_code` as strings (`\"123\"`, `\"1\"`, `\"353\"`); the v3 endpoints return integers.\n- `PUT /v3/users/{user}` is a full replacement with no partial update: send every `user.*` field, `user.departments` and `pages` even when unchanged. A missing field fails the request with `500`, not `422`.\n- `user.time_zone` is limited to 20 characters, so longer IANA names (`America/Argentina/Buenos_Aires`) are rejected with `422`.\n- A suspended member is listed and readable, but a `PUT` on them fails with `500`.\n- `departments` is present only where the endpoint loads it: in the list and in `/v3/users/{user}`.\n- `/v2/user_info` omits `user_extension` and `call_events` rather than returning `null` when the user has no extension or has not enabled call events." }, { "name": "Extensions", "description": "An extension is a SIP line on the account: a number in the range 10\u20139999, a display name, a subscription tier, an optional linked user and device. This group lists extensions, creates and deletes them and sets their live status; pricing previews, pre-pay creation and tier changes sit in the Extensions / Subscriptions group next to it. Per-extension settings such as voicemail, call handling and caller-ID preselection are set in the portal.\n\n## Workflow (what the portal does)\n\n1. **List**: [`GET /v2/extensions`](/v2/ref#/operations/extensions.index) answers a plain array of `{number, name, extension_is_used, subscription}`. An admin sees the whole account; a regular user sees their own extension and the ones granted to them.\n2. **Caller-ID numbers**: [`GET /v2/extensions/available-cli`](/v2/ref#/operations/v2.extensionsAvailableCli) lists the account's numbers an extension can present. [`GET /v2/user_info`](/v2/ref#/operations/user.view) gives the calling user's profile and outbound CLI.\n3. **Create** (account admin): pick a tier from [`GET /v2/subscriptions`](/v2/ref#/operations/subscriptions.index), then\n - bill-pay and trial accounts call [`POST /v2/extensions/store`](/v2/ref#/operations/extensions.store) with `from`, `to` (at most ten numbers per call), `subscription_id` and `callerID`;\n - pre-pay accounts buy the licences first in the portal, and create the extensions once the payment is confirmed.\n4. **Subscriptions** (account admin): [`add-subscription`](/v2/ref#/operations/extensions.addSubscription) for an extension without one, [`change-subscription`](/v2/ref#/operations/extensions.changeSubscription) to move tiers. [`DELETE /v2/extensions/{extNumber}/subscription`](/v2/ref#/operations/extensions.cancelSubscription) cancels the subscription **and deletes the extension**.\n5. **Rename**: [`PUT /v2/extensions/{extNumber}/set-name`](/v2/ref#/operations/extensions.updateExtensionName).\n6. **Delete** (account admin): [`DELETE /v2/extensions`](/v2/ref#/operations/extensions.deleteExtensions) with an `extensions[]` body. An extension with a provisioned device cannot be deleted this way (`422`), and at least two extensions must remain (`400`).\n7. **Queues**: [`POST /v2/extensions/set-dynamic-agent-queue-status`](/v2/ref#/operations/extensions.updateDynamicAgentQueueStatus) logs an extension in or out of a queue (`queue`, `extension`, `action`).\n8. **Availability report**: [`GET /v2/extension-activity`](/v2/ref#/operations/extensionActivity.index) returns each extension's online sessions for a `date`, optionally filtered by `departmentId` (from [`GET /v2/departments`](/v2/ref#/operations/departments.index)) or `extensions`.\n\nLinking an extension to a user is done by an admin in the portal's Users screen.\n\n## Creating an extension\n\n```mermaid\nflowchart TD\n tier[\"GET /v2/subscriptions: pick a tier\"] --> type{\"Account type\"}\n type -- \"bill-pay or trial\" --> billpay[\"POST /v2/extensions/store
from, to, subscription_id, callerID\"]\n billpay --> billready[\"Extension created\"]\n type -- \"pre-pay\" --> buy[\"Buy the licences in the portal\"] --> prepayready[\"Create the extensions once paid\"]\n```\n\n## Roles and access\n\n- Creating, deleting, renaming, changing subscriptions, pricing previews and the status endpoint require an **account admin** (`403` otherwise).\n- Listing, the caller-ID lookups, the agent queue status (for your own extension) and the availability report are open to any authenticated user.\n- The ISO dates option switches the availability report's timestamps to ISO 8601.\n\n## Pitfalls\n\n- Numbers 112, 171, 777 and 999 are reserved. In a `from`\u2013`to` range, numbers already taken are skipped silently; you only get an error when none is left.\n- `callerID` is copied as sent and is not validated. Use a number from `available-cli`.\n- Pre-pay creation and tier changes are asynchronous: `204` means the payment was accepted, not that the extension exists yet. Poll the list.\n- Pre-pay downgrades take effect on the first day of the next month; pre-pay upgrades are paid in the portal's checkout.\n- Cancelling a subscription deletes the extension, including its device link, voicemail and queue membership.\n- `status` values are case-sensitive: `Busy` or `Active`.\n- SIP credentials are never returned by the API; they are shown in the portal.\n- The availability report is account-wide: it is not filtered by the caller's permissions." }, { "name": "Extensions / Subscriptions" }, { "name": "Departments", "description": "Departments are the original name of [Teams](/v2/docs/groups/teams): the same named groups of users, with the same ids. This group holds the four v2 endpoints: one flat list that embeds the members of every department, and three admin-only writes that answer a boolean. Prefer the v3 Teams endpoints for new work; use this list when you want every department with its members in one request.\n\n## Workflow (what the portal does)\n\n1. **List**: [`GET /v2/departments`](/v2/ref#/operations/departments.index) takes no parameters and answers a plain array, not a page, with every department of the account: `id`, `name` and `users`, the members as `user_id`, `user_name` and `user_email`.\n2. **Create** (account admin): [`POST /v2/departments/store`](/v2/ref#/operations/departments.store) with `name` (required, at most 20 characters) answers `201` with `id`, `name` and an empty `users`. Members are added afterwards through [Teams](/v2/docs/groups/teams), or with `user.departments` on [`PUT /v3/users/{user}`](/v2/ref#/operations/v3.users.users.update) (see [Users](/v2/docs/groups/users)).\n3. **Rename** (account admin): [`PUT /v2/departments/{department}/update`](/v2/ref#/operations/departments.update) with `name` answers the JSON boolean `true`. The name is the only thing this endpoint changes.\n4. **Delete** (account admin): [`DELETE /v2/departments/{department}/delete`](/v2/ref#/operations/departments.destroy) answers `true`.\n\nAn unknown `{department}`, or one of another account, answers `404` from rename and delete. Each create, rename and delete is recorded in the account's change log as `User group has been added`, `renamed to ` or `deleted`.\n\n## Departments, users and extensions\n\n- A department is a set of users: a user may belong to several departments, and a department may be empty. Membership is the only relation a department has.\n- Extensions follow their users. A user has at most one extension per account (see [Extensions](/v2/docs/groups/extensions)), so \"the extensions of a department\" means the extensions of its members. That is how the availability report [`GET /v2/extension-activity`](/v2/ref#/operations/extensionActivity.index) applies its `departmentId` filter, and how an AI call recap addressed to a department reaches the members whose extension was on the call.\n- Departments carry no numbers, queues or permissions. What they gate \u2014 call tag visibility, conversation assignment, report filters and recap recipients \u2014 is listed under *What a team does* in [Teams](/v2/docs/groups/teams).\n\n## Roles and access\n\n- The list is open to any authenticated user. Create, rename and delete require an account admin; anyone else gets `403` `\"Forbidden\"`.\n\n## Pitfalls\n\n- The paths carry the verb: `POST \u2026/store`, `PUT \u2026/{department}/update`, `DELETE \u2026/{department}/delete`. There is no `GET /v2/departments/{department}`; read one department from the list, or from [`GET /v3/teams/{teamId}`](/v2/ref#/operations/v3.teams.teams.show).\n- Create answers `201` with the department; rename and delete answer a bare `true`, not the department.\n- The list is unpaginated and always embeds the members. `users` carries no status, so a suspended member looks like an active one; check `user_active` in [Users](/v2/docs/groups/users).\n- `name` is limited to 20 characters and is not unique: two departments can share a name.\n- `name` is the only field the writes accept; anything else in the body is ignored, so members cannot be set here.\n- Validation errors answer `422` as `{\"errors\": {...}}`; a missing department answers `404` with `{\"message\": \"Resource not found!\"}`." }, { "name": "Teams", "description": "A team is a named group of users in the account. Teams label users rather than extensions: they decide which call tags a user may see, where a conversation can be assigned, who receives the AI call recap email and which extensions the availability report shows. This group holds the v3 team list and the create, read, update and delete endpoints, plus, under **Teams / Users**, the membership endpoints. The v2 [Departments](/v2/docs/groups/departments) endpoints work on the same records under their older name, so a team `id` here is a department id there.\n\n## Workflow (what the portal does)\n\n1. **List**: [`GET /v3/teams`](/v2/ref#/operations/v3.teams.teams.index) with `page` (15 teams per page; `per_page` is not read), `sort` (`id` or `-id`; `id` by default) and `include`: `usersCount` fills `users_count`, `users` embeds the full member list, `team` embeds a preview of at most three members. The response is `{\"data\": [...], \"links\": {...}, \"meta\": {...}}`; each team is `id`, `name` and `users_count` (`null` unless you include it). An unknown `include` or `sort` answers `400`.\n2. **Create**: [`POST /v3/teams`](/v2/ref#/operations/v3.teams.teams.store) with `name` (required, at most 20 characters) and optional `members`, an array of user ids. Every id must be a user of your account whose membership has not been deleted; otherwise `422` with `One or some of the provided users does not belong to this account.`. Answers `201` with the team's `id` and `name`. Pick the ids from [`GET /v3/users`](/v2/ref#/operations/v3.users.users.index) (see [Users](/v2/docs/groups/users)).\n3. **Read**: [`GET /v3/teams/{teamId}`](/v2/ref#/operations/v3.teams.teams.show) answers `id`, `name`, `users_count` and `users`, the members as user rows (`user_id`, `user_name`, `user_email`, `mobile`, `extension`, `user_active`, `last_login`). An unknown id, or a team of another account, answers `404`.\n4. **Rename or replace the members**: [`PUT /v3/teams/{teamId}`](/v2/ref#/operations/v3.teams.teams.update) takes the same body as create. `members` replaces the whole membership, and a request without `members` empties the team. Answers `200` with `id` and `name`.\n5. **One member at a time**: [`GET /v3/teams/{teamId}/users`](/v2/ref#/operations/v3.teams.users.index) lists the members, 15 per `page`, as the user rows above; [`PUT /v3/teams/{teamId}/users/{user}`](/v2/ref#/operations/v3.teams.users.update) adds the user (no body) and answers `200` with the team and its new `users_count`; [`DELETE /v3/teams/{teamId}/users/{user}`](/v2/ref#/operations/v3.teams.users.destroy) removes them and answers `204`. A `{user}` who is not a member of your account answers `404`. The same membership is edited from the user's side with `user.departments` on [`PUT /v3/users/{user}`](/v2/ref#/operations/v3.users.users.update).\n6. **Delete**: [`DELETE /v3/teams/{teamId}`](/v2/ref#/operations/v3.teams.teams.destroy) answers `204`.\n\n## What a team does\n\nTeams are used by reference, through their `id`, in these places:\n\n- **Users**: every row of [`GET /v3/users`](/v2/ref#/operations/v3.users.users.index) and the profile in [`GET /v3/users/{user}`](/v2/ref#/operations/v3.users.users.show) carry `departments`, the user's teams as `id` and `name`.\n- **Call tags**: a tag with the visibility rule `{\"type\": 2, \"allowed_id\": }` is shown only to the members of that team \u2014 see [Call Tags](/v2/docs/groups/call-tags).\n- **Conversations**: an SMS or WhatsApp conversation can be assigned to a team (`department_id` on the assign endpoint, `assigned_department_id` on the conversation), and the auto-assignment rules can target a team \u2014 see [Conversations](/v2/docs/groups/conversations).\n- **Extension activity**: the availability report in [Extensions](/v2/docs/groups/extensions) takes `departmentId` and keeps only the extensions of that team's members.\n- **AI call recaps**: the recipients of the recap email are user ids and team ids written as `d` \u2014 see [Account](/v2/docs/groups/account).\n\nA team owns no extension, number or queue. Whatever applies to a team applies to the extensions of its members: a user has at most one extension per account, so a team's extensions are its members' extensions.\n\n## Roles and access\n\n- Every endpoint in this group, writes included, is open to any authenticated user of the account; none requires an account admin. The v2 [Departments](/v2/docs/groups/departments) endpoints, by contrast, allow writes to admins only.\n- Teams belong to the account of the token: another account's team id answers `404`, and `members` may name only users of your account.\n- The ISO dates option (per account) changes the `last_login` format in member rows \u2014 see [Dates and timezones](/v2/docs/dates-and-timezones).\n\n## Pitfalls\n\n- `PUT /v3/teams/{teamId}` is a full replacement: a body with only `name` removes every member. Send the complete `members` list, or use the per-member endpoints.\n- Team names are not unique: two teams can share a name, so key your data on `id`.\n- `users_count` is `null` on the list unless you add `include=usersCount`, and `null` on the create and update answers; `users` is present only on `GET /v3/teams/{teamId}` and with `include=users`.\n- `include=team` is a preview capped at three members per team; use `include=users` or the members endpoint for the full list.\n- The page size is fixed at 15; `per_page` is ignored.\n- Adding a user who is already a member answers `200` and changes nothing; removing a user who is not a member answers `204`.\n- Validation errors answer `422` as `{\"errors\": {...}}`.\n- The same number identifies a team everywhere: `id` here, `{department}` in the v2 endpoints, `allowed_id` in call tag visibility and `d` in the AI recap recipients." }, { "name": "Teams / Users" }, { "name": "Numbers", "description": "Numbers are the public phone numbers (DIDs) callers dial to reach the account. This group lists the numbers the account holds and covers getting new ones: the countries and prices on offer, searching NUACOM's stock and the provider catalogues, filing an order request, including the identity and address proof some countries require. Where a number's calls go (an extension, a queue or an [IVR](/v2/docs/groups/ivr)) is set in the portal under Numbers & Inbound Call Routing; the API has no routing endpoint. Number Providers and Porting are managed by NUACOM and have no public endpoints: to move an existing number to NUACOM, contact support, who need your authorisation before the port is requested.\n\n## Workflow (what the portal does)\n\n1. **The account's numbers**: [`GET /v2/my-numbers`](/v2/ref#/operations/account.myNumbers) answers a plain array with one `{\"in_ext\", \"number_name\"}` object per assigned number. `in_ext` is the number as international digits without `+` (`35312345678`); `number_name` is the label given to the line, which, when enabled for that number, is appended to the caller ID name of inbound calls so agents see which line was called. That is the whole row: country, routing target and capabilities are not returned. The numbers an extension may present as caller ID come from [`GET /v2/extensions/available-cli`](/v2/ref#/operations/v2.extensionsAvailableCli) (see [Extensions](/v2/docs/groups/extensions)), fax numbers from [`GET /v2/fax`](/v2/ref#/operations/fax.index).\n2. **Countries and prices** (account admin): [`GET /v2/numbers/order/countries-info`](/v2/ref#/operations/orderPhoneNumber.infoByCountries) answers one row each for Ireland, the United States and the United Kingdom (`iso` in lower case: `ie`, `us`, `gb`) with `name`, `priceMonthly` (the lowest monthly price in euro), `price` (the same as text, `\u20ac5 / month`, with a leading space) and `currency` (`\u20ac`), followed by an `Others Regions` row with `iso` `xx`, `price` `Custom Price` and `priceMonthly` `null`.\n3. **Search the catalogue** (account admin): [`GET /v2/numbers/order/search-available-numbers`](/v2/ref#/operations/orderPhoneNumber.searchAvailableNumbers) with `category=paid_1` (the only value accepted), `iso` (the country, `IE`) and optionally `type` (`Local`, `National`, `Mobile`, `Toll-free`, `Shared Cost` or `Global`) and `areaCode` (digits are matched against the provider's area prefix, text against the area name, for example `Dublin`). It answers up to 20 rows of `{\"number\", \"country_iso\", \"monthly_price\"}` with `number` in E.164 (`+35312345678`) and the monthly price in euro.\n4. **File the order** (account admin): [`POST /v2/numbers/order/phone-number-request`](/v2/ref#/operations/orderPhoneNumber.orderPhoneNumberRequest) with `category: \"paid_1\"`, `numbers` as an array of `{\"number\", \"price\"}` objects copied from the search (`price` is the monthly price) and an optional `description`. The request is recorded and opens a ticket with NUACOM's number team, who contact the requesting user to complete the purchase; the call itself provisions nothing. It answers `200` with `{\"status\": \"success\", \"numbers\": [...]}` echoing the array, or `400` with `{\"status\": \"error\"}` when the request could not be recorded.\n5. **Search the stock**: [`GET /v2/numbers/search`](/v2/ref#/operations/numbers.search) takes `category` (`free`, `paid_1`, `paid_2` or `paid_3`), optional `iso` (ISO 3166-1 alpha-2) and `number_contains` (2 to 20 digits, optional leading `+`). `free` lists numbers NUACOM already holds in stock, ten per page as `{\"id\", \"number\"}` rows in `data` with `current_page` and `next_page_url`, narrowed by dial code and area with `country_code` and `area_code`. The paid categories are the provider catalogues, answered as one array of rows with `number` (digits without `+`), `country_iso`, `area_name`, `prefix`, `features` (`sms` when the number supports SMS), `needs_registration`, `restriction_message`, the provider's `setup_price` and `monthly_price`, and the prices you pay, `setup_price_with_fee` and `monthly_price_with_fee`. Ordering a number from these results goes through the request flow above; the direct assignment the portal uses is not a public endpoint.\n6. **Registration**: when the chosen row has `needs_registration: true`, read [`GET /v2/numbers/get-requirements`](/v2/ref#/operations/numbers.getRequirements) with `category` (`paid_1` or `paid_2`) and `country_iso` first. For `paid_1` it answers `address_area_level`, `business_area_level`, `business_mandatory_fields`, `service_description_required`, `proof_types`, `business_permanent_document`, `business_onetime_document`, `restriction_message` and `country`. Send the assign request as `multipart/form-data` with `company_name`, `first_name`, `last_name`, `phone_number`, `address[country_iso]`, `address[city_name]`, `address[postal_code]`, `address[address]`, `service_description` when required, every field named in `business_mandatory_fields`, and the documents: `proofs[0][type]` (an id from [`GET /v2/numbers/proof-types`](/v2/ref#/operations/numbers.getProofTypes)) with `proofs[0][files][]`, and `supporting_documents[0][template]` (an id from [`GET /v2/numbers/supporting-document-types`](/v2/ref#/operations/numbers.getSupportingDocuments); `permanent` says whether the document stays on file) with `supporting_documents[0][files][]`. The provider verifies the address after the order and NUACOM records that verification against the number.\n\n## Roles and access\n\n- Any authenticated user: `GET /v2/my-numbers`, `GET /v2/numbers/search`, `GET /v2/numbers/get-requirements`, `GET /v2/numbers/proof-types` and `GET /v2/numbers/supporting-document-types`.\n- Account admin (`403` otherwise): the three `/v2/numbers/order/...` endpoints.\n\n## Pitfalls\n\n- `GET /v2/my-numbers` is the only list of the account's numbers and it holds two fields. Numbers are digits without `+`; the search endpoints answer them with `+` (order search) or without (direct search).\n- `category` differs per endpoint: the order endpoints accept only `paid_1`, `get-requirements` accepts `paid_1` and `paid_2`, search and assign accept `free`, `paid_1`, `paid_2` and `paid_3`. Any other value is `422`.\n- The order search returns at most 20 numbers and silently leaves out numbers whose setup price, fee included, is above 5. An `areaCode` that matches nothing is ignored and the whole country is searched; an unknown `iso` answers `200` with `[]`, not `422`.\n- `numbers` on the order request must be objects with `number` and `price`; plain strings answer `400`. The request is a ticket, not a purchase: the numbers reach `GET /v2/my-numbers` only once NUACOM completes the order.\n- When `address_area_level` is `Area`, `address[country_iso]` must equal the number's country (`422`).\n- Monthly prices on the order endpoints and the `*_with_fee` prices on the direct search include NUACOM's fee and are rounded up to a multiple of 5; `setup_price` and `monthly_price` on the direct search are the provider's raw prices.\n- `number_contains` takes 2 to 20 digits; a leading `+` is accepted and stripped; wildcards and letters answer `422`. The `free` search is simple pagination without a total: follow `next_page_url`." }, { "name": "Number Blocking", "description": "Number Blocking stops calls before they are placed or delivered, with two kinds of rules. **Destination rules** block a whole call class of the account's rate plan (a country, a number range or a service type, identified by a dial-prefix mask) for some or all extensions; they are the `/v2/calls-block-unblock` family and need an account admin. **Blocked numbers** block one phone number, inbound and/or outbound, for the whole account; they are `/v3/number-blocking`. The neighbouring Blacklist Numbers group is not about calls: it is the messaging block list, described at the end of this guide.\n\n## Workflow (what the portal does)\n\n1. **Destination rules**: [`GET /v2/calls-block-unblock`](/v2/ref#/operations/calls-block-unblock.index) with `page` and `perPage` (both required; `perPage` is 15, 25, 50, 100 or -1), `sort` (`name` by default, `-name` for descending), `filter[sSearch]` (a substring of the destination name or of its prefix mask) and `extension` (comma-separated extension numbers; the status of each destination is then computed for those extensions only, otherwise for every extension of the account). The answer is DataTables-shaped: `aaData[]` rows with `class_id` (one or more comma-separated destination ids that share a name), `class_name`, `class_mask` (the dialled-prefix pattern, such as `^00`) and `blocked`, which is `1` when blocked for every extension considered, `0` when allowed and `-1` when blocked for some of them; `iTotalRecords` and `iTotalDisplayRecords` carry the total.\n2. **Block or unblock**: [`POST /v2/calls-block-unblock`](/v2/ref#/operations/calls-block-unblock.store) with `action` (`0` to block, `1` to unblock), `extensions` (comma-separated extension numbers, each of which must exist on the account) and `destinations` (comma-separated `class_id` values from the list; pass a row's whole `class_id` string). Both are optional and the four combinations differ: both filled applies the action to those destinations for those extensions; `destinations` alone to those destinations for every extension; `extensions` alone to every destination for those extensions; neither to every destination for every extension, that is, block all or unblock all. The answer is `204`; read the list again to see the resulting status.\n3. **Copy rules between extensions** is a portal action (**Call Blocking \u2192 Copy rules**); through the API, create the same rules on each extension.\n4. **Blocked numbers**: [`GET /v3/number-blocking`](/v2/ref#/operations/v3.number-blocking.index) with `page` and `perPage` (both required; 15, 25, 50 or 100), `filter[search]` (a substring of the number or of the notes) and `sort` (`phone_number` by default, `inbound`, `outbound` or `notes`, `-` for descending). A standard paginated answer: `data[]` rows of `{\"entry_id\", \"phone_number\", \"inbound\", \"outbound\", \"notes\"}` with `links` and `meta` (`total`, `per_page`, `current_page`, `last_page`).\n5. **Add a blocked number**: [`POST /v3/number-blocking`](/v2/ref#/operations/v3.number-blocking.store) with `phone_number` (up to 20 characters, unique within the account), `inbound` and `outbound` (booleans: refuse calls from the number, refuse calls to it) and optional `notes`. The answer is `204` with no body: list again to learn the `entry_id`.\n6. **Edit or remove**: [`PUT /v3/number-blocking/{entryId}`](/v2/ref#/operations/v3.number-blocking.update) takes the same fields as the create (`phone_number` is required again; a flag you leave out keeps its value) and [`DELETE /v3/number-blocking/{entryId}`](/v2/ref#/operations/v3.number-blocking.destroy) removes the entry. Both answer `204`; an id that does not belong to the account answers `404`.\n\n## Blacklist Numbers\n\nThe Blacklist Numbers group is the account's messaging block list, not a call rule: a number on it is never sent an SMS, MMS or WhatsApp message by the account. A send to it is created with status `4` (failed), `error_code` `BLOCKED` and the description `Recipient is blocked or opted out` (see [Conversations](/v2/docs/groups/conversations)), and the number shows `sms_blocked: true` on a contact's phones in [Contacts](/v2/docs/groups/contacts). Calls are not affected; use the blocked numbers above for that. [`GET /v3/blacklist-numbers`](/v2/ref#/operations/v3.blacklist-numbers.index) lists the manually blocked numbers as `{\"id\", \"mobile_number\", \"account\", \"status\", \"notes\", \"entrydate\"}`; [`POST /v3/blacklist-numbers`](/v2/ref#/operations/v3.blacklist-numbers.store) with `mobile_number` (up to 20 characters) and optional `notes` (up to 50) answers `201` with the row, or `204` when it was already blocked; [`GET /v3/blacklist-numbers/{mobileNumber}`](/v2/ref#/operations/v3.blacklist-numbers.show) answers the row, or `204` when the number is not blocked; [`DELETE /v3/blacklist-numbers/{mobileNumber}`](/v2/ref#/operations/v3.blacklist-numbers.destroy) unblocks it (`204`). `status` is `2` for a number blocked through this endpoint and `3` for a number that opted out of the account's messages; only `2` rows are listed, shown and deleted here, but both stop sends, and a `POST` for an opted-out number turns it into a `2` row.\n\n## Roles and access\n\n- The destination rules (list, block or unblock) need an **account admin**; other users get `403`.\n- Blocked numbers (`/v3/number-blocking`) and the blacklist (`/v3/blacklist-numbers`) are open to any authenticated user of the account.\n\n## Pitfalls\n\n- `action` is the opposite of what the name suggests: `0` blocks, `1` unblocks.\n- There is no `all` keyword on the block call: `extensions=all` answers `422` with `One or more extensions are invalid.`, and `destinations` has no such value either. Leave the field out, or send it empty, to mean \"all\".\n- `blocked` in the list is an integer, not a boolean, and `-1` (partially blocked) appears whenever only some of the extensions considered are blocked. Pass `extension` to get the answer for specific extensions.\n- A row's `class_id` can hold several ids (`12,13`). Send that whole string in `destinations`; the ids grouped under one name are one destination to the portal.\n- Both lists require `page` and `perPage` (`422` without them); an unknown `filter[...]` or `sort` answers `400`. The `/v3/number-blocking` list has no `-1` page size.\n- `POST /v3/number-blocking` returns no id, and `inbound` and `outbound` you leave out are stored as `null`, not `false`: send both flags explicitly.\n- `phone_number` on `/v3/number-blocking` is stored exactly as sent and the uniqueness check is an exact string match, so `+353861234567` and `00353861234567` are two entries. Use one format consistently.\n- Blacklist a number as `00` followed by the country code and number (`00353861234567`): that is the form the send-time check compares against. A copy with a `+` or in national format is listed but may not stop the send.\n- `GET /v3/blacklist-numbers/{mobileNumber}` and the delete ignore opted-out rows (`status` `3`): the check answers `204` for them and the delete leaves them in place." }, { "name": "Blacklist Numbers" }, { "name": "Marked Mobile Numbers" }, { "name": "IVR", "description": "An IVR (auto-attendant) menu plays a greeting and routes the caller by the key they press, with separate behaviour for open hours, closed hours and the case where no key is pressed. In V2 this group is a single operation, [`PUT /v2/ivr/{id}/menu`](/v2/ref#/operations/v2.ivrMenu), which **replaces the whole configuration** of IVR `{id}`. Listing, creating and deleting IVRs is still done through V1 (`GET /v1/ivr_menu`, `POST /v1/ivr_menu_new`, `DELETE /v1/ivr_menu/{id}`), and an IVR is attached to a number in the portal under Numbers & Inbound Call Routing.\n\n## Workflow (what the portal does)\n\n1. `GET /v1/ivr_menu` returns every IVR with its `name` and a `data` object in exactly the shape the PUT expects. Edit that object rather than building one from scratch.\n2. Collect the identifiers your actions will point at:\n - announcement slots 10\u201399, uploaded with [`POST /v2/announcements/upload-audio`](/v2/ref#/operations/announcements.uploadAudio) (account admin);\n - extension numbers from [`GET /v2/extensions`](/v2/ref#/operations/extensions.index);\n - **queue numbers** (not queue ids) from [`GET /v2/queues`](/v2/ref#/operations/queues.index);\n - SMS template ids from [`GET /v2/sms-templates`](/v2/ref#/operations/sms-templates.index) for \"send a message\";\n - call tag ids, other IVR ids, or a phone number for \"forward\".\n3. Build `data`:\n - `options_msg_enabled`: whether digits 0\u20139 are offered at all.\n - `initial.ring_duration` (0\u201330 seconds) and `initial.message` (an announcement slot): what happens before the menu.\n - `open.message`, `open.pause` (seconds to wait for a key: 0.1, 0.5, 1\u202620, 25 or 30), `open.actions` (exactly ten entries, digits 0\u20139) and `open.fall_through` (no key pressed).\n - `close.actions` for out-of-hours calls and, when its first action is \"play message\" (`1`), `close.on_event_actions` for a key pressed during that message.\n - Every action is `{\"action_1\": {\"id\", \"value\"}, \"action_2\": {\"id\", \"value\"}}`. `value` is always a string of at most 50 characters: an extension number, a queue number, an announcement slot, an IVR id, a phone number, comma-separated tag ids or a template id.\n4. `PUT /v2/ivr/{id}/menu` with `name` and `data`. `204` means saved, and the change is live for the next call: there is no provisioning step.\n5. Opening hours and holidays live outside this group and take `menu_id` = the IVR id: opening hours through V1 (`PATCH /v1/opening_hours`), public holidays with [`PATCH /v2/ivr/public_holiday_settings`](/v2/ref#/operations/publicHolidaySettings.update) and custom holidays with [`PATCH /v2/ivr/custom_holiday_settings`](/v2/ref#/operations/customHolidaySettings.update).\n\n## Actions\n\n- First action (`action_1.id`): `0` hang up, `1` play message, `2` dial extension, `3` join queue, `4` play prompt then dial the entered number, `6` voicemail, `7` repeat the options, `8` forward to a number, `9` go to another IVR, `13` add a call tag, `14` send a message.\n- Second action (`action_2.id`): `0` none, `1` dial extension, `2` join queue, `4` dial the entered number, `5` fall through, `6` voicemail, `8` forward, `9` go to another IVR, `14` send a message.\n- Chaining: after `1`, `3` or `13` any second action is allowed; after `4` only `4` or `14`; after everything else `action_2.id` must be `0`. The fall-through slot has no second action `5`; the closed slot has no first action `7`.\n\n## Call routing\n\n```mermaid\nflowchart TD\n call[\"Incoming call\"] --> initial[\"initial.ring_duration + initial.message\"]\n initial --> hours{\"Open hours?\"}\n hours -- \"open\" --> menu[\"open.message, open.pause\"]\n menu -- \"digit 0-9 pressed\" --> actions[\"open.actions[digit]: action_1 (+ chained action_2)\"]\n menu -- \"no key pressed\" --> fall[\"open.fall_through\"]\n hours -- \"closed or holiday\" --> close[\"close.actions\"]\n close -- \"action_1.id 1 (play message)\" --> event[\"close.on_event_actions on keypress\"]\n actions --> terminal[\"Terminal action: hang up, dial extension/queue, voicemail, forward, another IVR, add tag, send message\"]\n fall --> terminal\n close --> terminal\n event --> terminal\n```\n\n## Roles and access\n\n- Account admin only (`403` otherwise).\n\n## Pitfalls\n\n- Full replacement: leave out `name` and the IVR is renamed to an empty string; a digit whose two actions are both `0` is removed; with `options_msg_enabled: false` the digits 0\u20139 are left as they were.\n- Validation checks every `id` against the allowed list but not the chaining rules: an unchainable pair such as `4` followed by `0` fails with `500`, not `422`.\n- References are not checked to exist. A wrong slot, extension, queue number or template id only shows up when a caller reaches it.\n- `open.actions` must be a list of exactly ten entries for digits 0\u20139. An object keyed 1\u201310 passes the size check and then fails.\n- `{id}` accepts 1\u2013127 and creates the configuration row when it is missing, but IVRs themselves are only created through V1 (ids 1\u201331). Use ids you got from the list.\n- `initial.message` and `open.message` are integers 10\u201399; an empty string is treated as \"no message\"." }, { "name": "Holiday Settings", "description": "Holiday settings tell an IVR what to do with a call on a day the business is closed. Each IVR can have one **public holiday** rule, applied on every national holiday of the country chosen for that IVR, and any number of **custom** rules, each a single from\u2013to period in the IVR's own timezone. This group holds the public holiday calendar (by country, or grouped by IVR), the public holiday rule (list, update, clear) and the custom rules (list, update, delete, clear). The IVR itself, including the out-of-hours actions a holiday rule can hand the call to, is configured in [IVR](/v2/docs/groups/ivr).\n\n## Workflow (what the portal does)\n\n1. **IVRs and their public holiday rule**: [`GET /v2/ivr/public_holiday_settings`](/v2/ref#/operations/publicHolidaySettings.index) answers an object keyed by IVR id. Each entry has `ivr` (`id`, `name`, `pub_holiday_country`) and `action`: the rule's `id`, `menu_id`, `first_action`, `first_action_data`, `second_action` and `second_action_data`, or only `menu_id` with `first_action` and `first_action_data` set to `null` when the IVR has no rule.\n2. **The calendar**: [`GET /v2/public_holidays/{countryCode}`](/v2/ref#/operations/publicHolidays.index) lists the upcoming national holidays of a country (ISO 3166-1 alpha-2, upper case; `GB` also returns the rows filed under `UK`), oldest first: `id`, `calendar_date` (`Y-m-d H:i:s`, at midnight), `country`, `menu_time_zone`, `holiday_name`, `holiday_description` and `holiday_type` (always `National holiday`). [`GET /v2/public_holidays_by_ivr`](/v2/ref#/operations/publicHolidays.byIvr) answers the same rows grouped by IVR id, for the country each IVR is set to, past dates included; an IVR without a country gets `[]`.\n3. **Set the public holiday rule**: [`PATCH /v2/ivr/public_holiday_settings`](/v2/ref#/operations/publicHolidaySettings.update) with one JSON object: `menu_id` (the IVR id), `first_action`, the optional `first_action_data`, `second_action` and `second_action_data`, and `pub_holiday_country` to set or change the IVR's country in the same call. Send the rule's `id` from step 1 when the IVR already has one. Answers `204`.\n4. **Custom rules**: [`GET /v2/ivr/custom_holiday_settings`](/v2/ref#/operations/customHolidaySettings.index) answers an object keyed by IVR id with `ivr` (`id`, `name`, `time_zone`) and `rules`, each with `id`, `menu_id`, `from_time`, `to_time`, the four action fields and `time_zone`.\n5. **Add or change custom rules**: [`PATCH /v2/ivr/custom_holiday_settings`](/v2/ref#/operations/customHolidaySettings.update) with a JSON **array** of rules, each with `menu_id`, `from_time`, `to_time`, `menu_time_zone` (an IANA name such as `Europe/Dublin`), `first_action` and the optional `first_action_data`, `second_action` and `second_action_data`. Add `id` to change an existing rule, leave it out to add one. Rules are saved one by one, in the order sent. Answers `204`.\n6. **Remove rules**: [`DELETE /v2/ivr/custom_holiday_settings/{id}`](/v2/ref#/operations/customHolidaySettings.remove) deletes one custom rule (`404` when it is not one of the account's); [`DELETE /v2/ivr/{ivrId}/custom_holiday_settings`](/v2/ref#/operations/customHolidaySettings.clearByIvr) deletes every custom rule of an IVR; [`DELETE /v2/ivr/{ivrId}/public_holiday_settings`](/v2/ref#/operations/publicHolidaySettings.clearByIvr) deletes the IVR's public holiday rule and leaves `pub_holiday_country` as it is. All answer `204`, also when there was nothing to delete.\n\n```bash\n# Irish public holidays on IVR 1: play announcement slot 12, then hang up\ncurl -X PATCH https://api.api-nuacom.com/v2/ivr/public_holiday_settings \\\n -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"menu_id\": 1, \"pub_holiday_country\": \"IE\", \"first_action\": 1, \"first_action_data\": \"12\", \"second_action\": 0, \"second_action_data\": null}'\n# \u2192 204\n\n# Closed from Christmas Eve lunchtime to the end of St Stephen's Day: out-of-hours routing\ncurl -X PATCH https://api.api-nuacom.com/v2/ivr/custom_holiday_settings \\\n -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '[{\"menu_id\": 1, \"from_time\": \"2026-12-24 13:00:00\", \"to_time\": \"2026-12-26 23:59:59\", \"menu_time_zone\": \"Europe/Dublin\", \"first_action\": 0, \"first_action_data\": null, \"second_action\": null, \"second_action_data\": null}]'\n# \u2192 204\n```\n\nThe custom rule then reads back like this (ISO contract; Dublin is `+00:00` in December):\n\n```json\n{\n \"1\": {\n \"ivr\": {\"id\": 1, \"name\": \"Main Call Flow\", \"time_zone\": \"Europe/Dublin\"},\n \"rules\": [\n {\"id\": 57, \"menu_id\": 1, \"from_time\": \"2026-12-24T13:00:00+00:00\", \"to_time\": \"2026-12-26T23:59:59+00:00\", \"first_action\": 0, \"first_action_data\": null, \"second_action\": null, \"second_action_data\": null, \"time_zone\": \"Europe/Dublin\"}\n ]\n }\n}\n```\n\n## Actions\n\nOn a day the public holiday rule matches, or during the period of a custom rule, the IVR runs the rule's actions instead of its open-hours flow: `first_action` with `first_action_data`, then `second_action` with `second_action_data` where the first action chains. The ids and the data are the IVR's own action vocabulary (see Actions in [IVR](/v2/docs/groups/ivr)); the data is a string of at most 50 characters.\n\n| `first_action` | What happens | `first_action_data` |\n|---|---|---|\n| `0` | Go to out of hours: the call takes the IVR's closed-hours actions | \u2013 |\n| `1` | Play a message | announcement slot 10\u201399, uploaded with [`POST /v2/announcements/upload-audio`](/v2/ref#/operations/announcements.uploadAudio) |\n| `2` | Dial an extension | extension number, from [`GET /v2/extensions`](/v2/ref#/operations/extensions.index) |\n| `3` | Join a queue | queue number (not the queue id), from [`GET /v2/queues`](/v2/ref#/operations/queues.index) |\n| `4` | Play a prompt, then dial the number the caller enters | announcement slot |\n| `6` | Go to voicemail | mailbox number, from [`GET /v2/voicemail/mailbox_numbers`](/v2/ref#/operations/voicemail.mailboxNumbers) |\n| `8` | Forward to a number | phone number |\n| `9` | Go to another IVR | IVR id |\n| `13` | Add a call tag | tag ids, comma-separated, from [`GET /v3/call-tags`](/v2/ref#/operations/v3.call-tags.index) |\n\n`second_action`: `0` none (hang up), `1` dial an extension, `2` join a queue, `4` dial the number the caller entered, `5` fall through (the IVR's no-key action), `6` voicemail, `8` forward to a number, `9` go to another IVR; `second_action_data` carries the matching value. The portal offers a second action after `1`, `3` and `13` (any of them except `4`) and after `4` (only `4`); after every other first action it sends `second_action` as `null`.\n\n## How a holiday rule overrides the IVR\n\n```mermaid\nflowchart TD\n call[\"Call arrives at the IVR\"] --> match{\"Does today match a public holiday
(IVR's country) or a custom from_time/to_time period?\"}\n match -- \"yes\" --> rule[\"Run the matching rule's first_action / first_action_data,
then second_action / second_action_data\"]\n match -- \"no\" --> normal[\"IVR's normal open.actions flow\"]\n rule -- \"first_action 0 (go to out of hours)\" --> closed[\"IVR's close.actions\"]\n```\n\n## Dates and timezones\n\n- A custom rule is one period, `from_time` to `to_time`, read as wall-clock times in `menu_time_zone`. Send `Y-m-d H:i:s`; a bare `Y-m-d` means midnight, so a one-day closure is `2026-12-25 00:00:00` to `2026-12-25 23:59:59`. Other date-time spellings are parsed, but an offset in the value is dropped rather than applied, and `X-Timezone` plays no part.\n- There is no recurrence: a custom rule covers its dates once, so a closure that repeats every year needs a new rule each year. Public holidays recur on their own: the public holiday rule applies to every national holiday in the calendar of the IVR's country, and the API has no way to leave individual days out.\n- In the custom list, `from_time` and `to_time` follow the account's date contract (see [Dates and timezones](/v2/docs/dates-and-timezones)). On the legacy contract they are `2026-12-24T13:00:00.000000Z`: the wall-clock time with a `Z` that does not mean UTC. On the ISO contract they are `2026-12-24T13:00:00+00:00`, with the offset of the IVR's timezone, never the one in `X-Timezone`. `calendar_date` on the calendar endpoints is `Y-m-d H:i:s` at midnight on both contracts.\n- `ivr.time_zone` in the custom list is the timezone of the IVR's first rule, or the account's timezone when the IVR has no rule. [`GET /v3/time-zones`](/v2/ref#/operations/v3.getTimezones) lists the IANA names.\n\n## Roles and access\n\n- Reading, that is both settings lists and both calendar endpoints, is open to any authenticated user of the account. Every `PATCH` and `DELETE` needs an account admin; any other user gets `403` with the body `\"Forbidden\"`.\n- The ISO dates option only changes the format of `from_time` and `to_time`.\n\n## Pitfalls\n\n- The settings lists and the by-IVR calendar are JSON objects keyed by IVR id; an account without IVRs gets `[]`.\n- Send `id` when changing the public holiday rule. A `PATCH` without `id` always inserts, and the list shows only the first rule of each IVR, so the extra row is invisible; `DELETE /v2/ivr/{ivrId}/public_holiday_settings` removes them all.\n- An `id` that is not one of the account's rules answers `500` on the public holiday `PATCH` and `404` on the custom `PATCH`; in the custom case the rules before it in the array are already saved, as there is no transaction.\n- `menu_id` must be one of the account's IVRs (`422` otherwise), but action ids and data are stored as sent: a wrong id, slot, extension or queue number only shows when a call reaches the rule.\n- `menu_time_zone` is required but not checked against the IANA list. An invalid name is stored, and on the ISO contract the custom list then fails.\n- `from_time` and `to_time` are not compared with each other or with other rules: a period that ends before it starts, or overlaps another rule, is accepted.\n- `pub_holiday_country` cannot be emptied: `null` or `\"\"` is ignored. To stop public holiday routing on an IVR, clear its rule.\n- `GET /v2/public_holidays/{countryCode}` lists dates from the current moment, so today's holiday has already dropped off it; `GET /v2/public_holidays_by_ivr` includes past dates. Both list national holidays only, and an unknown country answers `[]`.\n- `GB` is merged with `UK` on the country endpoint only; an IVR's `pub_holiday_country` must be exactly the `country` its calendar rows carry." }, { "name": "Announcements" }, { "name": "Softphone Announcements", "description": "Softphone announcements are audio clips an agent can play into a live call from the NUACOM softphone. Each one has a `name`, a `description`, one audio file (MP3, WAV or OGG) and a `duration`. This group holds the list, one announcement, create, update (JSON on `PUT`, multipart on `POST`), delete and the audio download. They are not the announcements IVRs and queues play: those are announcement slots uploaded with [`POST /v2/announcements/upload-audio`](/v2/ref#/operations/announcements.uploadAudio) and described in [IVR](/v2/docs/groups/ivr).\n\n## Workflow (what the portal does)\n\n1. **List**: [`GET /v2/softphone-announcements`](/v2/ref#/operations/softphone-announcements.index) answers every announcement of the account as an array of `{id, account_id, name, description, filename, size, duration}`; no paging and no filters. `size` is in bytes; `filename` is the storage name the API generated, not the name you uploaded.\n2. **Create**: [`POST /v2/softphone-announcements`](/v2/ref#/operations/softphone-announcements.store) as `multipart/form-data` with `name` (1\u201325 characters), `description` (up to 150 characters, optional), the audio as `file` (MP3, WAV or OGG) or as `base64_file` (a data URI, see below), and `duration`, the clip length in seconds, required whenever audio is sent. Answers `201` with the announcement. An account holds at most 100 announcements.\n3. **Edit the text**: [`PUT /v2/softphone-announcements/{id}`](/v2/ref#/operations/softphone-announcements.update) with a JSON body carrying any of `name`, `description` and `duration`; keys you leave out keep their value. Answers `204`, or `404` when the id is not one of the account's.\n4. **Replace the audio**: a file travels as `multipart/form-data`, which PHP does not read on `PUT`, so the portal sends it with [`POST /v2/softphone-announcements/{id}`](/v2/ref#/operations/softphone-announcements.updateWithAudio): `file` plus `duration`, and optionally `name` and `description`. It is the same operation as the `PUT`, which can replace the audio too, through `base64_file` in the JSON body. The previous file is deleted. Answers `204`.\n5. **Play or download**: [`GET /v2/softphone-announcements/{id}/audio`](/v2/ref#/operations/v2.softphoneAnnouncementAudio) answers the audio bytes with `Content-Type`, `Content-Length` and `Content-Disposition: attachment; filename=\"\u2026\"`; `404` when the announcement, or its file, does not exist. [`GET /v2/softphone-announcements/{id}`](/v2/ref#/operations/softphone-announcements.show) answers the record alone.\n6. **Delete**: [`DELETE /v2/softphone-announcements/{id}`](/v2/ref#/operations/softphone-announcements.destroy) removes the record and its file. `204`, or `404`.\n\nAfter a create or an update the account's connected softphones are notified of the change; the notification is best-effort and never fails the request.\n\n```bash\n# Create from an MP3 file\ncurl -X POST https://api.api-nuacom.com/v2/softphone-announcements \\\n -H 'Authorization: Bearer YOUR_API_KEY' \\\n -F 'name=Call recording notice' \\\n -F 'description=Played before taking card details' \\\n -F 'file=@recording-notice.mp3' \\\n -F 'duration=12'\n# \u2192 201 {\"id\": 41, \"account_id\": \"IE-00123\", \"name\": \"Call recording notice\", \"description\": \"Played before taking card details\", \"filename\": \"IE-00123-6901a1b2c3d4e.mp3\", \"size\": 196608, \"duration\": 12}\n\n# Rename it\ncurl -X PUT https://api.api-nuacom.com/v2/softphone-announcements/41 \\\n -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"name\": \"Recording notice\"}'\n# \u2192 204\n\n# Replace the audio: POST, not PUT\ncurl -X POST https://api.api-nuacom.com/v2/softphone-announcements/41 \\\n -H 'Authorization: Bearer YOUR_API_KEY' \\\n -F 'file=@recording-notice-v2.wav' -F 'duration=14'\n# \u2192 204\n\n# Download it\ncurl -o notice.wav https://api.api-nuacom.com/v2/softphone-announcements/41/audio \\\n -H 'Authorization: Bearer YOUR_API_KEY'\n```\n\n## Audio formats and limits\n\n| Input | Accepted | Notes |\n|---|---|---|\n| `file` (multipart) | MP3, WAV, OGG | Checked on the content, not on the file name; the stored name gets the extension the content implies |\n| `base64_file` | `data:audio/wav;base64,\u2026`, `data:audio/mpeg;base64,\u2026`, `data:audio/ogg;base64,\u2026` | The declared type must match the content (`audio/x-wav` and the other `x-` spellings count as the same type); anything that looks like a URL or a file path is rejected; the stored file is always named `.wav` |\n\n- `name`: 1\u201325 characters. `description`: up to 150 characters; stored as `\"\"` when left out on create.\n- `duration`: a number, required whenever `file` or `base64_file` is sent; the API stores and returns it as a whole number and does not check it against the audio.\n- No maximum file size is validated by the API.\n- At most 100 announcements per account.\n\n## Roles and access\n\n- Every endpoint in this group is open to any authenticated user of the account; none requires an account admin.\n\n## Pitfalls\n\n- `GET /v2/softphone-announcements/{id}` answers `200` with `{}` for an id that is not one of the account's; the update, delete and audio endpoints answer `404`.\n- The 101st announcement is refused with `500`, not `422`.\n- A multipart body on `PUT` is ignored: the request answers `204` and changes nothing. Send files with `POST /v2/softphone-announcements/{id}`.\n- `duration` is required with `file` and `base64_file` (`422` otherwise), on an update as well as on create.\n- When both `file` and `base64_file` are sent, `file` is used.\n- A base64 upload is stored as `.wav` whatever audio type the data URI declares; prefer multipart for MP3 and OGG.\n- Deleting does not notify the softphones; creating and updating do.\n- The download is served as an attachment under the stored file name, not the one you uploaded." }, { "name": "Queues", "description": "A queue holds inbound calls and rings its agents \u2014 extensions, each with a priority and an order \u2014 by a ring strategy until one answers or the timeout action fires. This group lists the account's queues ([`GET /v2/queues`](/v2/ref#/operations/queues.index), [`GET /v3/queues`](/v2/ref#/operations/v3.queues.index)), adds and removes agents, and reports on dynamic agents and on today's outbound activity. Queues themselves are created, configured and deleted in the portal. Logging a dynamic agent in or out is [`POST /v2/extensions/set-dynamic-agent-queue-status`](/v2/ref#/operations/extensions.updateDynamicAgentQueueStatus) in the [Extensions](/v2/docs/groups/extensions) group, and routing an IVR key to a queue is described in [IVR](/v2/docs/groups/ivr).\n\n## Workflow (what the portal does)\n\n1. **List**: [`GET /v3/queues`](/v2/ref#/operations/v3.queues.index) answers a plain array of `{\"id\", \"name\", \"number\", \"description\"}` ordered by number \u2014 enough for pickers. [`GET /v2/queues`](/v2/ref#/operations/queues.index) returns the same queues in full: `agents` (the member count), `agents_description` (one entry per member: `extension`, `name`, `priority`, `order`, `is_dynamic`), `queue_config` and `can_delete`. With `basic=true` it answers only `queue_id`, `queue_number`, `queue_name` and `queue_desc`.\n2. **Agents**: [`POST /v2/account-queue-headset`](/v2/ref#/operations/account-queue-headset.store) with `queue_number`, `extension_number` and optional `priority` (0\u201359, default 0), `order` (0 or more, default 0) and `is_dynamic` (boolean, default `false`) adds the extension to the queue, or updates those three settings when it is already a member, and answers `202` with the membership row `{\"account_id\", \"queue_id\", \"extension_number\", \"priority\", \"order\", \"is_dynamic\"}`. [`DELETE /v2/account-queue-headset/{account_queue_headset}`](/v2/ref#/operations/account-queue-headset.destroy) with `queue_number` and `extension_number` in the query string removes it (`204`). [`GET /v2/account-queue-headset`](/v2/ref#/operations/account-queue-headset.index) lists the memberships of the **caller's own** extension, each with its `queue` (`name`, `number`, `description`); it answers `400` when the caller has no extension in the account.\n3. **Dynamic agents**: a member with `is_dynamic` is a dynamic agent \u2014 one who logs in to and out of the queue instead of being rung permanently. [`POST /v2/extensions/set-dynamic-agent-queue-status`](/v2/ref#/operations/extensions.updateDynamicAgentQueueStatus) with `queue` (queue number), `extension` (extension number) and `action` (`login` or `logoff`) changes that state. It answers `200` with `{\"status\": \"success\", \"message\": \"Agent login\"}`, or `200` with `{\"error\": true, \"message\": \"Agent was not changed\", \"description\": \"\u2026\"}` when the change could not be applied.\n4. **Dynamic-agent reports**:\n - [`GET /v2/queue-dynamic-agents`](/v2/ref#/operations/v2.getQueueDynamicAgents) is the login/logoff log, paginated. `page` and `perPage` (`15`, `25`, `50` or `100`) are required; `sort` takes `id`, `ext`, `queue`, `action`, `user_name`, `platform` or `date`, with a `-` prefix for descending (`-date` by default); the filters are `filter[ext]`, `filter[queue]` (queue number), `filter[action]` (`1` login, `0` logoff), `filter[user_name]`, `filter[platform]` (`1` Wallboard, `2` Apps, `3` Shortcode) and `filter[date]` as two Unix timestamps `from-to`. Each row is `id`, `date`, `account`, `ext`, `queue`, `action`, `user_id`, `user_name`, `platform` and `platform_name`; next to `data`, `links` and `meta` the response adds `agents` (extension number \u2192 extension name) and `queues` (the queue numbers that appear in the log).\n - [`GET /v2/queue-dynamic-agents/status`](/v2/ref#/operations/v2.getQueueStatus) is the current state: for every extension-and-queue pair whose latest event is a login, that event, newest first \u2014 who is logged in where right now.\n6. **Related endpoints in other groups**: [`GET /v2/reports/queue-skipped-calls`](/v2/ref#/operations/v2.getQueueSkippedCalls) (Reports) lists the calls an agent did not pick up in a `queue` between `from` and `to`, optionally for one `agent` extension; [`GET /v2/call-log-queues`](/v2/ref#/operations/callLog.callLogAllowedQueues) (Call Logs) lists the queues the caller may filter call logs by, keyed by queue number.\n\n## Reading a queue\n\n`queue_config` in `GET /v2/queues` is the queue's behaviour:\n\n- `ring_strategy`: `ringall`, `leastrecent`, `fewestcalls`, `random`, `rrmemory`, `linear` or `wrandom`; `ring_agent_timeout` is the seconds each agent rings before the next one is tried, `ring_in_use` whether an agent already on a call is rung, `wrap_up_time` the seconds an agent is left alone after a call.\n- `timeout_in` is the seconds a caller waits before `timeout_action` fires: `0` ring an outside number, `1` continue, `2` backup call, `3` hang up, `4` option call, `5` option to voicemail, `6` dial an extension or shortcode, `7` voicemail, `8` another queue, `9` an IVR. `timeout_action_value` is the target (a number, extension, mailbox, queue id or IVR id); `backup_type` and `backup_value` describe the backup call.\n- `callee_announcement`, `periodic_announcement`, `announce_position` and `announce_position_frequency` are the caller-side announcements, `moh_class` the music on hold, `show_queue_name` whether the queue description is prepended to the caller ID the agent sees.\n- `can_delete` is `{\"allowed\": true}` when nothing points at the queue; otherwise `message` lists the numbers, IVRs, queues, callback widgets, webhooks and after-call-work rules that still use it. Deleting is portal-only.\n\n## Numbers and ids\n\nEvery queue has two identifiers: an **id** (`id` / `queue_id`), unique across NUACOM, and a **number** (`number` / `queue_number`), short and unique within the account. Every input in the API takes the number: `queue_number` in the agent endpoints, `queue` in the dynamic-agent status endpoint and the skipped-calls report, `filter[queue]` in the log, the `queues` filter of the call log, the `queues` grant in a user's permissions and the \"join queue\" actions of an IVR (see [IVR](/v2/docs/groups/ivr)). The id is only returned, never required.\n\nA queue also has two labels, a short **name** (`sales`) and a **description** (`Sales Queue`), and the key that carries each differs by endpoint:\n\n| Endpoint | id | number | short name | description |\n|---|---|---|---|---|\n| `GET /v3/queues` | `id` | `number` | `name` | `description` |\n| `GET /v2/queues` | `id` (string) | `number` (string) | \u2014 | `name` |\n| `GET /v2/queues?basic=true` | `queue_id` | `queue_number` | `queue_name` | `queue_desc` |\n| `GET /v2/account-queue-headset`, `queue` object | \u2013 | `number` | `name` | `description` |\n| `GET /v2/call-log-queues` | \u2013 | `number` | `id` | `name` |\n\n## Roles and access\n\n- Listing queues and the three reports are open to any authenticated user. An account admin sees every queue; a regular user sees only the queues in the `queues` grant of their permissions (set by an admin in the portal's Users screen, see [Users](/v2/docs/groups/users)), and with no grant both lists are empty \u2014 `[]`, not `403` \u2014 even when the user has full call-log access. The reports are not filtered: they cover the whole account.\n- Adding and removing agents requires an account admin (`403` otherwise).\n- Logging a dynamic agent in or out: an admin for any extension, a regular user for their own extension only (`403` otherwise).\n- The ISO dates option does not change this group: `date` in the dynamic-agent reports is always `M j Y H:i:s` (`Jun 15 2020 10:37:51`) in the caller's profile timezone, and `X-Timezone` is ignored there.\n\n## Pitfalls\n\n- `name` is the description in `GET /v2/queues` and the short name in `GET /v3/queues` (table above). Key your data on `number` or `id`, never on a label.\n- `/v2/queues` returns `id`, `number`, `agents` and every `queue_config` value as strings (`\"600\"`); `/v3/queues` returns integers. `is_dynamic` is `0`/`1` in `agents_description` and `true`/`false` in the agent endpoints, and `agents_description[].id` just repeats `extension`.\n- `POST /v2/account-queue-headset` answers `202` whether it created the membership or updated an existing one, and re-posting overwrites `priority`, `order` and `is_dynamic`, which reset to `0`/`false` when omitted.\n- `extension_number` must be an extension linked to a user; an existing but unlinked extension is rejected with `422`.\n- The `{account_queue_headset}` path segment of the `DELETE` is ignored \u2014 any value works \u2014 and the parameters go in the query string, not the body.\n- `perPage=-1` (\"all\") passes validation on the dynamic-agent log but the query then fails with `500`; page with `100` instead.\n- `filter[date]` takes Unix timestamps (`1735689600-1738368000`) while `date` in the rows is formatted text; convert before comparing. `action` is `login`/`logoff` on input and `1`/`0` in the reports.\n- When a queue is in use, `can_delete` is `{\"success\": false, \" allowed\": false, \"message\": [...]}` \u2014 the key carries a leading space \u2014 so test for `allowed === true` rather than for `allowed === false`." }, { "name": "Speed Dial" }, { "name": "Call Logs", "description": "Call logs are the account's call history: one row per call leg with direction, numbers, extensions, queue, duration, cost, whether a recording exists, and the notes and tags attached to it. This group is the list itself; recordings, notes, tags and reports have their own groups and are described here because the portal always uses them together.\n\n## Workflow (what the portal does)\n\n1. **The list**: [`GET /v2/call-log`](/v2/ref#/operations/callLog.callLog) is the call history grid. Filters (all optional, comma-separated where several values are allowed):\n - `from_date` / `to_date` as `Y-m-d` or `Y-m-d H:i:s`, read in the `X-Timezone` you send (or the user's profile timezone). Send **both**; with only one, the last month is used.\n - `type`: `incoming`, `outgoing`, `missed`, `unanswered`, plus `include_voicemail`, `include_playback`, `include_internal`, `group_missed_calls`.\n - `numbers`, `incoming_number`, `outgoing_number`, `extensions`, `queues`, `tags` (tag ids), `notes` (substring), `search_for` (contact or extension name, or a number), `duration_above` / `duration_under`, `billsec_above` / `billsec_under` (seconds), `has_transcriptions`, `transcription`.\n - `page`, `per_page` (default 25, no maximum), `sort_by` (`call_date`, `from`, `from_ext`, `to`, `to_ext`), `sort_dir` (`DESC` by default).\n - The response is `{\"_embedded\": [rows], \"_links\": {\u2026}, \"page_count\": , \"page_size\", \"total_items\"}`. Lists of selectable extensions, numbers and queues for the user come with it in `_selectable`.\n2. **One call**: [`GET /v2/call-logs/{callId}`](/v2/ref#/operations/v2.getCallLogUnique) by `call_id` (or `call_unique_id`) returns the legs of that call as an array.\n3. **Recording**: build the URL yourself from the row, [`GET /v3/call-recording/{callId}`](/v2/ref#/operations/v3.callRecording) with the row's `call_id`; `format` picks MP3 (default), OGG or WAV, `start`/`end` trim it. Deleting is admin-only: [`DELETE /v2/call-recording/{callUniqueId}`](/v2/ref#/operations/call_recording.destroy).\n4. **Notes and tags on a call**: read them with [`GET /v2/call-notes?callIDs[]=\u2026`](/v2/ref#/operations/callLog.callNotes) and [`GET /v2/call-tags?callIDs[]=\u2026`](/v2/ref#/operations/callLog.callTags), passing the row's `call_id`, `sip_call_id` and `original_sip_call_id` together. Add a note with [`POST /v3/call-notes`](/v2/ref#/operations/v3.call-notes.store) (`callId`, `note`), assign a tag with [`POST /v2/add-call-tag`](/v2/ref#/operations/v2.addCallTag) (`call_id`, `tag_info_id`); the tag catalogue is [`GET /v3/call-tags`](/v2/ref#/operations/v3.call-tags.index).\n5. **Transcript**: [`GET /v2/speech-to-text/{callUniqueId}`](/v2/ref#/operations/speechToText.getCallSTT) when the account has transcription enabled.\n6. **Export**: [`GET /v2/call-log-export`](/v2/ref#/operations/callLog.callLogExport) takes the same filters as the list and answers `204`: the CSV is built in the background and emailed to the requesting user, normally within minutes. The job is allowed 15 minutes; past that it is abandoned, not retried, and the user receives a failure email instead, so request again with a narrower range. An export holds at most 100,000 rows: above that the request answers `422` with the row count and the limit in `message`, and nothing is queued. The six-month limit on the date range is a portal rule, not an API one. Dates in the file are in the `X-Timezone` you send, or the user's profile timezone without it.\n7. **Reports** (their own group): [missed calls](/v2/ref#/operations/callLog.missedCalls) (paginated, with [an export](/v2/ref#/operations/callLog.missedCallsExport)), [top callers](/v2/ref#/operations/callLog.topCallers), [busy hours](/v2/ref#/operations/callLog.hourlyBusyHours) by hour, [day](/v2/ref#/operations/callLog.dailyBusyHours) or [month](/v2/ref#/operations/callLog.monthlyBusyHours), and extension usage by [direction](/v2/ref#/operations/callLog.directionExtensionUsage) or [duration](/v2/ref#/operations/callLog.durationExtensionUsage). All take `from_date`, `to_date` and, where it applies, `extensions` or `type`.\n\n## Reading a row\n\n- `call_unique_id` is the row's own id; `call_id` is the telephony id shared by every leg of the same call (transfers, queue legs). Key your data on `call_unique_id`, look recordings up by `call_id`.\n- `direction` is `inbound`, `outbound` or `internal`; `type` adds `missed`, `unanswered`, `voicemail`, `playback`; `status` is `ANSWERED`, `NO ANSWER`, `BUSY` or `FAILED`.\n- Who is who depends on `direction`. Every number comes twice, `from` / `to` as stored and `from_local` / `to_local` in local format; pick one and show it consistently.\n - **inbound**: the caller is `from` (or `from_local`), named by `from_name` (`from_contact_id` is the matched phonebook contact, `from_name_source` says where the name came from); the number they dialled is `to` (or `to_local`) with `to_name`; the extension that took the call is `to_ext` with `to_ext_name`. On a missed call `to_ext` is empty.\n - **outbound**: the agent is `from_ext` with `from_ext_name`; the caller ID presented to the other side is `from` (or `from_local`) with `from_name`; the person called is `to` (or `to_local`) with `to_name` (`to_contact_id`).\n - **internal**: both sides are extensions, `from_ext` / `from_ext_name` and `to_ext` / `to_ext_name`.\n - For one user, a row whose `from_ext` is their extension is a call they made and a row whose `to_ext` is their extension is a call they received.\n- `billsec` is the connected time, `duration` the total time including ringing.\n- `recording` is `true` only when a recording exists **and** the user may listen to it.\n- `extra.call_tags` and `extra.call_notes` are included in the row; `transferred_child` lists the ids of the legs a transfer created (fetch them with `cdr_id=`).\n\n## Roles and access\n\n- Any authenticated user. An account admin, or a user whose call-log permission is \"all\", sees every call; everyone else sees only calls on their own extension and on the numbers, extensions and queues granted to them. With no grants the list is simply empty, not `403`.\n- Recording playback needs the same visibility and recording access (the account's recording add-on or subscription); otherwise `403`.\n- Deleting a recording and the admin missed-call export are admin-only.\n- The ISO dates option (per account) switches `call_date` and note timestamps to ISO 8601 in the requested timezone (UTC by default). Without it dates are `Y-m-d H:i:s` in the user's timezone.\n\n## Pitfalls\n\n- The generated reference does not list the list's filters, because they are read from the raw query string. Use the parameters described above.\n- `call_id` is **not unique**: transfer and queue legs share it. Use `call_unique_id` as the row key, and pass all three ids when reading notes and tags.\n- `page_count` is the current page, not the number of pages; paginate on `total_items` and `page_size`.\n- Choosing a direction in `type` excludes voicemail and playback rows unless you add `include_voicemail` / `include_playback`.\n- Send filters as comma-separated strings, not as `extensions[]` arrays.\n- Dates: an unparsable value silently becomes 1970-01-01; a value with a UTC offset is shifted. Send wall-clock times and set `X-Timezone`.\n- There is no server-side cap on the date range or `per_page`; the portals cap the range at six months. Recordings are kept for six months by default (longer with a retention add-on), so an older row with `recording: true` can still answer `404`.\n- Exports are asynchronous and arrive by email; the request itself returns no job id." }, { "name": "Call Recording", "description": "Call recordings are the audio files of recorded calls, kept per account and addressed by the call's `call_id`. This group holds the playback and download endpoint, the admin-only delete and the account's storage statistics. The call row that tells you a recording exists is in [Call Logs](/v2/docs/groups/call-logs); the transcript of a recording is in Speech To Text and follows the same access rule as playback.\n\n## Workflow (what the portal does)\n\n1. **Find the call**: the rows of [`GET /v2/call-log`](/v2/ref#/operations/callLog.callLog) carry `recording` (`true` when a file exists and the user may listen to it) and the call's ids. Use the row's `call_id`, the telephony id shared by the legs of one call, for everything in this group; `call_unique_id` is the row's own id and is not a recording id. [Call Logs](/v2/docs/groups/call-logs) explains how to read a row.\n2. **Play or download**: [`GET /v3/call-recording/{callId}`](/v2/ref#/operations/v3.callRecording) streams the file. `format` is `0` for MP3 (the default), `1` for OGG or `2` for WAV; `start` and `end` trim the audio and are positions in seconds with optional decimals (`90.5`). Send both or neither. The answer is the audio bytes with `Content-Disposition: attachment; filename=\u2026` and a `Content-Type` detected from the file. The endpoint supports HTTP range requests: a `Range: bytes=\u2026` header is answered with `206` and `Content-Range`, a range past the end of the file with `416`. Each playback is recorded in the account's recording access log (user, time and IP address).\n3. **Transcript**: [`GET /v2/speech-to-text/{callUniqueId}`](/v2/ref#/operations/speechToText.getCallSTT) takes the same `call_id` (its parameter is named `callUniqueId`, but it is this value) when the account has transcription enabled, and applies the access rule of playback.\n4. **Delete** (account admin): [`DELETE /v2/call-recording/{callUniqueId}`](/v2/ref#/operations/call_recording.destroy), again with the row's `call_id`. It removes the file and its transcript, sets the call row's `recording` to `false` and answers `204`, also when no recording exists for that id. There is no undo; the deletion is written to the access log.\n5. **Storage** (account admin): [`GET /v2/call-recording/statistics`](/v2/ref#/operations/call_recording.statistics) answers `used` (`value` in bytes, `formatted`, and `percentage` of the allowance as a string such as `\"6.84\"`), `allowed` (`value` in GB, `formatted` as `\"10 Gb\"`) and `oldest_file.date` (`null` when nothing is stored). The allowance is the recording storage of the account's subscriptions that include recording plus any storage add-ons; when it is `0`, `percentage` is `\"100\"`.\n\n```bash\n# The whole call as MP3, saved to disk\ncurl -o call.mp3 \\\n 'https://api.api-nuacom.com/v3/call-recording/1761640800.123' \\\n -H 'Authorization: Bearer YOUR_API_KEY'\n\n# Seconds 30 to 90 only, as OGG\ncurl -o excerpt.ogg \\\n 'https://api.api-nuacom.com/v3/call-recording/1761640800.123?format=1&start=30&end=90' \\\n -H 'Authorization: Bearer YOUR_API_KEY'\n```\n\n## Who can access a recording\n\n```mermaid\nflowchart TD\n start{\"No Recordings add-on active?\"} -- \"yes\" --> denyAll[\"403 for everyone, admins included\"]\n start -- \"no\" --> admin{\"Account admin?\"}\n admin -- \"yes\" --> allow[\"Playback and transcript allowed\"]\n admin -- \"no\" --> toggle{\"Call Recording Access toggle on?\"}\n toggle -- \"no\" --> deny[\"403\"]\n toggle -- \"yes\" --> access{\"Call-log access to this call?
(all, own extension, or granted extension/queue/number)\"}\n access -- \"yes\" --> allow\n access -- \"no\" --> deny\n```\n\n## Roles and access\n\n- Playback and transcript: an **account admin** can play every recording of the account. Any other user needs the **Call Recording Access** toggle on their user profile (an account admin sets it in the portal's user settings) **and** access to the call through their call-log permissions: call-log access \"all\", or a call on their own extension or on an extension, queue or number granted to them. Otherwise the answer is `403`.\n- The **No Recordings** add-on, when active on the account, blocks playback and transcripts for everyone, admins included (`403`).\n- The `recording` flag on call rows is decided by a stricter test than playback: the Call Recording Access toggle must be on even for an admin, and a non-admin user also needs the account to hold the call recording add-on or a subscription that includes recording. An admin whose toggle is off therefore sees `recording: false` on rows they can still play.\n- Delete and statistics are **account admin** only; any other user gets `403` with the body `\"Forbidden\"`.\n- With the account's ISO dates option, `oldest_file.date` is ISO 8601 in the requested timezone (UTC by default); without it, it is `Y-m-d H:i:s` in Irish time.\n\n## Pitfalls\n\n- `format` on playback is a number (`0`, `1`, `2`); anything else answers `422`.\n- Trimming needs both `start` and `end`, as plain decimals (`90.5`, not `1:30`), with `end` after `start`.\n- A recording is prepared on demand: fetched from storage, decrypted and, for OGG, WAV or a trim, converted. The first request for a given file and format can take a few seconds; the prepared file is reused for about two minutes.\n- An id that is not a `call_id` (for example a `call_unique_id`) answers `404`; for a user with limited call-log access it answers `403` instead, because the visibility check runs first.\n- A row with `recording: true` can still answer `404`: recordings are kept for six months by default (longer with a retention add-on), and a deleted recording is gone at once.\n- `DELETE` answers `204` for an id that has no recording, so a mistyped id looks like success." }, { "name": "Call Notes", "description": "Call notes are free-text remarks attached to a call, with the user who wrote them and when. A call can hold any number of notes; they appear in the call details, go to the account's connected CRM integrations and fire the `note_added` webhook. This group holds one reading endpoint and two identical ways of adding a note. Call rows carry their notes in `extra.call_notes` (see [Call Logs](/v2/docs/groups/call-logs)); rules that make a note mandatory after a call are in [After Call Work](/v2/docs/groups/after-call-work).\n\n## Workflow (what the portal does)\n\n1. **Read the notes of a call**: [`GET /v2/call-notes?callIDs[]=\u2026`](/v2/ref#/operations/callLog.callNotes). `callIDs` is an array (`callIDs[]=a&callIDs[]=b`) or one comma-separated string; pass the row's `call_id`, `sip_call_id` and `original_sip_call_id` together, because a note is stored under whichever of them was used to add it. The answer is an array, newest first, of `call_id` (the id the note was stored under), `note`, `account_id`, `user_id`, `user_name` (`null` when that user no longer exists) and `note_time` (ISO 8601, UTC). Ids of several calls can be mixed in one request; tell the notes apart by `call_id`. Without `callIDs` the endpoint answers `406` with the body `false`.\n2. **Add a note**: [`POST /v3/call-notes`](/v2/ref#/operations/v3.call-notes.store) with `callId` (a string of up to 100 characters: the row's `call_id`, `sip_call_id` or `original_sip_call_id`) and `note` (up to 1000 characters; HTML tags are stripped). Answers `204`. [`POST /v2/call-notes`](/v2/ref#/operations/v2.addCallNote) is the same operation under its older path; both stay available and behave identically.\n3. **What follows**: the note is stored with the calling user as its author, the account's CRM integrations receive the updated call, and a `note_added` webhook goes to the subscribed URLs (see [Integrations](/v2/docs/groups/integrations)).\n\n```bash\n# Add a note\ncurl -X POST https://api.api-nuacom.com/v3/call-notes \\\n -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"callId\":\"1761640800.123\",\"note\":\"Customer asked for a quote by Friday\"}'\n# \u2192 204\n\n# Read the notes back; repeat callIDs[] for the row's sip_call_id and original_sip_call_id\ncurl 'https://api.api-nuacom.com/v2/call-notes?callIDs[]=1761640800.123' \\\n -H 'Authorization: Bearer YOUR_API_KEY'\n# \u2192 [{\"call_id\":\"1761640800.123\",\"note\":\"Customer asked for a quote by Friday\",\"account_id\":\"IE-00123\",\"user_id\":123,\"user_name\":\"Jane\",\"note_time\":\"2026-10-28T09:15:00.000000Z\"}]\n```\n\n## Roles and access\n\n- Any authenticated user can read and add notes; nothing in this group is admin-only.\n- Notes are scoped to the account, not to the user's call-log permissions: `GET /v2/call-notes` answers the notes of any call of the account whose ids you pass, and `POST` accepts any call of the account. A call of another account, or an id that matches no call, is refused with `422` (\"The given call does not belong to this account.\").\n\n## Pitfalls\n\n- `callId` must be a JSON string: a bare number such as `1761640800.123` fails validation (`422`).\n- Store notes under the row's `call_id` when you can; whichever id you use, read them back with all three ids, as the portal does.\n- The missing-parameter answer of `GET /v2/call-notes` is `406`, not `422`, and its body is `false`.\n- The text is stored with its HTML tags removed, silently; it is not truncated: more than 1000 characters answers `422`.\n- Editing and deleting a note is not part of this group; the portal does both in the browser.\n- `note_time` is set by the server. In `GET /v2/call-notes` it is ISO 8601 in UTC; inside a call row (`extra.call_notes`) it follows the row's date format, which the account's ISO dates option decides.\n- `user_name` is the user behind the token. With an API key that is the admin who created the key, not your end user; put the author in the text when it matters." }, { "name": "Call Tags", "description": "Call tags are labels an account defines once, in a catalogue, and then assigns to calls so that call history can be filtered and reported by outcome. The catalogue is a tree up to five levels deep: a tag has a name, a color, an availability (all calls, inbound only or outbound only), an optional parent and optional visibility rules that limit it to some extensions or departments. This group holds the catalogue endpoints under `/v3/call-tags`, the assignment endpoints `GET /v2/call-tags` and `POST /v2/add-call-tag`, and an older delete. Call rows carry their tags in `extra.call_tags` (see [Call Logs](/v2/docs/groups/call-logs)); rules that make tagging mandatory after a call are in [After Call Work](/v2/docs/groups/after-call-work).\n\n## Workflow (what the portal does)\n\n1. **Tag picker**: [`GET /v3/call-tags/all-parent-child`](/v2/ref#/operations/callTagInfo.allParentChild) answers every tag the user may see, parents and children alike, as one flat array in catalogue order; build the tree client-side on `parent_id`. `descendants_count` is always `0` on this endpoint.\n2. **Catalogue page**: [`GET /v3/call-tags`](/v2/ref#/operations/v3.call-tags.index) with `page` and `perPage` (both required; `perPage` is `15`, `25`, `50`, `100`, or `-1` for all) lists the top-level tags only, each with its `descendants_count` and `visibility` rules. Filters: `filter[name]` and `filter[color]` (partial match), `filter[available_for]` (`2` inbound or `3` outbound; tags available for all calls are always included). A paginated answer is `{\"data\": [tags], \"links\": {\u2026}, \"meta\": {\u2026}}` with `meta.total` and `meta.last_page`; `perPage=-1` answers a plain array.\n3. **One tag and its children**: [`GET /v3/call-tags/{callTag}`](/v2/ref#/operations/v3.call-tags.show) answers the tag with `descendants`, its direct children, each with their own `descendants_count`; `available_for` in the query limits the children the way the list filter does. Account admins also get the tag's `visibility`.\n4. **Create** (account admin): [`POST /v3/call-tags`](/v2/ref#/operations/v3.call-tags.store) with `name` (up to 20 characters), `color` (`#rgb` or `#rrggbb`; the key is required but may be `null`) and, optionally, `parent_id`, `available_for` (`1` all calls, the default; `2` inbound; `3` outbound), `visible_to` (a list of up to 100 entries, each `{\"type\": 1, \"allowed_id\": }` or `{\"type\": 2, \"allowed_id\": }`) and `order_column` (the position in the catalogue, from `1`; `0` or omitted appends the tag at the end). Answers `201` with the tag.\n5. **Update** (account admin): [`PUT /v3/call-tags/{callTag}`](/v2/ref#/operations/v3.call-tags.update) with the same body. `name` and `color` are saved on every call; `parent_id`, `available_for`, `visible_to` and `order_column` change only when the key is present. `\"parent_id\": null` promotes a child to the top level, `\"visible_to\": []` (or `null`) removes every visibility rule, and an omitted `visible_to` keeps them. Answers `202` with the tag.\n6. **Assign to a call**: [`POST /v2/add-call-tag`](/v2/ref#/operations/v2.addCallTag) with `call_id` (the row's `call_id`, `sip_call_id` or `original_sip_call_id`, as a string) and `tag_info_id` (the catalogue `id`). Answers `204`; assigning a tag the call already has is a no-op. A new assignment is pushed to the account's CRM integrations and fires the `tag_added` webhook (see [Integrations](/v2/docs/groups/integrations)).\n7. **Read a call's tags**: [`GET /v2/call-tags?callIDs[]=\u2026`](/v2/ref#/operations/callLog.callTags) with the row's `call_id`, `sip_call_id` and `original_sip_call_id` (an array, or one comma-separated string). It answers the account's whole catalogue, parents and children, in id order, with the stored fields `id`, `tag_name`, `tag_color`, `parent_id`, `available_for`, `order_column`, plus `assigned` (`1` or `0`) for that call. Without `callIDs` it answers `406`.\n8. **Delete** (account admin): [`DELETE /v3/call-tags/{callTag}`](/v2/ref#/operations/v3.call-tags.destroy) removes the tag with its whole subtree, every assignment of those tags on calls and their CRM tag mappings (ActiveCampaign, HubSpot); it answers `204`, or `404` for a tag of another account. [`DELETE /v2/tags/{id}`](/v2/ref#/operations/tags.destroy) is the older form: it detaches the one tag from every call (one `tag_removed` webhook per call) and deletes it, without the subtree and CRM clean-up, so use it only for a tag that has no children.\n\n```bash\n# A catalogue tag for inbound calls, visible to extension 101 only\ncurl -X POST https://api.api-nuacom.com/v3/call-tags \\\n -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"name\":\"Callback\",\"color\":\"#ff5733\",\"available_for\":2,\"visible_to\":[{\"type\":1,\"allowed_id\":101}]}'\n# \u2192 201 {\"id\":42,\"name\":\"Callback\",\"color\":\"#ff5733\",\"available_for\":2,\"descendants_count\":0,\"visibility\":[{\"type\":1,\"allowed_id\":101}],\"order_column\":7,\"parent_id\":null}\n\n# Assign it to a call\ncurl -X POST https://api.api-nuacom.com/v2/add-call-tag \\\n -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"call_id\":\"1761640800.123\",\"tag_info_id\":42}'\n# \u2192 204\n```\n\n## Reading a tag\n\n| Field | Meaning |\n|---|---|\n| `id` | The catalogue id; it is the `tag_info_id` you assign with, and the `tags` filter value of the call-log list |\n| `name`, `color` | The label and its hex color (`tag_name`, `tag_color` on `GET /v2/call-tags`) |\n| `available_for` | `1` all calls, `2` inbound only, `3` outbound only |\n| `parent_id` | `null` for a top-level tag, otherwise the parent's `id` |\n| `order_column` | The position in the catalogue, from `1`; every list is sorted by it |\n| `descendants_count`, `descendants` | The number of direct children, and the children themselves where the endpoint loads them |\n| `visibility` | The visibility rules: `type` `1` with an extension number, or `2` with a department id. No rules means visible to everyone |\n\n## Roles and access\n\n- Reading the catalogue, reading a call's tags and assigning tags: any authenticated user. The `/v3/call-tags` reads hide restricted tags from non-admin users: a user sees the tags without visibility rules plus those whose rules name their extension or one of their departments, and `GET /v3/call-tags/{callTag}` answers `404` for a tag they may not see. `GET /v2/call-tags` applies no visibility filter. Account admins see every tag.\n- Creating, updating and deleting catalogue tags: **account admin** only. The `/v3/call-tags` writes answer `403` for any other user; `DELETE /v2/tags/{id}` answers `403` with the body `\"Forbidden\"`.\n\n## Pitfalls\n\n- Two different things are called \"call tags\": `GET /v3/call-tags` is the catalogue, `GET /v2/call-tags` is the assignment state of one call; `POST /v3/call-tags` creates a catalogue entry, `POST /v2/add-call-tag` assigns one. There is no `POST /v2/call-tags`: that path is redirected to the catalogue create, so a body meant for an assignment is validated as a new tag.\n- `GET /v2/call-tags` reads one call: it takes the first call that matches any id you pass and answers that call's assignments. Pass the three ids of one row, not the ids of several calls.\n- `tag_info_id` is not checked against the catalogue: an unknown id, or another account's, answers `204` and creates an assignment that `GET /v2/call-tags` never shows.\n- There is no endpoint to remove one tag from one call. The portal does that in the browser; through the API the only removals are the catalogue deletes, which detach the tag from every call.\n- `page` and `perPage` are required on `GET /v3/call-tags` (`422` without them); `sort` is accepted but ignored; an unknown `filter[...]` key answers `400`.\n- A tag can be at most five levels deep, cannot be its own parent and cannot be moved under one of its own descendants (`422`). `parent_id` must be a tag of the account.\n- A `visible_to` entry must name something the account owns, an extension number for `type` 1 or a department id for `type` 2 (`422`); a tag whose rules match nobody disappears for every non-admin user.\n- `name` over 20 characters, or a `color` that is not a hex code, answers `422`. Both are required on every `PUT`, not only on create.\n- `DELETE /v2/tags/{id}` answers `204` for an id that does not exist. `DELETE /v3/call-tags/{callTag}` sends no `tag_removed` webhook for the assignments it removes; only the v2 delete does." }, { "name": "Call Rates", "description": "The rate card is the per-minute price list for outbound calls under the account's package: one price per destination network, by country. The group has two read-only endpoints, the countries the card covers and the rates of one of them, which together make the portal's **Billing \u2192 Call Rates** page. Messaging prices are a separate list, described in [Conversations](/v2/docs/groups/conversations).\n\n## Workflow (what the portal does)\n\n1. **Countries**: [`GET /v2/account/call-rates-countries`](/v2/ref#/operations/v2.getAccountCallRatesCountries) answers a bare array of `{\"country_code\": \"IE\", \"name\": \"Ireland\"}`: the countries with at least one rate in the account's card, in alphabetical order of name, with `XS` \"International Satellite\" last when the card prices satellite numbers. The portal fills its country picker from it.\n2. **Rates of a country**: [`GET /v2/account/call-rates?country_code=IE`](/v2/ref#/operations/v2.getAccountCallRates) answers `{\"currency\": \"EUR\", \"data\": [{\"network\": \"IRELAND EIR MOBILE\", \"number_type\": 1, \"rate\": 0.04215}, \u2026]}`: one row per network, number type and rate, sorted by network. `rate` is the price per minute before VAT in `currency`, the account's billing currency, with up to five decimals. `number_type` is `0` fixed line, `1` mobile, `3` toll-free, `4` premium or `99` undefined, for a range that mixes landlines and mobiles (the US and Canada) or that NUACOM has not classified.\n\n`country_code` is required: two letters in either case, one of the countries of [`GET /v3/country-list`](/v2/ref#/operations/v3.getCountries) or `XS`; anything else answers `422`.\n\n## Roles and access\n\n- Any authenticated user of the account; no admin check.\n\n## Pitfalls\n\n- The two answers have different shapes: the countries are a bare array, the rates an object with `data` and `currency`.\n- An account without a package has no rate card: both endpoints answer `200` with an empty list, as does a country with no rates. Neither is a `404`.\n- Rates are before VAT and come with up to five decimals; the portal rounds them to three.\n- A destination can appear more than once: a network priced differently for two number types, or at two rates, is two rows.\n- Networks whose name says \"mobile\" but whose numbers are classified as fixed, toll-free or premium are left out rather than shown under a misleading name." }, { "name": "Callbacks", "description": "A callback is a call NUACOM places for you in two legs: the platform first rings one of the account's extensions or a queue and, once that leg is answered, dials the destination number and bridges the two. In the API it is a single operation, [`POST /v2/request-callback`](/v2/ref#/operations/v2.requestCallbackAction). The extension and queue numbers it starts from come from the [Extensions](/v2/docs/groups/extensions) and Queues groups.\n\n## Workflow (what the portal does)\n\n1. **Pick the origin**: an extension number from [`GET /v2/extensions`](/v2/ref#/operations/extensions.index) (`number`) or a queue number from [`GET /v2/queues`](/v2/ref#/operations/queues.index) (`number`, not the queue id).\n2. **Request the call**: `POST /v2/request-callback` with `method` (`extension` or `queue`), `from_number` (the extension or queue number, up to 20 characters) and `dst_number` (the destination in E.164, `+353861234567`, up to 20 characters). The answer is `200` with `{\"data\": true}` when the platform accepted the request and `{\"data\": false}` when it refused it.\n3. **What happens next**: with `extension`, the extension rings for up to 30 seconds showing the caller ID name `WebCall +353861234567` (the destination); when the agent answers, the destination is dialled from that extension and the two legs are bridged. With `queue`, the call is placed into the queue and offered to its agents under the same `WebCall` name, and the destination is dialled when an agent answers. If nobody answers within 30 seconds, nothing is dialled.\n4. **Afterwards**: the request returns nothing beyond `data`: no call id and no status to poll.\n\n```bash\ncurl -X POST https://api.api-nuacom.com/v2/request-callback \\\n -H 'Authorization: Bearer YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"method\":\"extension\",\"from_number\":\"101\",\"dst_number\":\"+353861234567\"}'\n# \u2192 {\"data\":true}\n```\n\n## How a callback connects two legs\n\n```mermaid\nsequenceDiagram\n participant I as Your integration\n participant API as NUACOM API\n participant Origin as Extension or queue (leg 1)\n participant Dst as Destination number (leg 2)\n\n I->>API: POST /v2/request-callback
method, from_number, dst_number\n API-->>I: 200 {data: true}\n API->>Origin: Ring for up to 30 seconds
caller ID \"WebCall \"\n alt answered within 30 seconds\n Origin-->>API: Answered\n API->>Dst: Dial dst_number\n Dst-->>API: Answered\n Note over Origin,Dst: Two legs bridged\n else nobody answers within 30 seconds\n Note over API,Origin: Nothing is dialled\n end\n```\n\n## Validation errors\n\nA rejected body answers `422` with the first error as `message` and every error under `errors`:\n\n```json\n{\n \"message\": \"Extension is not available for input account id.\",\n \"errors\": {\n \"from_number\": [\"Extension is not available for input account id.\"]\n },\n \"trace\": null\n}\n```\n\n| Field | Error text | When |\n|---|---|---|\n| `method` | `The method field is required.` | Missing |\n| `method` | `The selected method is invalid.` | Not `extension` or `queue` |\n| `from_number` | `The from number field is required.` | Missing |\n| `from_number` | `Extension is not available for input account id.` | `method` is `extension` and the account has no extension with that number |\n| `from_number` | `Queue not available for account.` | `method` is `queue` and the account has no queue with that number |\n| `dst_number` | `The dst number field is required.` | Missing |\n| `dst_number` | `dst number has an invalid phone format` | Cannot be read as a phone number |\n| `dst_number` | `The dst number field must not be greater than 20 characters.` | Longer than 20 characters |\n\n## Roles and access\n\n- Any authenticated user; there is no admin gate. The call is placed on the account behind the token, from the extension or queue you name.\n- `500` means the telephony platform could not be reached; `{\"data\": false}` means it answered but did not place the call.\n\n## Pitfalls\n\n- `dst_number` is dialled exactly as you send it. The format check reads it in the user's country, so a national number such as `0861234567` can pass validation for an Irish user, but the platform still receives that string unchanged. Always send E.164.\n- For `queue`, `from_number` is the queue **number** (`number` in `GET /v2/queues`), not its id; the API resolves the id itself.\n- A refusal comes back as `200` with `{\"data\": false}`, not as an error status. Check the flag.\n- The first leg rings for 30 seconds at most; the limit is not configurable per request.\n- The API does not de-duplicate requests; each one is handed to the platform as a new call." }, { "name": "After Call Work", "description": "After Call Work rules make tagging and note-taking mandatory in the NUACOM softphone. A rule matches calls by inbound number or by queue and sets what the agent must enter once the call ends: a minimum number of tags, a minimum number of words in the note, and a countdown timer that bounds how long the softphone waits for them. This group holds the rule list, the save (an upsert of the whole set), the delete, and the lookup phones use to find the rules for one call. The tags come from the [Call Tags](/v2/docs/groups/call-tags) catalogue, and the entries themselves are written with the [Call Notes](/v2/docs/groups/call-notes) and Call Tags endpoints.\n\n## Workflow (what the portal does)\n\n1. **List**: [`GET /v2/after-call-work`](/v2/ref#/operations/after-call-work.index) answers the account's rules, newest first, each with `id`, `account_id`, `direction` (`inbound`, `outbound` or `both`), `number` (a list of numbers, or `null`), `queue_id` (a list of queue ids, or `null`), `tags` (the minimum number of tags), `notes` (the minimum number of words in the note) and `timer` (seconds).\n2. **Save**: [`PUT /v2/after-call-work/upsert`](/v2/ref#/operations/v2.afterCallWorkUpsert) takes a JSON array of rules and inserts or updates each one by `id`; the portal sends every rule of its page on each save. A rule has `id` (`0` for a new rule), `direction`, either `number` (a list) or `queue_id` (a list), `tags`, `notes` and `timer` (at most `180` seconds). Send every key, with `null` or `[]` for the ones that do not apply. `tags` and `notes` are required when `timer` is `0`, and `timer` is required when `tags` or `notes` is `0`. A queue rule is stored as `inbound` whatever `direction` says. An `id` that is not `0` and not one of the account's rules fails the whole save with `422` and an error on `.id`. Answers `204`; connected softphones are told to reload their rules.\n3. **Delete**: [`DELETE /v2/after-call-work/{id}`](/v2/ref#/operations/after-call-work.destroy) removes one rule and notifies the softphones. `204`, or `404` when the id is not one of the account's.\n4. **Lookup for one call**: [`GET /v2/after-call-work/settings`](/v2/ref#/operations/v2.afterCallWorkSettings) with `direction` (`inbound` or `outbound`) and either `number` or `queue_id` answers the rules that apply to such a call, as `[{\"id\", \"tags\", \"notes\", \"timer\"}]`: rules with that `direction` or `both` whose `number` list contains the number, or whose `queue_id` list contains the queue id. An empty array means nothing is mandatory. The number you send is normalised to `00` + country code + national number before matching (`+353 91 234 5678` becomes `00353912345678`), so store numbers in that form.\n\n```bash\n# One new rule for a number (both directions) and one updated queue rule\ncurl -X PUT https://api.api-nuacom.com/v2/after-call-work/upsert \\\n -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '[\n {\"id\": 0, \"direction\": \"both\", \"number\": [\"00353912345678\"], \"queue_id\": [], \"tags\": 1, \"notes\": 10, \"timer\": 60},\n {\"id\": 17, \"direction\": \"inbound\", \"number\": [], \"queue_id\": [\"10\"], \"tags\": 2, \"notes\": 0, \"timer\": 120}\n ]'\n# \u2192 204\n\n# What a phone must ask for after an inbound call from queue 10\ncurl 'https://api.api-nuacom.com/v2/after-call-work/settings?direction=inbound&queue_id=10' \\\n -H 'Authorization: Bearer YOUR_API_KEY'\n# \u2192 [{\"id\":17,\"tags\":2,\"notes\":0,\"timer\":120}]\n```\n\n## When a tag or note is enforced\n\n```mermaid\nflowchart TD\n callEnds[\"Call ends on a matching number/queue and direction\"] --> lookup[\"GET /v2/after-call-work/settings
direction + number or queue_id\"]\n lookup --> rules{\"Matching rule(s)?\"}\n rules -- \"none (empty array)\" --> nothing[\"Nothing mandatory\"]\n rules -- \"yes\" --> prompt[\"Softphone requires at least `tags` tags
and a note of `notes` words\"]\n prompt --> timer[\"Countdown timer (at most 180s) bounds the wait\"]\n timer -- \"submitted before timer ends\" --> submitted[\"Tag/note written via Call Tags / Call Notes endpoints\"]\n timer -- \"timer runs out\" --> expired[\"Softphone stops waiting\"]\n```\n\n## Roles and access\n\n- Every endpoint in this group is open to any authenticated user of the account; none requires an account admin.\n\n## Pitfalls\n\n- The save is an upsert keyed on `id`: a rule you leave out of the array is kept, not deleted (use the delete endpoint), and `id: 0` always creates. Any other id must be one of the account's existing rules.\n- Send every key of every rule (`direction`, `number`, `queue_id`, `tags`, `notes`, `timer`); a rule with a missing key makes the save fail.\n- Numbers and queue ids are stored as sent and are not checked against the account's numbers and queues. Store numbers as `00` + country code + national number and queue ids as strings (`[\"10\"]`): the lookup matches them in exactly that form.\n- `timer` is capped at `180` seconds (`422` above it); `tags` and `notes` have no upper bound.\n- The softphone notification is best-effort: when it fails, the request still answers `204` and the rules are saved; phones apply them once they next reload their rules.\n- `GET /v2/after-call-work/settings` needs `direction` and one of `number` / `queue_id` (`422` otherwise). Sending both narrows the answer to rules that name both, which is rarely what you want." }, { "name": "Call AI", "description": "Call AI is what NUACOM extracts from a call recording once it has been transcribed: a summary, the conversation split by channel, the topics discussed, the action items and the overall sentiment. This group holds two read-only endpoints, one for a single call and one for every call of a period. The full transcript with timings, talk time and search lives in [Speech To Text](/v2/docs/groups/speech-to-text), the audio in [Call Recording](/v2/docs/groups/call-recording), and the call ids you need come from [Call Logs](/v2/docs/groups/call-logs).\n\n## Workflow (what the portal does)\n\n1. **Find the call**: take `call_id` from a [`GET /v2/call-log`](/v2/ref#/operations/callLog.callLog) row that has `recording: true`. `call_id` is the telephony id shared by every leg of a call; `call_unique_id` is not accepted here.\n2. **One call**: [`GET /v2/calls/{callId}/ai-data`](/v2/ref#/operations/v2.getCallAiData) answers the object described below. It is JSON unless you ask for XML with an `Accept` header containing `application/xml` or `text/xml`, or with `?format=xml`. `format` accepts only `json` and `xml`; anything else answers `422`.\n3. **A period**: [`GET /v2/calls/ai-data`](/v2/ref#/operations/v2.listCallAiData) with `date_from` and `date_to`, both required, as `Y-m-d` or `Y-m-d H:i:s` (a bare date spans the whole day), at most 31 days apart and `date_to` not before `date_from`; `page` (default 1) and `per_page` (1\u2013100, default 25). It answers `{\"data\": [...], \"meta\": {\"page\", \"per_page\", \"total\"}}`; each item is the object below plus `callId` and `callDate`. This endpoint is JSON only.\n\n```bash\ncurl 'https://api.api-nuacom.com/v2/calls/svr13-core2-1753839825.12345/ai-data' \\\n -H 'Authorization: Bearer YOUR_API_KEY'\n```\n\n```json\n{\n \"summary\": \"Megan from NUACOM asked for Brian about a telecommunications offer; he was unavailable, so she left a message asking to be called back.\",\n \"transcription\": [\n {\"channel\": 1, \"text\": \"Good morning, Mullen and Sons.\"},\n {\"channel\": 0, \"text\": \"Hi, is Brian available?\"},\n {\"channel\": 1, \"text\": \"He is not, can I take a message?\"}\n ],\n \"topics\": [\"Callback request\", \"Telecommunications\"],\n \"actionItems\": [\"Brian to call Megan back\"],\n \"averageSentiment\": \"neutral\"\n}\n```\n\n## Reading the response\n\n| Field | Content |\n| --- | --- |\n| `summary` | A few sentences describing the call. |\n| `transcription` | The utterances in order, each `{\"channel\": , \"text\": \"...\"}`; the channel separates the two parties of the recording. |\n| `topics` | Short labels for what was discussed. |\n| `actionItems` | Follow-ups extracted from the conversation. |\n| `averageSentiment` | The tone of the whole call: `positive`, `neutral` or `negative`; `Unknown` when none was computed. |\n\nIn XML the root element is ``; `transcription` entries are `` elements with `` and ``, `topics` entries are `` and `actionItems` entries are ``.\n\n## Enabling AI data\n\nA call gets AI data when it was recorded and the account had an active AI Analysis add-on at the time:\n\n- **Unlimited AI Call Analysis**: every recorded call is analysed.\n- **Free AI Call Analysis**: an allowance of minutes, reset monthly. The duration of each analysed call is deducted from it, and new calls are no longer analysed once it is used up.\n\n[`GET /v2/speech-to-text/active`](/v2/ref#/operations/accountAddonStt.currentAddon) tells you which one is active; an admin switches them with the subscription endpoints described in [Speech To Text](/v2/docs/groups/speech-to-text). Analysis runs in the background after the recording is stored, so the data for a call that has just ended arrives later.\n\n## Roles and access\n\n- Any authenticated user can call both endpoints.\n- The single-call endpoint applies the recording rules: account admins may read any call; other users need the **Call Recording Access** setting on their user, and the call must be visible to them (on their own extension, or on the numbers, extensions and queues granted to them; a user whose call-log permission is \"all\" sees every call). A call outside that scope, including an id that does not exist, answers `403`.\n- The period endpoint has no per-user filter: it returns the AI data of every call of the account.\n- Accounts that opted out of recording with the No Recordings add-on get `403` from both endpoints.\n\n## Pitfalls\n\n- `404` with `{\"message\": \"No AI data available for this callId\"}` covers every \"nothing to show\" case: an unknown id (for an admin), a call that was not recorded, not analysed yet, recorded before the add-on was active, or whose analysis failed. There is no \"pending\" state to tell them apart.\n- A recording too short to summarise still answers `200`: `summary` is then the placeholder `Unable to summarize. Recording is too short or lacks conversational content.`. Check for it before showing the summary.\n- `date_from` and `date_to` are compared with the stored call date, which is Irish time (`Europe/Dublin`); `X-Timezone` is not read. `callDate` in the response is UTC ISO 8601 (`2026-06-01T09:00:00.000000Z`).\n- `meta.total` counts the account's call-log rows in the period, not the items returned. Rows without AI data are skipped, so a page can carry fewer than `per_page` items, even none, while later pages still do. Walk every page up to `total / per_page` instead of stopping at an empty one.\n- A call with several legs (transfers, queue legs) has several call-log rows sharing one `call_id`, and each row yields an item: the same analysis can appear more than once in a page. De-duplicate on `callId`.\n- `format=xml` on the period endpoint does nothing; only the single-call endpoint speaks XML." }, { "name": "Speech To Text", "description": "Speech To Text is the transcript NUACOM produces from a call recording, together with the analysis built on it: summary, topics, action items, sentiment per utterance and talk time per party. This group holds the transcript endpoint, a search-and-highlight variant and, under **Speech To Text / Subscription**, the endpoints that manage the AI Analysis add-on that enables transcription. [Call AI](/v2/docs/groups/call-ai) returns a condensed view of the same data; the audio is in [Call Recording](/v2/docs/groups/call-recording) and the call ids come from [Call Logs](/v2/docs/groups/call-logs).\n\n## Workflow (what the portal does)\n\n1. **Check the subscription**: [`GET /v2/speech-to-text/active`](/v2/ref#/operations/accountAddonStt.currentAddon) returns the active AI Analysis add-on as `addon_id`, `addon_name`, `addon_price`, `added_date` and `qty`, or `{\"addon_id\": 0}` when there is none.\n2. **Open a transcript**: from a [`GET /v2/call-log`](/v2/ref#/operations/callLog.callLog) row with `recording: true` (the list's `has_transcriptions` filter narrows it to transcribed calls), call [`GET /v2/speech-to-text/{callUniqueId}`](/v2/ref#/operations/speechToText.getCallSTT) with the row's `call_id`. The document is described below.\n3. **Search inside it**: [`POST /v2/speech-to-text/{callUniqueId}/highlight`](/v2/ref#/operations/speechToText.getHighlightedCallSTT) with `{\"search\": \"invoice\"}` answers the same document only when it matches, with every match wrapped in `\u2026` inside `summary`, `topics`, `actionItems` and the utterances. The query syntax is below.\n4. **Change the subscription** (admins): see [Subscription](#subscription).\n\n```bash\ncurl -X POST 'https://api.api-nuacom.com/v2/speech-to-text/svr13-core2-1753839825.12345/highlight' \\\n -H 'Authorization: Bearer YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"search\": \"\\\"invoice\\\" + \\\"refund\\\"\"}'\n```\n\n## Reading a transcript\n\n| Field | Content |\n| --- | --- |\n| `combinedRecognizedPhrases` | One entry whose `display` is the whole transcript as plain text. |\n| `recognizedPhrases` | One entry per utterance: `channel` and `speaker`, `offset` and `duration` as ISO 8601 durations (`PT12.5S`), `offsetInTicks` and `durationInTicks` (one tick is 100 ns, 10,000,000 per second), and `nBest` with `display` (the text), `words` (each with its own offset and duration) and `sentiment` (`sentiment` and `confidence`). |\n| `summary` | A few sentences describing the call, or the placeholder `Unable to summarize. Recording is too short or lacks conversational content.`. |\n| `topics`, `conversationTopics` | Labels for what was discussed. Some transcripts fill only `conversationTopics`; read both. |\n| `actionItems` | Follow-ups extracted from the conversation, as a list of strings; `\"\"` when none were extracted. |\n| `sentiment` | `positive`, `neutral` or `negative` for the whole call; `unknown` when none was computed. |\n| `talkTime` | One entry per channel with `channel`, `talkTimeDurationInTicks` and `percentage`, the integer share of the speaking time; `null` when not computed. |\n| `balance` | The account's AI allowance: `null` without an AI Analysis add-on, `1` with a paid one, otherwise the remaining free allowance, `0` or less once it is used up. |\n| `doc` | Unused, always `[]`. |\n\nA call that has no transcript answers `200` with the empty defaults (`summary` `\"\"`, lists `[]`, `sentiment` `\"unknown\"`, `talkTime` `null`) and `balance` still filled. It is not a `404`.\n\n### Search syntax\n\n| Query | Matches |\n| --- | --- |\n| `invoice` | Plain text is matched as a phrase, case-insensitively, allowing up to two words between the terms. |\n| `\"late payment\"` | A quoted phrase, same rules. |\n| `\"invoice\" + \"refund\"` | Both phrases. |\n| `\"invoice\" \\| \"refund\"` | Either phrase. |\n| `-\"refund\"` | The phrase must be absent. |\n| `\"invoice\" + (-\"refund\")` | The first phrase present and the second absent. |\n\nOperators only work on double-quoted terms; a `+`, `|` or `-` next to an unquoted word is searched as text. A term matches in any of `summary`, the utterances, `topics` or `actionItems`.\n\n## When a call is transcribed\n\nA recording is transcribed when the account has an active AI Analysis add-on:\n\n- **Unlimited AI Call Analysis**, a paid add-on: every recorded call.\n- **Free AI Call Analysis**: an allowance of minutes, reset monthly. The duration of each transcribed call is deducted from it; once the allowance is used up new calls are no longer transcribed, while existing transcripts stay readable.\n\nTranscription starts in the background once the recording is stored and takes a while, so a row that already shows `recording: true` can still have no transcript. The transcript is produced in the language configured for the account: English unless an admin set a default call language or per-number overrides with [`POST /v2/account-language-config`](/v2/ref#/operations/account-language-config.store) (where enabled for the account; [`GET /v2/language-options`](/v2/ref#/operations/v2.languageOptions) lists the choices). The summary, topics, action items and sentiment are generated from that transcript.\n\n## Subscription\n\nTwo AI Analysis add-ons exist: **Free AI Call Analysis** (`addon_id` `1124`, no charge, a monthly allowance of minutes) and **Unlimited AI Call Analysis** (`addon_id` `1128`, a monthly price per extension). Only one is active at a time; activating one cancels the other.\n\nSubscription states:\n\n```mermaid\nstateDiagram-v2\n [*] --> None: no AI Analysis add-on\n None --> Free: upgrade addon_id 1124 (no charge)\n None --> Unlimited: upgrade addon_id 1128 (charged pro-rata)\n Free --> Unlimited: upgrade addon_id 1128\n Unlimited --> Free: downgrade addon_id 1124 (no charge)\n Free --> None: DELETE /v2/speech-to-text/deactivate\n Unlimited --> None: DELETE /v2/speech-to-text/deactivate\n```\n\n1. [`GET /v2/speech-to-text/calculate/{addonId}`](/v2/ref#/operations/accountAddonStt.calculate) prices an activation from today to the end of the month: `unitPrice` (the monthly price), `cleanAmount` (the pro-rata part for the remaining days; the full price on the 1st), `extensionsCount` (the account's extensions), `subTotal` (`cleanAmount` \u00d7 `extensionsCount`), `accountVatRate`, `vatAmount` (VAT on `cleanAmount`), `total` (`subTotal` plus VAT), `billingPeriodStart`, `billingPeriodEnd`, `billingCurrency`, `addonName`, `transactionName` and `isNextMonth` (`false`). An id that is not an AI Analysis add-on offered to your account answers `400` `{\"message\": \"Addon not found\"}`.\n2. [`POST /v2/speech-to-text/upgrade`](/v2/ref#/operations/accountAddonStt.upgrade) with `addon_id` and, for a paid add-on on a pre-pay account, `paymentMethod` (the id of one of the account's saved payment methods). It cancels the current AI add-on and its pending charges, activates the new one, sets the free allowance when the add-on has one, and charges the pro-rata amount at once when it has a price: a pre-pay account's payment method is charged immediately, a bill-pay account is billed for it. `204`.\n3. [`POST /v2/speech-to-text/downgrade`](/v2/ref#/operations/accountAddonStt.downgrade) with `addon_id` makes the same switch without a charge. `204`.\n4. [`DELETE /v2/speech-to-text/deactivate`](/v2/ref#/operations/accountAddonStt.deactivate) cancels every active AI Analysis add-on and any upcoming charge. `204`.\n\n`upgrade` and `downgrade` answer `422` with `errors` when `addon_id` is not an AI Analysis add-on (`Wrong addon type.`), is already active (`This addon is already active.`) or, on a pre-pay account activating a paid add-on, when `paymentMethod` is missing or unknown (`Invalid payment method.`). An `addon_id` that does not exist, or that is not offered to your account, answers `404`. A declined card answers `400` with an `error_code`.\n\n## Roles and access\n\n- Transcript and highlight: any authenticated user who may listen to the recording. Account admins always may; other users need the **Call Recording Access** setting on their user, and the call must be visible to them (own extension, or the numbers, extensions and queues granted to them; call-log permission \"all\" covers every call). Otherwise `403`, also for an id that does not exist; the highlight endpoint says `You are not authorized to access information about this call.`. Accounts with the No Recordings add-on get `403` for every call.\n- `active`: any authenticated user; the answer includes the add-on's price.\n- `calculate`, `upgrade`, `downgrade` and `deactivate`: account admins only; anyone else gets `403` `\"Forbidden\"`.\n\n## Pitfalls\n\n- `{callUniqueId}` is the call-log row's `call_id`, the telephony id shared by the legs of one call; `call_unique_id` finds nothing.\n- Nothing distinguishes \"not transcribed yet\" from \"never will be\": both answer `200` with empty fields. Test `recognizedPhrases` rather than the status code, and treat the placeholder summary as \"no summary\".\n- The highlight markup is inside the strings (`\u2026`): strip it before reuse. `balance` is always `0` in that response.\n- `upgrade` charges without a preview: call `calculate` first and show the `total` to the user. Switching to the Free add-on resets its allowance to the monthly amount.\n- `deactivate` takes effect at once: transcription stops for new calls, existing transcripts stay readable.\n- `added_date` in `active` is a plain `Y-m-d H:i:s` string unless the account has the ISO dates option, which renders it in ISO 8601 in the requested timezone." }, { "name": "Speech To Text / Subscription" }, { "name": "Keyword Tracker", "description": "A keyword tracker watches the transcripts of your recorded calls for words or phrases. When a call matches, the tracker tags the call and emails the people you chose, with the summary and the matching lines of the transcript. Trackers run on the transcript and analysis NUACOM produces for a recorded call, so they need the AI Analysis add-on described in [Speech To Text](/v2/docs/groups/speech-to-text); the summary, topics and action items they search are the ones [Call AI](/v2/docs/groups/call-ai) returns. This group holds the list, create, show, update and delete of a tracker and a switch to enable or disable one.\n\n## Workflow (what the portal does)\n\n1. **List**: [`GET /v2/keyword-trackers`](/v2/ref#/operations/keyword-trackers.index) answers every tracker of the account as a plain array; there is no paging and no filter. Each item is `id`, `tracker_name`, `account_id`, `keywords`, `is_active`, `filters`, `email_alerts` and `tag_ids` (the tag ids as a list of strings).\n2. **Create**: [`POST /v2/keyword-trackers`](/v2/ref#/operations/keyword-trackers.store) with:\n - `tracker_name` (required, at most 255 characters);\n - `keywords` (required, at most 1024 characters): the rule, see [Writing the rule](#writing-the-rule);\n - `is_active` (required boolean);\n - `filters`: whose calls are watched, a list of `{\"id\": \u2026, \"group\": \u2026}` entries, see [Who is watched, who is told](#who-is-watched-who-is-told);\n - `email_alerts`: who receives the alert, the same shape;\n - `tags`: ids from the call tag catalogue ([`GET /v3/call-tags`](/v2/ref#/operations/v3.call-tags.index)), as strings; they are attached to every call the tracker matches.\n The answer is the tracker as the list shows it.\n3. **Show**: [`GET /v2/keyword-trackers/{trackerId}`](/v2/ref#/operations/keyword-trackers.show). An id that is not one of your account's trackers answers `404`.\n4. **Update**: [`PUT /v2/keyword-trackers/{trackerId}`](/v2/ref#/operations/keyword-trackers.update) takes the same body as create and replaces the whole tracker: a list you leave out becomes empty.\n5. **Enable or disable**: [`PATCH /v2/keyword-trackers/{trackerId}/status/{status}`](/v2/ref#/operations/keywordTracker.setKeywordTrackerStatus) with `1` to enable or `0` to disable (any number other than `1` disables). It answers the tracker; a disabled tracker is kept but never matches.\n6. **Delete**: [`DELETE /v2/keyword-trackers/{trackerId}`](/v2/ref#/operations/keyword-trackers.destroy) answers `204`, also for an id that does not exist.\n\n```bash\ncurl -X POST 'https://api.api-nuacom.com/v2/keyword-trackers' \\\n -H 'Authorization: Bearer YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"tracker_name\": \"Cancellation risk\",\n \"keywords\": \"\\\"cancel\\\" | \\\"switch provider\\\"\",\n \"is_active\": true,\n \"filters\": [{\"id\": \"d12\", \"group\": \"User groups\"}],\n \"email_alerts\": [{\"id\": \"4821\", \"group\": \"Users\"}],\n \"tags\": [\"1001\"]\n }'\n```\n\n```json\n{\n \"id\": 7,\n \"tracker_name\": \"Cancellation risk\",\n \"account_id\": \"IE-00123\",\n \"keywords\": \"\\\"cancel\\\" | \\\"switch provider\\\"\",\n \"is_active\": true,\n \"filters\": [{\"id\": \"d12\", \"group\": \"User groups\"}],\n \"email_alerts\": [{\"id\": \"4821\", \"group\": \"Users\"}],\n \"tag_ids\": [\"1001\"]\n}\n```\n\n## How a tracker runs\n\nA tracker is evaluated once per call, when the transcript and analysis of the recording have been stored, some time after the call ends ([Speech To Text](/v2/docs/groups/speech-to-text) explains when a call is transcribed). A call that has no transcript, no extension, or an extension that is not linked to a user is never checked.\n\nFor each active tracker:\n\n1. The rule is tested against the summary followed by the full transcript, and separately against each topic and action item. The tracker matches when either test passes.\n2. `filters` decides whether the call is one you watch. With an `Everyone` entry every call of the account is watched; otherwise the extension on the call, the caller's or the called party's, must belong to one of the listed users or to a member of one of the listed teams. An empty list watches nobody.\n3. On a match, the tracker's tags are attached to the call (a tag already on it is not duplicated); they then show on the call row and in [`GET /v2/call-tags`](/v2/ref#/operations/callLog.callTags). Then one email goes to each user in `email_alerts` and to each member of the teams listed there; suspended users are skipped. The email names the tracker, the user on the call and the other party, gives the date and time and a link to the call, and shows the summary with the matched terms highlighted plus up to 12 lines of the transcript from the first highlighted line.\n\n### Who is watched, who is told\n\n`filters` and `email_alerts` hold the same kind of entries, each with a required `id` and `group`, both strings of at most 50 characters:\n\n| `group` | `id` | Meaning |\n| --- | --- | --- |\n| `Users` | the user's `user_id`, as a string (`\"4821\"`) | that user's calls are watched, or that user is emailed |\n| `User groups` | `d` followed by the team id (`\"d12\"`) | every member of the team |\n| `Everyone` | required but not read; send `\"0\"` | every call of the account. Only meaningful in `filters` |\n\nThe `d` prefix on `id` is what makes an entry a team; `group` is a label the API stores for you and acts on only when it is `Everyone`. User ids come from [`GET /v3/users`](/v2/ref#/operations/v3.users.users.index), team ids from [`GET /v3/teams`](/v2/ref#/operations/v3.teams.teams.index); see [Users](/v2/docs/groups/users).\n\n### Writing the rule\n\n`keywords` is one rule in the syntax below. Terms are matched as whole words, so `\"cancel\"` does not match \"cancellation\".\n\n| Rule | Matches when |\n| --- | --- |\n| `invoice` | the word appears. A bare term must be written in lower case; the text is compared in lower case |\n| `\"late payment\"` | the phrase appears, in any case |\n| `\"invoice\" + \"refund\"` | both appear |\n| `\"invoice\" \\| \"refund\"` | either appears |\n| `-\"refund\"` | the term is absent |\n| `\"invoice\" + (-\"refund\")` | the first appears and the second is absent |\n\n`|` is applied last: `\"a\" + \"b\" | \"c\"` means (a and b) or c. Parentheses only wrap a single term, as in `(-\"b\")`; they cannot regroup an `|`. The characters `+` and `|` always split the rule, even inside quotes. A rule that starts with `-` has to pass both tests, the text and the topics, so combine a negation with a positive term rather than using it alone.\n\n## Roles and access\n\n- Every endpoint of this group works on the account your API key belongs to, and any user of that account may call it: there is no account-admin check. A tracker belongs to the account, not to the user who created it.\n- Alerts and tags only happen for calls that are transcribed: the account needs an active AI Analysis add-on ([`GET /v2/speech-to-text/active`](/v2/ref#/operations/accountAddonStt.currentAddon)) and, with the Free add-on, an allowance that is not used up. Without it the trackers are stored but never match.\n- The recipients are not checked against call-log or recording permissions: everyone you list receives the transcript excerpt.\n\n## Pitfalls\n\n- Ids are strings: `\"tags\": [1001]` or `{\"id\": 12, \u2026}` answers `422`; send `\"1001\"` and `\"12\"`.\n- `PUT` replaces everything. Leave `tags` out and the tracker ends with no tags, answered as `tag_ids: [\"\"]` rather than `[]`; a tracker created without tags answers the same.\n- An empty `filters` list matches no calls. To watch every call add `{\"id\": \"0\", \"group\": \"Everyone\"}`.\n- `Everyone` in `email_alerts` emails nobody; list the users or teams.\n- A tracker with no recipients still tags the matching calls.\n- Commas are not separators: `invoice,refund` is matched as that literal text. Use `\"invoice\" | \"refund\"`.\n- A bare term with a capital letter never matches; quote it or write it in lower case.\n- Trackers are evaluated once, when the analysis is stored. Editing or enabling a tracker does not re-check earlier calls.\n- `DELETE` answers `204` for an id that does not exist, so a mistyped id looks like success." }, { "name": "Autodialer", "description": "The autodialer runs outbound campaigns: a list of numbers that one extension calls one after the other, with a pause between calls, a ring timeout and retries for the numbers that did not answer. The calls themselves are placed by the NUACOM portal in the agent's browser; the API holds what the dialer works from \u2014 the campaigns and their settings, the numbers with their status and retry counters, and the statistics. Numbers can be loaded from your own lists or picked from [Contacts](/v2/docs/groups/contacts).\n\n## Workflow (what the portal does)\n\n1. **Campaigns**: [`GET /v2/auto-dialer/campaigns`](/v2/ref#/operations/campaigns.index) lists them 15 per page (`page`), newest first, with an optional `status` filter. Account admins see every campaign; other users only those whose `sign_to` is their own extension. Each campaign carries `numbers_count` and a `stats` block.\n2. **Create**: [`POST /v2/auto-dialer/campaigns`](/v2/ref#/operations/campaigns.store) with `name` (up to 250 characters), `phone_number` (the caller ID, one of the account's own numbers), `delay` (seconds between calls, at least 1), `max_response_time` (seconds to let a call ring before hanging up, at least 1), `max_retries` (how many more times a number that did not answer is tried, 0 or more), `sign_to` (the extension number that runs the campaign, e.g. `\"32\"`), optional `time_to_recall` (the wait before such a number may be dialled again, at least 1), optional `status` (defaults to `initial`) and optional `contacts` (up to 2000 numbers to load at once). Answers `201` with the campaign.\n3. **Load numbers**: [`POST /v2/auto-dialer/campaign/{campaignId}/numbers/upload`](/v2/ref#/operations/autodialerCampaignNumber.upload) with `{\"numbers\": [\"+353861234567\", \"0861234568\"]}`, 1 to 2000 per request; the portal builds this list from a pasted text or a `.txt` file with one number per line. Numbers are validated for the account's country, normalised to international format, de-duplicated and skipped when already in the campaign; new ones start as `initial`. `204`. To add one number, [`POST /v2/auto-dialer/campaign/{campaignId}/numbers`](/v2/ref#/operations/numbers.store) with `number` or `contact_id` (the contact's mobile number, or its first number when it has no mobile) and an optional `status`; `201` with the number.\n4. **Read**: [`GET /v2/auto-dialer/campaigns/{campaignId}`](/v2/ref#/operations/campaigns.show) for one campaign, [`GET /v2/auto-dialer/campaign/{campaignId}/numbers`](/v2/ref#/operations/numbers.index) for its numbers (1000 per page, newest first) and [`GET /v2/auto-dialer/campaign/{campaignId}/numbers/{numberId}`](/v2/ref#/operations/numbers.show) for one of them.\n5. **Dial** (portal only): the agent presses Play in the portal. The browser places the calls through the agent's extension, moves the campaign to `in_progress` with [`PUT /v2/auto-dialer/campaigns/{campaignId}`](/v2/ref#/operations/campaigns.update), records the outcome of each attempt on the number with [`PUT /v2/auto-dialer/campaign/{campaignId}/numbers/{numberId}`](/v2/ref#/operations/numbers.update) (`status`), and sets the campaign back to `initial` when it stops. The API does not start or stop dialling.\n6. **Statistics**: [`GET /v2/auto-dialer/campaigns/{campaignId}/stats`](/v2/ref#/operations/autodialerCampaign.stats) answers `{\"answered\": 10, \"not_answered\": 10, \"all\": 20, \"percentage\": 50}`: the counts of numbers in those statuses, the total, and the integer share of numbers that are finished (`answered` or `voicemail`; a `not_answered` number is not finished because it may be retried). The same block is embedded in every campaign as `stats`.\n7. **Across campaigns**: [`GET /v2/auto-dialer/calls`](/v2/ref#/operations/autodialer.autodialerCall) lists the numbers of all the account's campaigns, filtered by `campaign_id`, `agent` (the campaign's `sign_to`), `status`, `date_from` and `date_to` (`Y-m-d` or `Y-m-d H:i:s`; a bare date covers the whole day), paginated with `per_page` (1\u20131000, default 50).\n8. **Edit and delete**: `PUT \u2026/campaigns/{campaignId}` takes any subset of the fields of step 2, plus `contacts` to load more numbers, and answers `202` with the campaign; `PUT \u2026/numbers/{numberId}` takes `number` and `status` and answers `202`. [`DELETE /v2/auto-dialer/campaigns/{campaignId}`](/v2/ref#/operations/campaigns.destroy) and [`DELETE /v2/auto-dialer/campaign/{campaignId}/numbers/{numberId}`](/v2/ref#/operations/numbers.destroy) answer `204`.\n\n```bash\ncurl -X POST 'https://api.api-nuacom.com/v2/auto-dialer/campaigns' \\\n -H 'Authorization: Bearer YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"name\": \"October renewals\",\n \"phone_number\": \"+35312345678\",\n \"delay\": 15,\n \"max_response_time\": 30,\n \"max_retries\": 2,\n \"time_to_recall\": 60,\n \"sign_to\": \"32\",\n \"contacts\": [\"+353861234567\", \"+353871234568\"]\n }'\n```\n\n## Vocabulary\n\nA campaign's `status` is free text up to 50 characters; the portal uses `initial` (idle) and `in_progress` (dialling).\n\nA number's `status` is one of:\n\n| Status | Meaning | Finished |\n| --- | --- | --- |\n| `initial` | Not dialled yet. | no |\n| `in_progress` | Being dialled now. | no |\n| `not_answered` | Did not answer; eligible for a retry. | no |\n| `answered` | Answered and completed. | yes |\n| `voicemail` | Reached voicemail. | yes |\n\nEach number also carries `retries` (attempts made so far) and `last_retry` (when the last attempt was made). The portal's dialer reads them against the campaign settings: a number that did not answer is dialled again while `retries` is below `max_retries`, and only once `time_to_recall` has passed since `last_retry`.\n\n## Dial status lifecycle\n\n```mermaid\nstateDiagram-v2\n [*] --> initial: loaded via upload, numbers.store or contacts\n initial --> in_progress: dialled\n in_progress --> not_answered: no answer\n in_progress --> answered: answered and completed\n in_progress --> voicemail: reached voicemail\n not_answered --> in_progress: retries < max_retries and time_to_recall elapsed\n answered --> [*]\n voicemail --> [*]\n```\n\n## Roles and access\n\n- Every endpoint is open to any authenticated user of the account; there is no admin-only operation.\n- Only the campaign list is filtered by role: non-admins get the campaigns assigned to their extension (none at all when their user has no extension). Every other endpoint checks only that the campaign belongs to the account, so a non-admin who knows a campaign id can read and change it.\n- A campaign or number of another account, or an unknown id, answers `404` `{\"message\": \"Resource not found!\"}`.\n\n## Pitfalls\n\n- Two path shapes: campaigns live under `/v2/auto-dialer/campaigns/{campaignId}`, numbers under `/v2/auto-dialer/campaign/{campaignId}/numbers` (singular `campaign`).\n- `sign_to` is the bare extension number (`\"32\"`), whatever the example in the reference suggests; any other value answers `422` `The selected extension does not belong to your account.`. A non-admin whose extension is not the campaign's `sign_to` does not see it in the list.\n- `phone_number` must be one of the account's numbers, in any national or international spelling; it is stored as sent.\n- Adding one number with `number` stores the string as sent: no format check beyond 30 characters, no normalisation and no duplicate check, unlike `upload` and `contacts`. Prefer `upload`, or `contact_id`, which resolves and normalises the contact's number. Sending neither answers `422` `A number or contact_id is required`; a contact without a phone number answers `422`; a contact of another account `404`.\n- `retries` and `last_retry` are maintained by the dialer: the API reports them but does not accept them as input \u2014 `PUT \u2026/numbers/{numberId}` takes `number` and `status` only.\n- Successful updates answer `202`, not `200`.\n- `date_from` and `date_to` on `/v2/auto-dialer/calls` filter by the date the number was added to its campaign, not by `last_retry`.\n- Lists are paginated resources (`data`, `links`, `meta`); a single campaign or number is returned bare, without a `data` wrapper.\n- Timestamps are ISO 8601 in UTC (`2022-11-24T11:15:54.000000Z`). With the account's ISO dates option, `created_at` and `updated_at` follow the requested timezone while `last_retry` stays in UTC." }, { "name": "Reports", "description": "Reports are the account's call history aggregated or filtered for one question: which callers still need a call back, who calls most, when the lines are busiest, how much each extension handles, and which queue calls an agent let ring. This group holds the missed-call report (a user view, an account-wide view and a CSV export of each), the top-callers report, the busy-hours reports by hour, day and month, the two extension-usage reports and the queue skipped-calls report. All but the last one are built from the same rows as [Call Logs](/v2/docs/groups/call-logs) and take the same filters; the emailed summary of the missed-call report is configured in [Reports / Missed Call Follow-up](/v2/docs/groups/reports-missed-call-follow-up).\n\n## Workflow (what the portal does)\n\nThe call-log reports read their inputs from the query string (`GET`) or the request body (`POST`), as plain comma-separated strings. The period is `from_date` and `to_date`, see [Period and filters](#period-and-filters); every other call-log filter (`type`, `extensions`, `queues`, `number`, `search_for`, \u2026) applies too.\n\n1. **Missed calls to follow up**: [`GET /v2/missed-call-report`](/v2/ref#/operations/callLog.missedCalls) lists inbound calls that were not answered. The portal sends `type=missed,include_voicemail,include_playback,group_missed_calls` (unanswered inbound calls, including those that ended in voicemail or an announcement, one row per caller who has not been called back) and `empty=src_extension` (callers from outside the account only), with `from_date`, `to_date`, `sort_by` (`call_date`, `from`, `from_ext`, `to` or `to_ext`; `call_date` by default), `sort_dir` (`ASC` by default), `per_page` (default 25, no maximum) and `page` (default 1). The answer is `{\"_embedded\": [rows], \"_links\": {\u2026}, \"page_count\": , \"page_size\", \"total_items\"}`; `_links` holds `next` and `last` while there are more pages and `prev` and `first` after the first one, and a `Link` header repeats them. Each row carries `id`, `call_date`, `direction`, `status` and `last_app` (how and where the call ended), the caller as `from` / `from_local` / `from_name`, the number dialled as `to` / `to_local` / `to_name`, the extensions involved as `from_ext` / `from_extension` and `to_ext` / `to_extension` (number and name), the queue the call was waiting in as `call_in_queue` / `call_in_queue_name`, and `original_sip_call_id`.\n2. **Account-wide view**: [`GET /v2/admin-missed-call-report`](/v2/ref#/operations/callLog.missedCallsAdmin) takes the same inputs and answers the same shape, but ignores the caller's call-log permissions: every missed call in the account.\n3. **CSV export**: [`POST /v2/missed-call-report-export`](/v2/ref#/operations/callLog.missedCallsExport) and [`POST /v2/admin-missed-call-report-export`](/v2/ref#/operations/callLog.missedCallsAdminExport) take the same filters (the portal posts `from_date`, `to_date`, `type` and `empty`) and answer `204`: the file is built in the background and emailed to the user behind the token, newest call first, with the columns Date, Call Type, From Name, From, To Name, To, To Ext, To Ext Name, Queue No and Queue Name. Dates in the file are `Y-m-d H:i:s` in the `X-Timezone` you send (an IANA name; anything else is replaced by Europe/Dublin), or in your profile timezone without it. The user export sees what the user sees; the admin export covers the whole account.\n4. **Top callers**: [`GET /v2/top-callers-report`](/v2/ref#/operations/callLog.topCallers) with `from_date`, `to_date` and `type`: `incoming` ranks the callers of answered inbound calls by their number, `outgoing` the numbers dialled on answered outbound calls; add `missed` or `unanswered` to count the unanswered ones as well (`type=incoming,missed`). The answer is `{\"_embedded\": [{\"group\": \"+353861234567 - Jane Doe\", \"calls_count\": 12, \"contacts\": {\u2026}}, \u2026], \"total_items\": 20}`: at most 20 rows, most calls first. `group` is the number alone when nothing names it, `number - name` when a phonebook or integration contact matches (`contacts` then carries that contact) or when the number is a system short code; withheld callers appear as `\u2026 - Anonymous`.\n5. **Busy hours**: [`POST /v2/hourly-busy-hours-report`](/v2/ref#/operations/callLog.hourlyBusyHours), [`POST /v2/daily-busy-hours-report`](/v2/ref#/operations/callLog.dailyBusyHours) and [`POST /v2/monthly-busy-hours-report`](/v2/ref#/operations/callLog.monthlyBusyHours) count answered and missed calls per hour, day or month of the period. The portal sends `from_date`, `to_date`, `type` (`incoming,missed,include_voicemail,include_playback` by default, that is every inbound call) and optionally `number` to look at one of the account's numbers. The answer is an array with one entry per bucket of the whole period, zero-filled: `[{\"period\": \"2026-05-04 09:00\", \"answered_value\": 14, \"missed_value\": 3}, \u2026]`; `period` is `Y-m-d H:00`, `Y-m-d` or `Y-m`. `answered_value` counts calls with status `ANSWERED`, `missed_value` every other status (`NO ANSWER`, `BUSY`, `FAILED`).\n6. **Extension usage**: [`POST /v2/extension-call-direction-report`](/v2/ref#/operations/callLog.directionExtensionUsage) counts calls per extension and [`POST /v2/extension-call-duration-report`](/v2/ref#/operations/callLog.durationExtensionUsage) sums their duration in seconds. Inputs are `from_date`, `to_date`, `extensions` (comma-separated extension numbers; empty for all of them) and `type` (the portal sends `outgoing,unanswered,incoming,missed,include_voicemail,include_playback,include_internal` when nothing is ticked). Only calls with an extension on at least one side are counted. The answer is an array with one object per extension, ordered by extension number; the duration report names its columns `Voicemail_duration` \u2026 `Total_duration`:\n\n ```json\n [{\"Extension\": \"Jane Doe - 101\", \"Voicemail\": 0, \"Playback\": 1, \"Internal\": 3, \"Incoming\": 12, \"Missed\": 2, \"Outgoing\": 8, \"Unanswered\": 1, \"Total\": 27}]\n ```\n\n `Extension` is `name - number`, or the bare number for an extension without a name. A call counts once for the extension that made it and once for the one that received it, so an internal call appears in two rows. Durations are the connected time of answered calls and the ring time of the others.\n7. **Queue skipped calls**: [`GET /v2/reports/queue-skipped-calls`](/v2/ref#/operations/v2.getQueueSkippedCalls) with `queue` (queue number), `from` and `to` (both required, `to` after `from`) and optionally `agent` (extension number) returns the queue events of every call in that queue that an agent (that agent, when given) let ring without answering. The answer is a plain array ordered by call, then by time, one entry per event: `{\"call_id\": \"1651753116.134\", \"queue\": \"100\", \"agent\": \"10\", \"caller_id\": \"0861234567\", \"status\": \"RINGNOANSWER\", \"event_date\": \"May 4 2026 09:12:30\"}`. The portal opens it from the Queue Reports page as the call flow of a queue or of an agent; see [Queues](/v2/docs/groups/queues) for queue numbers and [Reading the queue events](#reading-the-queue-events) for `status`.\n\n```bash\n# Callers of May 2026 still waiting for a call back, Dublin time, 25 per page\ncurl 'https://api.api-nuacom.com/v2/missed-call-report?from_date=2026-05-01%2000:00:00&to_date=2026-05-31%2023:59:59&type=missed,include_voicemail,include_playback,group_missed_calls&empty=src_extension&per_page=25&page=1' \\\n -H 'Authorization: Bearer YOUR_API_KEY' \\\n -H 'X-Timezone: Europe/Dublin'\n```\n\n## Period and filters\n\n- `from_date` and `to_date` take `Y-m-d` (expanded to `00:00:00` and `23:59:59`) or `Y-m-d H:i:s`. They are wall-clock values read in the `X-Timezone` header (or `timezone` parameter) if you send one, otherwise in the profile timezone of the user behind the token, otherwise Europe/Dublin; see [Dates and timezones](/v2/docs/dates-and-timezones).\n- Send both. With only one, or none, the report covers the last month: every call since one month before now. There is no maximum range in the API; the portal limits its own date pickers (31 days on the missed-call report).\n- Output: `call_date` and the busy-hours `period` are wall-clock `Y-m-d H:i:s` in your profile timezone on the legacy contract. With the ISO dates option, `call_date` becomes ISO 8601 in the `X-Timezone` offset (UTC by default) and `period` is labelled in the timezone your dates were read in. The CSV exports keep `Y-m-d H:i:s`.\n- `type` is a comma-separated list. Naming a direction excludes the calls that ended in voicemail or in an announcement unless you add the `include_*` values; omitted altogether, every call counts.\n\n| `type` value | Selects |\n|---|---|\n| `incoming` | inbound calls that were answered |\n| `missed` | inbound calls that were not answered |\n| `outgoing` | outbound calls that were answered |\n| `unanswered` | outbound calls that were not answered |\n| `include_internal` | calls between two extensions |\n| `include_voicemail`, `include_playback` | keep the calls that ended in voicemail or in an announcement |\n| `group_missed_calls` | one row per caller, keeping only callers who were not called back, and did not call again and get through, within the period |\n\n- `extensions` (as source or destination extension), `queues`, `number` (as caller or as number dialled; one or two values match as substrings, three or more exactly), `incoming_number`, `outgoing_number` and `search_for` narrow the calls as on the call log; `empty=src_extension` keeps calls from outside the account.\n\n## Reading the queue events\n\nEvery event of a skipped call is listed, not only the skip. `status` is one of:\n\n| `status` | Meaning |\n|---|---|\n| `RINGNOANSWER` | the agent was rung and declined, or the ring timed out |\n| `COMPLETEAGENT`, `COMPLETECALLER` | the call was answered by an agent and then ended, hung up by the agent or by the caller |\n| `ABANDON` | the caller hung up while waiting |\n| `EXITWITHTIMEOUT` | the call timed out in the queue and moved to another step or hung up |\n| `TRANSFER` | the call was transferred to another agent or number |\n\nThe other values (`inQue`, `CONNECT`, `EXITWITHKEY`, `EXITEMPTY`) are the queue events they name. `call_id` is shared by every event of the same call; `queue` and `agent` are the queue number and the extension number; `caller_id` is the caller's number as the queue saw it, empty on some events; `event_date` is `M j Y H:i:s` in the caller's profile timezone.\n\n## Roles and access\n\n- Every endpoint is open to any authenticated user, except [`POST /v2/admin-missed-call-report-export`](/v2/ref#/operations/callLog.missedCallsAdminExport), which needs an account admin and answers `403` with the body `\"Forbidden\"` otherwise.\n- The user reports (missed calls and its export, top callers, busy hours, extension usage) follow the call-log visibility rules: an admin, or a user whose call-log permission is \"all\", sees the whole account; everyone else only the calls on their own extension and on the numbers, extensions and queues granted to them, and with no grants the answer is empty, not `403`.\n- The account-wide missed-call list and export, and the queue skipped-calls report, cover the whole account regardless of grants.\n- The ISO dates option (per account) changes the date formats as described above; the skipped-calls `event_date` is always `M j Y H:i:s` in the caller's profile timezone and ignores `X-Timezone`.\n\n## Pitfalls\n\n- The generated reference shows no parameters for the call-log reports: they read the raw request. Use the inputs above, as comma-separated strings (`extensions=101,102`, not `extensions[]`).\n- The missed-call endpoints do not add the missed filter themselves. Without `type=missed` they list every call of the period; without `group_missed_calls` every unanswered leg of a call is a row, called back or not.\n- An unparsable date silently becomes 1970-01-01, and a value carrying a UTC offset is shifted again by the input timezone. Send wall-clock values and set `X-Timezone`.\n- `page_count` is the current page, not the number of pages; paginate on `total_items` and `page_size`. `_links` is `[]` on a single page and an object otherwise.\n- Missed-call rows whose caller is not a dialable number (withheld numbers, park and speed-dial codes) are dropped after pagination: a page can hold fewer rows than `page_size`, and `total_items` is only corrected when everything fits on one page.\n- Missed-call rows carry no `call_id` or `call_unique_id`; to reach the recording or notes of a call, find it on [`GET /v2/call-log`](/v2/ref#/operations/callLog.callLog) by date and number.\n- Exports are asynchronous and arrive by email; the request returns no job id and answers `204` even when nothing matches. They ignore `sort_by` and, unlike the call-log export, have no row limit.\n- Top callers always answers `total_items: 20`, whatever the number of rows. `incoming` and `outgoing` count answered calls only, and numbers shorter than six characters (extensions, short codes) are dropped. Without `type` the report groups every call, internal ones included, by the number dialled.\n- Busy hours counts whatever `type` selects: omit it and outbound and internal calls are counted too.\n- On the extension-usage reports `extensions=all` answers an empty array; omit the parameter, or send it empty, to get every extension. The duration report fails with `500` when `extensions` is missing altogether: always send it, empty if need be.\n- Queue skipped calls: `from` and `to` are compared with the stored event time as given, `X-Timezone` is ignored, and a date-only `to` ends at midnight, so send `to=2026-05-31 23:59:59`. `agent` picks which calls are included, not which rows: the events of the other agents on those calls are listed too. Validation errors answer `422` with `errors` alone, no `message`." }, { "name": "Reports / Missed Call Follow-up", "description": "The Missed Call Follow-up report, [`GET /v2/missed-call-report`](/v2/ref#/operations/callLog.missedCalls) in [Reports](/v2/docs/groups/reports), lists the callers who were not answered and have not been called back. This sub-group schedules an email summary of it: one setting per account and report page, holding the recipients, the period the email covers, the hour it is sent at and the timezone of both. Four endpoints: read the setting, create or update it, delete it, and send the email now.\n\n## Workflow (what the portal does)\n\nThe portal's **Get Email Updates** button on the report, shown to account admins only, drives all four:\n\n1. **Read**: [`GET /v2/missed-call-followup-settings/{reportId}`](/v2/ref#/operations/missedCallFollowupSetting.show) with the report id (`34`, see [Report ids](#report-ids)) pre-fills the form. It answers `200` with `{\"data\": {\"id\", \"account_id\", \"report_id\", \"email\", \"period\", \"hour\", \"timezone\", \"is_enabled\"}}`, or `200` with `{\"data\": null, \"message\": \"No settings found for this report.\"}` when nothing is configured yet, not `404`. `timezone` is the effective one: the value saved, or the account's timezone when none was.\n2. **Save**: [`POST /v2/missed-call-followup-settings`](/v2/ref#/operations/missedCallFollowupSetting.store) creates the setting or replaces the existing one for that `report_id`. The portal sends `email`, `report_id` and `timezone` and leaves the rest to the defaults.\n\n | Field | Required | Rules |\n |---|---|---|\n | `email` | yes | One or more addresses separated by commas, 2000 characters at most; every address must be valid |\n | `report_id` | yes | `34` or `340` |\n | `period` | no | `daily` (default), `weekly` or `monthly` |\n | `hour` | no | The hour to send at, as `HH:00`; `08:00` by default |\n | `timezone` | no | An IANA name such as `Europe/Dublin`; the account's timezone by default |\n | `is_enabled` | no | `true` by default; `false` keeps the setting but stops the emails |\n\n It answers `200`, on create as well, with `{\"message\": \"Settings saved successfully.\", \"data\": {\u2026}}`, the same `data` as the read. Validation failures answer `422` with `errors`, for instance `Invalid report ID. Must be 34 or 340.`, `Invalid hour format. Must be in HH:00 format (e.g., 08:00).` or `Invalid email address(es): \u2026`.\n3. **Delete**: [`DELETE /v2/missed-call-followup-settings/{reportId}`](/v2/ref#/operations/missedCallFollowupSetting.destroy) answers `200` with `{\"message\": \"Settings deleted successfully.\"}`, or `404` with `{\"message\": \"No settings found to delete.\"}`.\n4. **Send now**: [`POST /v2/missed-call-followup-settings/{reportId}/send-now`](/v2/ref#/operations/missedCallFollowupSetting.sendNow) queues the email immediately, with the saved period and recipients, and answers `200` with `{\"message\": \"Report has been queued and will be sent shortly.\"}`, or `404` when no setting exists for that id. NUACOM enables it per account; elsewhere it answers `403` with `{\"message\": \"This endpoint is not available for your account.\"}` and the portal hides the button.\n\n```bash\ncurl -X POST https://api.api-nuacom.com/v2/missed-call-followup-settings \\\n -H 'Authorization: Bearer YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"email\": \"reception@example.com,manager@example.com\", \"report_id\": 34, \"period\": \"daily\", \"hour\": \"08:00\", \"timezone\": \"Europe/Dublin\"}'\n# \u2192 {\"message\": \"Settings saved successfully.\", \"data\": {\"id\": 17, \"account_id\": \"IE-00123\", \"report_id\": 34, \"email\": \"reception@example.com,manager@example.com\", \"period\": \"daily\", \"hour\": \"08:00\", \"timezone\": \"Europe/Dublin\", \"is_enabled\": true}}\n```\n\n## The scheduled email\n\n- **When**: NUACOM's scheduler runs once an hour and sends a setting when the current hour in its timezone equals `hour`, so the email arrives within that hour. `daily` sends every day, `weekly` on Sundays, `monthly` on the first day of the month.\n- **Which period**: `daily` covers yesterday, `00:00:00` to `23:59:59` in the setting's timezone; `weekly` the seven days before today; `monthly` from the same day of the previous month to yesterday, which is the previous calendar month when sent on the 1st.\n- **What it says**: the subject is `NUACOM - Missed Call Follow-up Report` (your own brand name on a branded account). The body is titled *Yesterday's*, *Last Week's* or *Last Month's* *Missed Calls Report* and reads \"On you had: Missed N call(s), Returned N call(s), Remaining N call(s)\", with a link to the report page in the portal. When all three are zero it says you had zero missed calls instead.\n- **How it counts**: *Missed* is the number of callers from outside the account whose inbound call was not answered in the period, calls that ended in voicemail or an announcement included, one per number, leaving out those who were called back or who called again and got through before the period ended, and leaving out withheld numbers and system short codes: the rows the account-wide report shows for that period. *Returned* is how many of those numbers have since received an answered outbound call from the account, up to the moment the email is generated. *Remaining* is the difference.\n- **Who receives it**: every address in `email`, in one message; recipients need not be portal users.\n- **What it does not do**: it covers the whole account, with no queue or extension filter, and it does not list the calls. The queue each call was waiting in is in the report rows (`call_in_queue`, `call_in_queue_name`) and in the CSV export, see [Reports](/v2/docs/groups/reports).\n- **When it stays silent**: a disabled setting, an account that is not active, or an `email` without a single valid address: nothing is sent and nothing is reported back.\n\n## How the scheduled summary is sent\n\n```mermaid\nflowchart TD\n save[\"POST /v2/missed-call-followup-settings
email, period, hour, timezone\"] --> wait[\"Scheduler runs once an hour\"]\n wait --> hourMatch{\"Current hour in setting's timezone == hour?\"}\n hourMatch -- \"no\" --> wait\n hourMatch -- \"yes\" --> gate{\"is_enabled, account active,
email has a valid address?\"}\n sendNow[\"POST .../{reportId}/send-now\"] --> gate\n gate -- \"no\" --> silent[\"Nothing sent, nothing reported back\"]\n gate -- \"yes\" --> compute[\"Compute Missed / Returned / Remaining for the period\"]\n compute --> email[\"Email every address in email, one message\"]\n```\n\n## Report ids\n\n`report_id` names the portal report page the setting belongs to and the email links to: `34` is the Missed Call Follow-Up report, the view of [`GET /v2/missed-call-report`](/v2/ref#/operations/callLog.missedCalls); `340` is its account-wide version, [`GET /v2/admin-missed-call-report`](/v2/ref#/operations/callLog.missedCallsAdmin). The two ids hold independent settings, but the email is the same for both: account-wide counts, as above. The portal reads and saves `34` from both pages, so a setting saved under `340` is never shown there.\n\n## Roles and access\n\n- All four endpoints require an account admin; any other user gets `403` with the body `\"Forbidden\"`. An API key acts as the admin who created it.\n- The setting belongs to the account, not to the user who saved it: every admin reads and changes the same one.\n- Send now is additionally restricted to the accounts NUACOM has enabled it for (`403` with a `message` otherwise).\n\n## Pitfalls\n\n- `hour` must be zero-padded: `8:00` passes validation but never matches the scheduler's hour, so the email is never sent. Send `08:00`.\n- Saving replaces the whole setting. An omitted `period`, `hour`, `timezone` or `is_enabled` goes back to its default; send every field each time, not only the one you change.\n- The read answers `200` with `data: null` when nothing is configured; only the delete answers `404`.\n- Send now answers `200` \"queued\" even when the setting is disabled, the account is not active or no recipient is valid; in those cases nothing is sent.\n- Only `34` and `340` are accepted on save; the read, delete and send-now endpoints accept any integer and simply find nothing.\n- `timezone` must be an IANA name; abbreviations and offsets are rejected with `Invalid timezone.`\n- The date in the email is the first day of the period: on a weekly or monthly report it is not the day the email was sent." }, { "name": "Conversations", "description": "Conversations is the messaging module: one thread per contact and channel, with the same message, participant and delivery-status shapes for SMS (`channel_type` 1), WhatsApp (2) and MMS (3). This guide covers the thread endpoints, delivery statuses, assignment rules, webhooks and prices. What each channel needs before you can send is in its own guide: [Conversations / SMS](/v2/docs/groups/conversations-sms) (credit, sender names, templates, MMS, the legacy history endpoints) and [Conversations / WhatsApp](/v2/docs/groups/conversations-whatsapp) (sender, templates, media, the 24-hour window). Forwarding inbound SMS to email is configured in the portal (**Settings \u2192 SMS**).\n\n## Vocabulary\n\n- A **conversation** has an `id` (UUID), a `channel_type`, the `sender_id` it is sent from (your sender name or number), `participants` (`participant_type` `phone_number`, `email` or `user`; `participant_id`; `is_system_user` for your own users), `is_group`, `assigned_to_id` / `assigned_department_id`, `is_pinned`, `is_active` (`false` once archived), `unread_count`, `last_message_at` and, for WhatsApp, `expires_at` (the end of the 24-hour reply window). `channels` lists every channel the same contact has written on.\n- A **message** has `direction` (`inbound` / `outbound`), `message_type` (0 text, 5 image, 6 video, 7 file, 8 location, 9 audio, 10 sticker, 11 contact), `content`, `content_url`, `attachments` (one entry per media file with `content_url`, `thumbnail_url`, `mime_type`, `file_size`), `metadata` (`template_id` and `template_variables` for a template, `location`, `media`, and `media_error` when an inbound file could not be fetched), `scheduled_for`, `is_draft` and `statuses`: one row per recipient with `status` (0 pending, 1 sent, 2 delivered, 3 read, 4 failed, 5 scheduled), `error_code`, `error_description`.\n\n## Workflow (what the portal does)\n\n1. **The inbox**: [`GET /v2/conversations`](/v2/ref#/operations/conversation.index) lists the account's threads, newest activity first. Filters: `search` (number, name or text), `channel` (1, 2 or 3), `from_date` / `to_date` (`Y-m-d`, the portal defaults to the last 31 days), `status` (last message status, 0\u20135), `assigned_to_id`, `is_active` (`0` to include archived threads), `is_group`, `unread=1`, `unassigned=1`, `expires_in_hours` (WhatsApp windows closing soon; the last three drop pagination and return up to 500 rows), `sorts` (comma-separated, `-` for descending, for example `is_pinned,-last_message_at`), `page`, `per_page` (default 15). The response is paginated: `data`, `total`, `per_page`, `current_page`, `last_page`, `from`, `to`. [`GET /v2/conversations/unread-count`](/v2/ref#/operations/conversation.unreadCount) is the badge counter.\n2. **Open a thread**: [`GET /v2/conversations/{conversation}`](/v2/ref#/operations/conversation.show) returns the conversation with `participants` and its non-draft `messages` in chronological order, and marks it read for the calling user. WhatsApp messages are included only when the account has the WhatsApp feature.\n3. **Reply**: [`POST /v2/conversations/{conversation}/messages`](/v2/ref#/operations/conversation.addMessage) with `content`, or media as `content_url` / `content_file` (WhatsApp) or `media_ids` (MMS), or a template as `metadata.template_id` plus `metadata.template_variables`. Optional `scheduled_for`, `is_draft`, `opt_in` / `opt_out` (SMS), and `channel_type` to pick the channel on a thread that has both SMS and WhatsApp. Answers `201` with the message; an archived thread is restored. `402` means no credit, `400` carries the domain `code` of a failed send (see the SMS guide), `422` a validation failure or a closed WhatsApp window.\n4. **Start a thread**: [`POST /v2/conversations`](/v2/ref#/operations/conversation.store) with `channel_type`, `sender_id`, either `participants[]` or, for SMS campaigns, `contacts` (comma-separated numbers), `groups` (contact group ids) or `message_contacts` (reuse the recipients of an earlier message), and `message` (`content`, `content_url`, `content_file`, `media_ids`, `metadata.template_id`, `metadata.template_variables`, `scheduled_for`). An existing thread with the same contact is reused. A single recipient answers `201` with the conversation; a bulk send answers `201` with `success_count`, `failed_count`, `total_count` and, when the landline filter dropped numbers, `warning_code`, `warning` and `warning_detail`.\n5. **Schedule and cancel**: `scheduled_for` is `Y-m-d H:i:s`, must be in the future and is read in the user's timezone (or `X-Timezone`). The message sits with status 5 until delivery; [`DELETE /v2/conversations/{conversation}/messages/{message}`](/v2/ref#/operations/conversation.cancelScheduledMessage) cancels it and refunds the reserved credit.\n6. **Organise**: [`PATCH \u2026/archive`](/v2/ref#/operations/conversation.archive) (no body), [`PATCH \u2026/pin`](/v2/ref#/operations/conversation.pin) (`is_pinned`, omit to toggle), [`PATCH \u2026/assign`](/v2/ref#/operations/conversation.assign) (`user_id` or `department_id`, `null` to unassign; account admin), [`PATCH \u2026/read-status`](/v2/ref#/operations/conversation.changeReadStatus) (`status` `read` or `unread`).\n7. **Delivery**: [`GET /v2/conversations/messages/{messageId}`](/v2/ref#/operations/v2.getMessageInfo) is one message or, with `is-bulk=1`, the bulk group it belongs to; [`POST /v2/conversations/messages/{message}/statuses`](/v2/ref#/operations/v2.getMessageStatuses) lists the per-recipient statuses of a message or bulk group (`is-bulk`, `filter[search]` by number, `filter[status]`, `type`, `start`, `length`), each with `status`, `error_code`, `error_description` and `cost`.\n8. **Rules**: [`GET /v2/conversations/settings`](/v2/ref#/operations/settings.index) and [`POST /v2/conversations/settings`](/v2/ref#/operations/settings.store) (account admin) hold, per channel key (`sms`, `whatsapp`), `auto_assigning` rules (`numbers[]` \u2192 `assign_to {type: user|department, id}`) and `time_to_respond` rules (`numbers[]` \u2192 minutes); `available_numbers` lists the numbers you can put in a rule. The whole settings object is replaced on every save.\n9. **Be told, not poll**: [`POST /v2/webhook-subscriptions`](/v2/ref#/operations/webhook-subscriptions.webhook-subscriptions.store) with `type` `message_received` or `message_sent` sends every inbound or outbound message of any channel to your URL (payloads and delivery rules in the [Webhooks](/v2/docs/groups/webhooks) guide).\n10. **Prices**: [`GET /v2/account/messaging-rates-countries`](/v2/ref#/operations/v2.getAccountMessagingRatesCountries) then [`GET /v2/account/messaging-rates?country_code=IE`](/v2/ref#/operations/v2.getAccountMessagingRates): one row per channel (1 SMS, 2 WhatsApp with `wa_message_type`, 3 MMS) with the per-message `price` in the account currency.\n\n## Roles and access\n\n- Any authenticated user can list, open, start and reply; `assign` and the rules endpoints need an **account admin** (`403` otherwise). Opening a thread the user may not see answers `403`.\n- the WhatsApp for Business add-on enables channel 2 and the MMS option enables `media_ids` on channel 1; without them the input is ignored or answers code 6101.\n- The ISO dates option (per account) returns every timestamp as ISO 8601 in the requested `X-Timezone`; without it the thread and message timestamps are ISO 8601 in UTC with microseconds (`2026-05-01T13:30:00.000000Z`) and `X-Timezone` is ignored. See [Dates and timezones](/v2/docs/dates-and-timezones).\n\n## Pitfalls\n\n- `channel_type`, `message_type` and every `status` are integers; `direction` is a string.\n- One contact, one thread: a number that writes to you on SMS and on WhatsApp shares a conversation, with both channels in `channels`. Send `channel_type` with the reply, or the thread's default channel is used.\n- A WhatsApp thread with `expires_at` in the past accepts templates only; see the WhatsApp guide. SMS threads have `expires_at: null`.\n- An inbound WhatsApp file that could not be fetched arrives as a message without `content_url` and with `metadata.media_error.code` (`MEDIA_TOO_LARGE`, `UNSUPPORTED_MEDIA_TYPE`, `MEDIA_DOWNLOAD_FAILED`, `MEDIA_PROCESSING_FAILED`, `MEDIA_TOO_LARGE_PROVIDER`).\n- The SMS group still serves the older inbox, timeline and sent-history endpoints the portal's SMS pages use; they return the same messages in DataTables-style shapes and are documented in the SMS guide. New integrations should read through this group." }, { "name": "Conversations / Messages" }, { "name": "Conversations / Settings" }, { "name": "Conversations / SMS", "description": "SMS is the first channel of [Conversations](/v2/docs/groups/conversations): credit bought in packages, an approved sender name, optional templates, and three ways to send. This guide follows the portal's **New Message** page and its **Sent History** and **SMS Inbox** reports, and covers MMS, which is an SMS with `media_ids` for US, Canadian and Australian numbers. Forwarding inbound SMS to email is configured in the portal (**Settings \u2192 SMS**).\n\n## Before you send\n\n1. **Credit**: [`GET /v2/sms/packages`](/v2/ref#/operations/smsPackages.index) lists the packages (`id`, `amount` of credits, `cost`); [`POST /v2/top-up/sms/calculate`](/v2/ref#/operations/topUp.calculateSmsTopUp) with `package_id` quotes `amount`, `vat` and `total`; [`POST /v2/top-up/sms`](/v2/ref#/operations/topUp.smsTopUp) with `package_id` and a saved `payment_method` buys it (account admin; `400` with `error_code` `PAYMENT-INCOMPLETE` means the card needs 3-D Secure in the portal). Auto top-up is [`GET`](/v2/ref#/operations/topUp.getSmsAutoTopUp), [`POST`](/v2/ref#/operations/topUp.saveSmsAutoTopUp) (`package_id`, `payment_method`, `credit_limit`) and [`DELETE /v2/top-up/auto/sms`](/v2/ref#/operations/topUp.deleteSmsAutoTopUp). The balance is `sms_balance` on the account info.\n2. **Sender name**: [`GET /v2/sms/sender_names`](/v2/ref#/operations/smsSenderNames.getSenderNames) returns the approved names (`filter[channel]=sms`; `whatsapp` returns the WhatsApp numbers instead, each row carries `channel`). [`POST /v2/sms-sender-name`](/v2/ref#/operations/v2.requestSmsSenderName) (account admin) requests a new one: `sender_name` of 3 to 11 letters and digits, not digits only; `is_ireland_sender: true` when it will write to Irish numbers, which registers it with ComReg (the organisation and contact fields on the request are the ComReg details). Approval is manual; until then the name is absent from the list and an Irish send answers code 6004.\n3. **Templates** (optional): [`GET /v2/sms-templates`](/v2/ref#/operations/sms-templates.index) with `filter[channel]=1`, `filter[status]=1`, `filter[search]`, `filter[usage]` (`sms`, `10dlc`, `whatsapp`), `sort`, `page`, `per_page`; [`POST /v2/sms-templates`](/v2/ref#/operations/sms-templates.store) with `name`, `message_text`, `channel: 1`, `sender_id`, `opt_in`, `opt_out`; [`PUT`](/v2/ref#/operations/sms-templates.update) and [`DELETE /v2/sms-templates/{smsTemplate}`](/v2/ref#/operations/sms-templates.destroy). Status codes are the same as for WhatsApp (1 approved is the one you can send with).\n4. **US numbers (10DLC)**: a message to a `+1` number must reference an approved campaign template, otherwise the send answers code 6005 (6106 for an unverified toll-free number). The campaign is requested with the same `POST /v2/sms-templates`, adding `config` (`description`, `message_samples[]`, `use_cases[]` from `additional=campaign_use_cases`, `will_include_links`, `will_include_phone_numbers`, `opt_in_description`); the resulting template has `usage: \"10dlc\"`, cannot be edited, and lists the campaign's numbers in `sender_names`. Send it with `template_id`, and leave `from` empty to let NUACOM pick a campaign number.\n\n## Sending (what the portal does)\n\n- **The compose flow** (New Message page): [`GET /v2/sms/search-contacts?q=`](/v2/ref#/operations/sms.searchContacts) suggests up to five phonebook entries (`name`, `number`); [`POST /v2/sms/overview`](/v2/ref#/operations/sms.overview) stages the message and quotes it: `from`, `message`, recipients as `contacts` (comma-separated numbers), `groups` (contact group ids) or `message_contacts` (the reference of an earlier send), `template_id`, `time_to` for a scheduled send, `send_to_opted_in`, `opt_in` / `opt_in_message`, `opt_out` / `opt_out_message`, the landline filter (`ll_sniff`, `ll_sniff_from`, `ll_sniff_to`, `ll_last_activity`, `ll_visits_times`, `ll_visits_operation`), `channel_type` (1 SMS, 2 WhatsApp), `media_ids` for MMS and an `sms_session` of your own (any string up to 32 characters; reuse it to overwrite the staged draft). The answer carries `sms_session_id`, the valid, invalid and opted-out numbers, the segment count and the credit it will use. The portal's Send button then sends the staged draft; through the API, send with [`POST /v2/sms/send`](/v2/ref#/operations/sms.send) once the quote looks right.\n- **One call**: [`POST /v2/sms/send`](/v2/ref#/operations/sms.send) with `from`, `message`, `to[]` (`number`, optional `reference` echoed back), optional `send_at` (`Y-m-d H:i:s`; within two minutes it is sent at once), `template_id` and `media_ids`. The answer is `status` (`sent`, `scheduled`, `partial`, `failed`), `success_count`, `failed_count` and `numbers[]` with `number`, `international_number`, `reference`, `valid`, `message_id`, `status` and `error`. Keep `message_id`: it is the key for the status endpoints.\n- **In a thread**: [`POST /v2/conversations`](/v2/ref#/operations/conversation.store) and [`POST /v2/conversations/{conversation}/messages`](/v2/ref#/operations/conversation.addMessage) with `channel_type: 1`, described in the [Conversations](/v2/docs/groups/conversations) guide. This is the path for a reply inside an existing thread.\n- **Appointment reminders**: [`POST /v2/sms/appointment`](/v2/ref#/operations/sms.storeAppointment) with `contacts`, `sender_name`, `date_to_send`, `time_zone`, `send_before` (for example `1day`) and `sms_session` schedules the reminder relative to the appointment and answers `recipient`, `sms_message`, `scheduled_for` and `new_session_id`.\n- **MMS**: on accounts with the MMS option and every recipient in the US, Canada or Australia, upload each file first with [`POST /v2/mms/media`](/v2/ref#/operations/mms.uploadMmsMessageMedia) (multipart `file`; up to 10 files per message, images up to 5 MB, other files up to 500 KB) and pass the returned ids as `media_ids`. Images and videos are moderated asynchronously: poll [`GET /v2/mms/media/{mediaId}/moderation-status`](/v2/ref#/operations/mms.getMmsMediaModerationStatus) until `approved`, or the send answers 6105. MMS has its own rate in the messaging rates.\n\n**Result codes**: a failed send answers `400`, `402` or `422` with a `code` in the body. 6001 insufficient credit, 6002 no valid recipient, 6003 invalid sender, 6004 the sender is not approved for Irish numbers, 6005 US campaign not approved, 6006 delivery failed, 6007 scheduling error, 6008 partial bulk failure, 6009 whole bulk failed, 6010 draft not found, 6011 message limit reached, 6012 too many requests, 6013 auto top-up failed, 6014 send failed after the top-up; 6101 MMS disabled, 6102 MMS country not supported, 6103 too many files, 6104 media not found, 6105 media not approved yet, 6106 toll-free number not verified.\n\n## Reading\n\n- **New integrations** read through [`GET /v2/conversations`](/v2/ref#/operations/conversation.index) and the message status endpoints of the Conversations guide.\n- **Sent History**: [`POST /v2/sms/history`](/v2/ref#/operations/v2.getSmsMessages) is the report behind the portal's Sent History page, in DataTables form: `iDisplayStart`, `iDisplayLength`, `sSearch`, `type` (message type filter), `search_by_number` and `sEcho` in; `sEcho`, `iTotalRecords`, `iTotalDisplayRecords` and `aaData[]` out, one row per message or per bulk send (`bulk_id`, `status.counts`) with `message_id`, `conversation_id`, `channel_type`, `sender_id`, `destination_e164`, `message_text`, `scheduled_for`, `sent_by` and the `actions` the portal may offer. A bulk row expands with [`GET /v2/conversations/messages/{messageId}?is-bulk=1`](/v2/ref#/operations/v2.getMessageInfo) and [`POST /v2/conversations/messages/{message}/statuses?is-bulk=1`](/v2/ref#/operations/v2.getMessageStatuses).\n- **Inbox**: [`GET /v2/sms/inbox`](/v2/ref#/operations/smsGwInbox.index) lists inbound SMS and WhatsApp messages, newest first (`iDisplayStart`, `iDisplayLength`, `filter`), as `_embedded[]` with `date`, `sender`, `number`, `number_name_sender`, `number_name_dst`, `message`, `channel_type`, `message_type`, `content_url`, `content_filename`, `media_error`, plus `total_items`.\n- **Thread by numbers**: [`GET /v2/sms/timeline?src_number=&dst_number=`](/v2/ref#/operations/smsGwInbox.timeline) returns every SMS and WhatsApp message exchanged between two numbers, same row shape.\n- **Combined feed**: [`GET /v2/sms`](/v2/ref#/operations/smsMsg.index) is a paginated union of inbound and outbound SMS (`page`, `pageSize`, `filter`), kept for older clients.\n\n## Roles and access\n\n- Any authenticated user can send and read; buying credit, requesting a sender name and managing 10DLC campaigns need an **account admin**.\n- The MMS option, enabled per account by NUACOM, allows `media_ids`; without it the field is ignored on the overview and answers 6101 on a direct send.\n- The ISO dates option switches `scheduled_for` and the history dates to ISO 8601 in the requested `X-Timezone`.\n\n## Pitfalls\n\n- Numbers may be sent as `+353\u2026`, `00353\u2026` or local Irish format; the answer echoes `international_number`. The inbox and timeline hold international digits without `+`.\n- `send_at` and `time_to` are read in the user's timezone, not UTC; a value within two minutes is sent immediately.\n- The compose flow is two calls: `overview` only stages. A staged draft that is never sent stays as a hidden conversation.\n- `POST /v2/sms/history` is a POST although it only reads; the `GET` of the same path is a deprecated legacy report and is not part of the reference.\n- `opt_in` / `opt_out` append their text to the message and count toward its segments; opted-out numbers are dropped silently from the counts, not reported as errors." }, { "name": "Conversations / SMS / Packages" }, { "name": "Conversations / SMS / Sender Names" }, { "name": "Conversations / SMS / Templates" }, { "name": "Conversations / MMS" }, { "name": "Conversations / WhatsApp", "description": "WhatsApp is the second channel of [Conversations](/v2/docs/groups/conversations) (`channel_type` 2). It is sent through the same thread endpoints as SMS, with three WhatsApp rules on top: the sender is a phone number connected to a Meta business account, a conversation that has had no inbound message for 24 hours accepts **approved templates only**, and media is moderated before it leaves. This group holds the template and media endpoints; the sender itself is connected in the portal.\n\n## Before your first message\n\n1. **Add-on and sender**: the account needs the WhatsApp for Business add-on and at least one connected number. Both are set up in the portal under **Integrations \u2192 WhatsApp for Business**: payment, a Twilio sub-account and Meta's Embedded Signup run in the browser, so those endpoints are not part of the public reference. Accounts that bring their own Twilio carrier (BYOC) cannot use WhatsApp.\n2. **Find your senders**: [`GET /v2/sms/sender_names?filter[channel]=whatsapp`](/v2/ref#/operations/smsSenderNames.getSenderNames) lists the connected numbers; `sender_name` is the value to send as `sender_id`. Up to 10 numbers per account.\n3. **Token**: the template and media endpoints need an **account admin** token. Without an active sender every endpoint of this group answers `403` \"No active WhatsApp sender found for your account\".\n\n## Templates (what the portal does)\n\n1. **List**: [`GET /v2/integrations/whatsapp/templates`](/v2/ref#/operations/integrations.whatsapp.templates.index) (`status`, `category`, `language`, `search`, `page`, `per_page` up to 100) or the shared [`GET /v2/sms-templates?filter[channel]=2`](/v2/ref#/operations/sms-templates.index), which is what the portal's template picker uses (`filter[status]=1` for sendable ones, `filter[exclude_dynamic_variables]=true` for automations that cannot fill placeholders).\n2. **Create**: [`POST /v2/integrations/whatsapp/templates`](/v2/ref#/operations/integrations.whatsapp.templates.store) with `name`, `category` (1 Authentication, 2 Marketing, 3 Utility: Meta prices and reviews them differently), `language`, `sender_id`, `body` (`text` with `{{1}}`\u2026`{{N}}` and one sample per placeholder in `variables`), optional `header` (`type` text, image, video or document; media as a `media_id` from the upload endpoint, a public `media_url` or an inline `media` file), `footer` and up to 10 `buttons`. The template is created locally with status 6 (Not Submitted); `submit_after_approval: true` submits it as soon as its header media passes moderation.\n3. **Edit or delete**: [`PUT`](/v2/ref#/operations/integrations.whatsapp.templates.update) is allowed while `permissions.can_edit` is true (Not Submitted, Rejected, Disabled or Media Rejected); an approved template is immutable, create a new one. [`DELETE`](/v2/ref#/operations/integrations.whatsapp.templates.destroy) works in every status and also removes the template from Twilio.\n4. **Submit**: [`POST /v2/integrations/whatsapp/templates/{smsTemplate}/submit`](/v2/ref#/operations/integrations.whatsapp.templates.submit) sends it to Meta. `200` with `status: \"submitted\"` and the `template_sid`; `202` with `status: \"pending_submit\"` when the header media is still being moderated (it is submitted automatically afterwards); `403` when the template is already approved or pending; `422` when a placeholder has no sample.\n5. **Wait for approval**: Meta decides asynchronously, usually within minutes, sometimes a day. Poll [`GET \u2026/templates/{smsTemplate}`](/v2/ref#/operations/integrations.whatsapp.templates.show): `status` is an integer and `status_label` its text: 0 Pending (submitted, awaiting Meta's review), 1 Approved, 2 Error (the submission failed; `status_label` reads \"Unknown\"), 3 Rejected, 4 Disabled, 5 Paused, 6 Not Submitted, 7 Pending Moderation (header media still being checked), 8 Pending Submit (queued for submission), 9 Media Rejected, 10 Deleted from Twilio (removed on the provider side; create a new one). Only **1** can be sent. An approved template can later become Paused or Disabled by Meta for quality reasons.\n\n## Template lifecycle\n\n```mermaid\nstateDiagram-v2\n [*] --> NotSubmitted: created locally (status 6 Not Submitted)\n NotSubmitted --> PendingModeration: submit_after_approval, header media uploaded (status 7)\n PendingModeration --> PendingSubmit: media approved (status 8)\n PendingModeration --> MediaRejected: media rejected (status 9)\n PendingSubmit --> Pending: auto-submitted to Meta (status 0)\n NotSubmitted --> Pending: POST \u2026/submit, 200 submitted (status 0)\n NotSubmitted --> PendingSubmit: POST \u2026/submit, 202 pending_submit (status 8)\n Pending --> Approved: Meta approves (status 1)\n Pending --> Rejected: Meta rejects (status 3)\n Pending --> Error: submission failed (status 2)\n Approved --> Paused: Meta pauses for quality (status 5)\n Approved --> Disabled: Meta disables (status 4)\n Rejected --> [*]: DELETE, create a new one\n MediaRejected --> [*]: DELETE, create a new one\n Approved --> [*]: Deleted from Twilio (status 10)\n```\n\n## Media\n\n- **Upload**: [`POST /v2/integrations/whatsapp/media`](/v2/ref#/operations/integrations.whatsapp.media.upload) (multipart `file`; JPEG, PNG, MP4, AAC, MP3, AMR, 3GP, PDF, DOC, DOCX, PPTX, XLSX, VCF; 16 MB, images 5 MB) answers `media_id`, a signed preview `url`, `type`, `message_type` and `moderation_status`. Images and videos are moderated asynchronously (`pending` \u2192 `approved` or `rejected`); audio and documents are approved on upload. Rejected media cannot be sent or used in a template header. Template headers accept JPEG, PNG, MP4 and PDF only; an inline `header.media` file is checked on its real MIME type, not its extension, and the same 16 MB / 5 MB limits apply.\n- **Read**: an inbound or outbound file is the message's single `attachments[]` entry (`id`, `content_url`, `thumbnail_url`, `media_type`, `mime_type`, `file_size`, `filename`), and `content_url` and `thumbnail_url` are repeated on the message itself. `content_url` is a signed URL that expires. [`GET /v2/whatsapp/media/{media}/download-url`](/v2/ref#/operations/whatsapp.media.download-url) with the attachment's `id` issues a fresh one: `200` with `url` (valid for 15 minutes, usable directly in ``, `