claudetools/.claude/skills/packetdial/references/api.md

NetSapiens SNAPsolution API v2 — Reference (PacketDial / OITVOIP)

Source of truth: the live OpenAPI spec at https://pbx.packetdial.com/ns-api/webroot/openapi/openapi.json (title "NetSapiens API v2", version 44.4.10 as of 2026-06-02).

Hosts

• API host: pbx.packetdial.com — https://pbx.packetdial.com/ns-api/v2
• Customer portal (no API): voip.packetdial.com — login-gated UI; the Cascades fax/UC dashboard lives here (account 28598). Hitting /ns-api/* on this host returns errors/not_found.

Authentication (bearerAuth)

All calls send Authorization: Bearer <token>. Two ways to get the token:

1. Static API key — created in pbx.packetdial.com Admin > API Keys. Prefix encodes scope: nsr_ = reseller, nss_ = system, nsd_ = domain. Use the key string directly as the bearer token (no exchange step).
2. OAuth2 password grant — POST /ns-api/v2/tokens form-encoded: grant_type=password&client_id=..&client_secret=..&username=..&password=.. Response includes access_token (JWT) + expires_in. The client caches it and refreshes ~60s before expiry.

Endpoint inventory (239 paths, grouped)

Top-level resource groups and the methods present:

Resource	Methods	Notes
/version	GET	platform version
/apikeys, /apikeys/{id}, /apikeys/~	GET POST PUT DELETE	~ = current key
/tokens, /jwt	POST (+ GET/DELETE on jwt)	auth / token mgmt
/resellers, /resellers/{reseller}	GET POST PUT DELETE
/domains, /domains/{domain}	GET POST PUT PATCH DELETE	/domains/count for totals
/domains/{domain}/users, /users/{user}	GET POST PUT DELETE	extensions
/domains/{domain}/users/{user}/devices	GET POST PUT DELETE	per-user SIP devices
/domains/{domain}/users/{user}/answerrules	GET POST	call routing
/domains/{domain}/users/{user}/cdrs	GET	per-user CDRs
/domains/{domain}/phones	GET POST PUT DELETE	domain device list
/domains/{domain}/phonenumbers, /{phonenumber}	GET POST PUT DELETE	DIDs
/domains/{domain}/addresses, /addresses/endpoints	GET POST PUT DELETE	emergency/E911 addrs
/domains/{domain}/cdrs, /cdrs	GET	call detail records (/count variants)
/phonenumbers	GET	global DID search
/smsnumbers	GET
/subscriptions	GET POST PUT DELETE	event/webhook subs
/connections, /routes, /routecon	GET POST PUT DELETE	SIP trunks / routing
/configurations, /config-definitions, /templates	GET POST PUT DELETE
/certificates, /images	GET POST PUT DELETE
/meetings, /video, /firebase	GET POST	UC / video
/sipflow	GET	SIP trace
/holidays, /cdrs	GET
/backup, /restore	POST / GET PUT	platform backup

Many resources also expose /count (totals) and #1/#2/#3 openapi-dedup variants (same path, different query-param shapes). Use the Swagger UI for the exact request/response schema of any specific path.

Common query params

• List endpoints accept limit, offset, and resource-specific filters.
• CDR endpoints accept start-date / end-date (and domain, user scoping via the nested path). Always bound CDR queries — they can be large.

Provisioning flow (new customer domain)

1. POST /domains — creates the domain; dial plan auto-generates.
2. POST /domains/{domain}/users — one per extension.
3. POST /domains/{domain}/users/{user}/devices or POST /domains/{domain}/phones — SIP devices (MAC provisioning).
4. POST /domains/{domain}/phonenumbers — attach DIDs, route to users.
5. Configure answerrules as needed.

History

• 2026-04-20: API researched (session log session-logs/2026-04-20-session.md, "OITVOIP / NetSapiens API Research"). Platform identified, auth shapes documented. No API key created yet — provisioning the key + storing it in msp-tools/oitvoip.sops.yaml was the open TODO.
• 2026-06-02: packetdial skill created wrapping the v2 API (read-by-default, gated writes). Confirmed voip. is portal-only and pbx. is the API host.
• 2026-06-22: Reseller API key provisioned + vaulted (msp-tools/oitvoip.sops.yaml, key-id nsr_hSGUB5Wo, scope Reseller 91912.service, read-write). Live-verified end to end. RTFM pass over the v2 spec (v44.4.10, 239 paths / 354 ops) — capability map added to SKILL.md. Added live-verified read wrappers: callqueues, timeframes, sites, contacts, autoattendants, billing. Reseller territory = 3 domains today (arizonacomputerguru + two *.91912.service). Added gated WRITE wrappers for call queues (create/update/delete-callqueue, add/update/remove-agent) and time frames (create/update/delete-timeframe), each live-verified create→update→delete on the arizonacomputerguru test domain (sanctioned test bed, not in production use). Timeframe writes are body-discriminated (same path; the server selects the op from the body) — wrappers pass --body verbatim. Note: entry-bearing timeframe types (days-of-week etc.) reject create without their array — create always then convert, or include the array. Finished the resource wrapping: added reads (addresses, smsnumbers, blocked-numbers, moh, dialrules, recording, transcriptions) and gated writes (DID update/delete, per-user device CRUD, E911 address CRUD, contact CRUD, site create/update, auto-attendant create, SMS number CRUD, block/unblock numbers, MoH TTS create/delete). Verified [V] lifecycles on arizonacomputerguru: contact create→delete (id = unique-id), plus the callqueue/timeframe lifecycles. The rest are plumbed per spec [P] but not lifecycle-verified (test domain lacks the feature, or needs a special body — E911 address-formatted-pidflo via addresses/validate; SMS not provisioned; number-filters add 202'd but didn't persist on the empty domain). Multipart MoH upload + dialrule writes + queue-agent PATCH stay on raw.