net2phone is a cloud business phone system (UCaaS) with a public developer portal at developer.net2phone.com. It offers two REST APIs: the older API V1 (OAuth, mainly users, call detail records, click-to-call and basic call webhooks) and the newer API V2 (API key or OpenID Connect, covering call detail records, recordings, voicemail, call queues, presence, phone numbers, messaging, webhooks and AI virtual agents). Verdict: a solid, modern API for reporting, wallboards, CRM call logging and event-driven integrations. It is not a full provisioning API. Most PBX configuration is still done in the net2phone admin console.

Important: net2phone publishes its API reference as an interactive explorer that changes over time. This article lists what we verified in the published V1 and V2 OpenAPI specifications in October 2026. Always confirm field names and parameters in the API V2 explorer before you build.

At a glance

Getting access

Tip: Some V2 features, such as SMS and AI virtual agents, need the matching service on the account. If an endpoint returns 402 (feature unavailable), ask Empire Telecom to enable the feature.

Authentication

API V2: API key

Send the key in the X-API-Key header on every request.

The V2 specification lists two security schemes on every operation: n2pApiKeyAuth (API key) and n2pOpenIdConnect (OpenID Connect bearer token), both with the scope public_api.v2. Use the API key for server-to-server integrations. Use OpenID Connect only if net2phone has issued you OAuth credentials for a user-facing app.

API V1: OAuth 2.0 password grant

V1 uses the OAuth 2.0 resource-owner password grant. You send your developer client ID, the user's net2phone email and password, and the grant type to the token endpoint. The response contains an access token and a refresh token. Access tokens expire, so refresh them with the refresh token before they run out.

The form field names above follow the standard OAuth password grant; confirm them in the V1 explorer before use.

Then call the API with the bearer token:

Important: Build new integrations on V2 with an API key. V1 depends on a user's password, and V1 features differ by account platform generation (see below).

V1 account generations

V1 responses include a generation value on the account: gen_v, gen_p, gen_x or gen_u. Many V1 parameters only work on some generations. For example, GET /users/ returns every user on Gen V (net2phone Canada) accounts but only the current user on Gen P, U and X. The V2 specification marks its operations for the unite and unite3 account backends.

Endpoints and resources

All V2 paths below are relative to https://api.n2p.io/v2. Paths containing a colon (for example :search) are custom actions and are part of the path.

Users and account (V2)

Call detail records (V2)

The search is a POST with a JSON filter body (for example by date range, direction, answered or not, department, unread voicemail or recording). Admins see every call in the account; regular users see their own calls, calls to their departments and some voicemail fallbacks. Check the explorer for the current filter fields.

Call recordings (V2)

The download-link endpoint behaves differently depending on the Accept header: with Accept: application/json it returns 200 and a JSON object containing the link; with any other or no Accept it returns 302 with the temporary URL in the Location header. It returns 409 if the audio is not ready. Recording IDs come from call detail records and from the CallRecorded webhook.

Voicemail (V2)

Voicemails themselves are found through /call-detail-records:search and the VoicemailReceived webhook.

Call queues (V2)

These are the endpoints to use for wallboards. Statistics return 422 if the queue type does not support them.

Presence (V2)

Filters include presence status, extension and presence owner. Admins see every extension; regular users see only their own.

Phone numbers and porting (V2)

Tip: Ordering numbers adds billable services. For Empire Telecom customers, ask Empire Telecom to order or port numbers so billing stays correct.

Call blocking (V2)

Messaging and team chat (V2)

Business texting in the US requires 10DLC brand and campaign registration (The Campaign Registry). Ask Empire Telecom to arrange registration before you send SMS through the API. Incoming and outgoing texts are delivered as MessageReceived and MessageSent webhooks.

Meetings (V2)

AI virtual agents (V2)

net2phone's V2 API also manages its AI voice agents. Verified operations include:

Webhook management (V2)

API V1 (legacy)

All paths are relative to https://api.n2p.io/v1. Note the trailing slashes.

V1 CDR queries take start_date (required), end_date, user (repeatable), type (Incoming, Outgoing, On Net), cursor, and either limit (1-100, default 20; Gen P, X, U) or page_size (1-100, default 10; Gen V). Gen V also supports recording_available, min_duration, max_duration and phone_number. Results come back as { "more": true|false, "cursor": "...", "result": [ ... ] }. On Gen V each CDR's from and to can include a recordings array with recording_id, url (download link) and status.name (Processing, Available, No Recording, Deleted, Archived, Ignored).

Webhooks and events

V2 webhook subscriptions (recommended)

Create a subscription with POST /webhook-subscriptions, giving the endpoint_url that should receive events and the event types you want. Call GET /webhook-event-types first: it returns the event types your account can use (each with an id such as call_ringing, a display_name and a platform). The V2 specification lists these 29 callback events:

Each subscription has a secret, which you can regenerate with PUT /webhook-subscriptions/{id}/secret. Use it to confirm that events really come from net2phone; the exact signing method is described in the Webhooks section of the developer portal.

V1 subscriptions (legacy)

POST /subscriptions/ takes post_uri (your HTTPS URL), the booleans calls, cdrs and recordings to choose event families, an optional user (default * for all users) and expires_in in seconds (default 7200, maximum 604800, which is 7 days). Re-create subscriptions before they expire. V1 call events are CallRinging, CallAnswered, CallWithAutoAttendant and CallCompleted. Each carries from and to objects (number or extension, call_id, state of progressing, ringing, active or ended), time_start, time_answer, duration in seconds, on_net and by_call_id for transfers.

Important: net2phone's V1 specification states that webhook responses are discarded and V1 webhook requests are never retried. If your endpoint is down, those events are lost. Reconcile with a CDR query afterwards.

Good practice for receivers

• Use HTTPS only and restrict your endpoint to trusted sources.
• Reply quickly with a 2xx and do the heavy work in the background.
• Expect duplicates and out-of-order events; key on call IDs.
• Run a periodic CDR search to catch anything a webhook missed.

Errors, limits and good practice

• Rate limits (V2). Each operation carries a throttling quota. Read RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset on every response, slow down as Remaining approaches zero, and after a 429 wait until the reset time before retrying.
• Rate limits (V1). Published per endpoint (see the V1 table). The 429 body contains a message such as "1 per 1 second".
• Pagination. V2 list endpoints are cursor-based, using limit with before and after cursors. V1 CDRs use cursor and the more flag.
• Error bodies. V1 errors return { "status": <code>, "message": "..." }. Log the full body.
• Retries. Retry 429 and 5xx with exponential backoff. Do not retry 400, 401, 403 or 422 without fixing the request.
• Scope of data. Use an Admin user's key for account-wide reporting; a regular user's key only sees that user's data.

Common tasks

Pull yesterday's call log

Download a call recording

Get notified when a call ends

Build a call-queue wallboard

Place a click-to-call from your app

Check who is on the phone right now

Block a nuisance caller

More information

• net2phone Developer Portal - home of the API documentation, credential request form and integrations.
• API V2 explorer - the current API reference, with getting-started and authentication articles.
• API V2 authentication: API keys - how to authenticate with an API key.
• API V1 explorer - the legacy API reference.
• Webhooks documentation - V2 and V1 webhook events and payloads.
• V2 OpenAPI specification - machine-readable V2 definition for code generators and API tools.
• V1 OpenAPI specification - machine-readable V1 definition.
• Dialer SDK - embed a net2phone dialer in any web page.
• Integrations - ready-made connectors (Salesforce, Microsoft Teams, Slack, Zapier and more).
• net2phone Integrate - no-code workflow automation for net2phone.
• net2phone API Settings (help article) - creating, rotating and revoking API keys in the admin console.
• Need admin access, SMS registration, numbers or a feature enabled? Ask Empire Telecom through the customer portal or by calling support.