Getting started

The NoodleVoice API lets your software work with a NoodleVoice client's phone system: users, phone numbers, call routing, call queues, call history, recordings, voicemail, text messages and real-time events. This page covers what you need before your first request.

1. Get an API key

Keys are issued by NoodleVoice. Ask your NoodleVoice contact (or the client you're building for can ask on your behalf). NoodleVoice creates the key in its Key Admin at keys.noodlevoice.com and sends it to you securely. Each key:

• starts with nvg_,
• belongs to exactly one client account,
• has an access level (Read only, Full access, or Custom per feature),
• can have an expiry date and an IP allow list.

The key is shown once when it's created. Store it like a password: in a secrets manager or environment variable, never in browser code or a public repository. If a key leaks, ask NoodleVoice to revoke it and issue a new one.

2. Base URL

Every request goes to:

https://api.noodlevoice.com/ns-api/v2

Paths in this reference are relative to that base. For example, GET /domains/~/users means GET https://api.noodlevoice.com/ns-api/v2/domains/~/users. Always use HTTPS.

3. Authentication

Send your key in the Authorization header on every request:

Authorization: Bearer nvg_your_key_here

No other special headers are needed. Send JSON bodies with Content-Type: application/json.

4. Your account and the ~ shortcut

Almost every path starts with /domains/{domain}, where {domain} is the client's account ID (it looks like yourfirm.noodlevoice). You don't need to know it: use ~ and the API fills in the account your key belongs to.

GET /domains/~/users          (same as /domains/yourfirm.noodlevoice/users)

A key only works on its own account. Asking for any other account returns 403. To find the full account ID (some fields, like queue agent IDs, include it), call GET /domains/~ and read the domain field.

5. Your first request

This lists the users on the account:

curl https://api.noodlevoice.com/ns-api/v2/domains/~/users \
  -H "Authorization: Bearer $NOODLEVOICE_KEY"

const res = await fetch("https://api.noodlevoice.com/ns-api/v2/domains/~/users", {
  headers: { Authorization: "Bearer " + process.env.NOODLEVOICE_KEY },
});
const users = await res.json();

import os, requests

r = requests.get(
    "https://api.noodlevoice.com/ns-api/v2/domains/~/users",
    headers={"Authorization": "Bearer " + os.environ["NOODLEVOICE_KEY"]},
)
users = r.json()

A good connection test is GET /domains/~/count. It returns {"total": 1} when your key works.

6. What your key can reach

Every key has one of three access levels, set by NoodleVoice in the Key Admin:

This reference is organized by the same features as the Key Admin switches, and every endpoint shows which switch it needs. If you get a 403 saying the scope doesn't allow a request, ask for that feature to be added to your key. A few endpoints aren't covered by any feature switch; they're marked Full access and need a Full access key.

Key management, sign-in tokens and anything above the client's own account are never available through the API.

7. Errors

Errors come back as JSON with a status code and a message:

{ "code": 403, "message": "Token is limited to domain yourfirm.noodlevoice" }

8. Conventions

• Field names use lowercase words joined by hyphens, like name-first-name or caller-id-number.
• Yes and no settings are usually the strings "yes" and "no", not true and false.
• Dates and times look like 2026-10-29 14:30:00 and use the account's time zone unless a field says otherwise.
• Phone numbers are digits only in E.164 form, like 15555550123.
• Paging: list endpoints that can return a lot take limit and start. Ask for a page, then move start forward by limit until you get fewer results than you asked for.
• Extra fields: responses can include fields that aren't listed in this reference, and new ones may be added. Ignore fields you don't use rather than failing on them.
• Counting: endpoints ending in /count return {"total": n} without the records.
• Writes often answer 202 Accepted. Add "synchronous": "yes" to the body, where it's offered, to wait until the change is done.
• Real-time events: instead of polling, create an event subscription and we'll post events to your server.

Need help?

Contact your NoodleVoice account manager. Include the time of the request, the method and path, the status code, and the x-nv-gateway-token response header if there is one (it identifies your key without revealing it). Never send the key itself.