NUACOM API

Account & access

Account

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 is the one endpoint of this group and the first call to make with a new API key (see 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).

Account info and its sub-configs

flowchart TD
    info["GET /v2/account_info"] --> security["Account / Settings<br/>GET /v2/account-security-settings"]
    info --> language["Account / Language Config<br/>GET/POST /v2/account-language-config"]
    info --> ai["Account / AI Config<br/>GET/POST /v2/account-ai-config"]

Workflow (what the portal does)

  1. Account info: GET /v2/account_info, any user. The fields are described below.
  2. Password policy: GET /v2/account-password-requirements, 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, and the same object comes back as requirements when a login fails with code 4001 (see Authentication).
  3. Security settings (account admin): GET /v2/account-security-settings 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.
  4. Transcription languages: GET /v2/language-options, any user, lists the 58 supported languages as {"data": [{"code": "en", "label": "English"}, …]} with two-letter codes. GET /v2/account-language-config returns the account's defaults and overrides and POST /v2/account-language-config replaces them (account admin, where the feature is enabled). Details below.
  5. AI call recap (account admin): GET /v2/account-ai-config and POST /v2/account-ai-config, described below.

Reading the account info

Field Meaning
account_id The account id (IE-00123), the same value POST /v2/auth/login returns
company_name, company_email, billing_email As set in the portal; null when unset
address address_1, address_2, city, county, country_iso_code, post_code, coordinates; every key is present, "" when unset
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
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
created_at When the account was set up; see Dates and timezones for the two formats
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
billing.billing_currency The currency code (EUR)
billing.billing_type bill_pay, pre_pay or mixed
billing.sms_billing_type bill_pay or pre_pay: how SMS is charged
billing.account_balance The balance in billing_currency, two decimals
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

Security settings

Setting Default Effect
allow_local_login true false rejects every email-and-password login with code 4002; users sign in with SSO only
allow_sso_logins true false rejects Google and Microsoft sign-ins
oauth both providers enabled, config [] One entry per provider: provider, provider_name (GOOGLE, MICROSOFT), is_enabled, config
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
ip_whitelist [] Entries as id and ip_address
require_2fa false Every user must confirm a new device with the emailed code, whatever their own two-factor setting
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
reset_period_months 6 1 to 12
password_min_length 8 8 to 32
password_must_mixed_case true At least one upper-case and one lower-case letter
password_must_include_numbers true At least one digit
password_must_include_symbols true At least one symbol
password_is_uncompromised false Rejects passwords found in public data leaks

Until 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 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.

Transcription languages

The language config decides which language Speech To Text transcribes calls and voicemails in; the AI data in Call AI is built from that transcript. GET answers, and POST takes, the same four keys:

  • number_languages: the default for calls, a list of codes from GET /v2/language-options. Required on POST, with at least one code.
  • voicemail_languages: the default for voicemails. On POST, null or omitted leaves it as it is; a list ([] included) replaces it.
  • 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.
  • voicemail_overrides: one entry per voicemail box, {"voicemail_box": 10, "languages": ["en"]}, with the same replace-or-leave rule.

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): without it GET returns them empty, POST ignores what you send for them and clears what was stored, and voicemails are transcribed in English.

AI call recap

When 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:

  • is_recap_email_enabled: send true or false; it is returned as 1 or 0.
  • 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.
  • 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.

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.

Roles and access

  • GET /v2/account_info, GET /v2/account-password-requirements and GET /v2/language-options: any authenticated user.
  • Security settings and AI config: account admins only; anyone else gets 403 "Forbidden".
  • 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.
  • 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 — see Dates and timezones.

Pitfalls

  • The account info carries no add-ons: read the AI add-on from GET /v2/speech-to-text/active.
  • 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.
  • Only the first code of each language list is used; the rest is stored and returned but has no effect.
  • 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.
  • number_overrides and voicemail_overrides are replaced wholesale whenever you send them: an entry left out is deleted.
  • 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.
  • 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.