EmpireUC is Empire Telecom's own cloud phone system (UCaaS). It is built on the NetSapiens platform, so everything you can do in EmpireUC can also be done in code through the NetSapiens API v2: a JSON REST API with bearer-token authentication that covers users, phones, phone numbers, call routing, schedules, auto attendants, call queues, voicemail, call history (CDRs), recordings, transcriptions, SMS, live call control and event subscriptions (webhooks). In short: it is a complete, mature API, and almost every screen in the phone system has an endpoint behind it.

Tip: You do not need code for day-to-day changes. Customers can manage EmpireUC without any programming in the Phones section of the Empire Telecom customer portal (users, numbers, ring groups, call history and more). Use the API when you want to connect EmpireUC to your own systems, such as an EHR, CRM, wallboard or reporting tool.

At a glance

Getting access

Important: The client ID and the client secret are two separate values that go in two separate fields. Pasting both into the client ID field produces the error Invalid_client.

Authentication

Access token (username and password)

Request a token from POST /tokens. The body is JSON, not form-encoded. The /tokens call is the only one that does not need a bearer token.

The response includes access_token, refresh_token, expires_in (seconds), token_type, scope, user, domain, uid, displayName, user_email, client_id and apiversion. Send the token on every other request:

Refresh the token (preferred)

When the access token expires, use the refresh token instead of sending the password again:

Multi-factor authentication

If the user has MFA turned on, the first request returns a token with the mfa_required scope. Repeat POST /tokens with "grant_type": "mfa", the same client and login values, the mfa_vendor and mfa_type from the first response, the 6-digit passcode from the authenticator app, and the access_token you received with the mfa_required scope.

JWT tokens

NetSapiens also issues JSON Web Tokens, which suit end-user web applications:

API keys (machine to machine)

API keys are 60 characters long and are sent as a bearer token (Authorization: Bearer <key>). The first four characters show the scope: nsu_ Basic User, nsd_ Office Manager (domain), nsr_ Reseller, nss_ Super User. The first 12 characters are the Key ID, used to manage or revoke the key. A key is shown only once when it is created and cannot be retrieved later. Keys do not expire on their own, can be read-only, can be limited to IP addresses, limited to a domain, and limited to specific data models (allowed-models).

Endpoints and resources

All paths below are relative to https://<your-EmpireUC-API-server>/ns-api/v2. {domain} is your numeric domain ID (or ~ for the domain of the signed-in user). {user} is the extension (or ~ for yourself). Collection reads accept start and limit for paging.

Account, domain and version

Users (extensions)

Common user fields: user, name-first-name, name-last-name, email-address, user-scope, account-status, user-presence-status, status-message, department, site, time-zone, caller-id-number, dial-policy. Example create body:

Important: A new user is a new EmpireUC seat and is billable. Ask Empire Telecom before creating users in bulk.

Departments, sites and presence

There is no separate "department" object. department is a field on each user, and Sites group users by location.

Presence (available, on a call, do not disturb and so on) is returned on each user as user-presence-status, which the platform calculates from registration, answer rules and active calls.

Phones and devices

There is no separate "registrations" collection; use the user's devices and presence instead.

Phone numbers

Routing is set with dial-rule-application (for example to-user, to-callqueue, to-voicemail, to-connection, to-single-device, available-number, hangup) and dial-rule-translation-destination-user (the extension, queue or number it goes to). Example:

Tip: Point main numbers at an auto attendant, ring group or queue rather than at one person, so calls are not lost when that person is away. New numbers and porting are ordered through Empire Telecom.

Call routing: answer rules, schedules and ring groups

Each user has answer rules, one per timeframe (schedule). An answer rule decides what happens during that timeframe: simultaneous ring, forward always, forward on busy, forward when not answered, forward when unregistered, do not disturb, call screening, and lists of numbers to allow or reject.

Timeframes come in five types: always, days-of-week, specific-dates, holiday and custom. Shared (domain) timeframes and per-user timeframes have matching endpoints:

Ring groups are not a separate object. A ring group is built from a user (often a system extension) whose answer rules ring several destinations at once or in order, with timeframes for business hours and after hours. Use /answerrules/reorder to set which rule wins.

Auto attendants (welcome menus)

On the EmpireUC release there is no DELETE for auto attendants through the API; ask Empire Telecom to remove one.

Call queues and agents (contact center)

Queue dispatch types include Round-robin, Tiered Round-robin, Ring All, Linear Cascade, Linear Hunt and Call Park.

Call history (CDRs)

Useful filters: datetime-start, datetime-end, type (Inbound, Outbound, On-net, Off-net, Missed, Received), dialled, caller, site, group (department), plus start and limit (default 100, maximum 1000). Key fields: id, call-direction, call-start-datetime, call-answer-datetime (present only when the call was answered), call-disconnect-datetime, call-orig-from-user, call-orig-caller-id, call-orig-from-name, call-orig-to-user, call-term-user, call-talking-duration-seconds, call-total-duration-seconds, call-disconnect-reason-text, call-orig-call-id and call-intelligence-job-id.

Recordings and transcriptions

Recordings are looked up by call ID (from the CDR, call-orig-call-id), not listed as a collection.

The recording response includes call-recording-status, file-duration-seconds, file-size-kilobytes and file-access-url, a link you use to download the audio. Call recording must be turned on for the user or number; ask Empire Telecom (recording is included free with EmpireUC).

Voicemail and greetings

Messaging (SMS, MMS and chat)

Important: Business texting in the US requires 10DLC registration of the sending numbers. Ask Empire Telecom to register and enable SMS before you send through the API.

Live calls and call control

These act on the user's desk phone or app. You do not need a browser softphone to control calls.

Contacts

Emergency (911) addresses

Required fields for an address: address-name, caller-name, address-line-1, address-city, address-state-province-abbreviation, address-postal-code, address-country-abbreviation and address-location-description (for example "2nd floor nurses' station").

Dial plans, conferences and other areas

The full reference also covers meetings and video, phone templates, images, configurations, backups and certificate management. Most of these are platform-administration features that Empire Telecom manages for you.

Features that depend on the platform release

The NetSapiens reference for newer releases (45 and later) documents some endpoints that may not be on the EmpireUC release yet. Check with Empire Telecom before relying on them:

Call blocking

Example body: {"phone-numbers-to-reject": {"parameters": ["2015550199"]}}. You can also block callers for a user with the phone-numbers-to-reject list on that user's answer rule.

Webhooks and events

EmpireUC pushes events to your system through event subscriptions. You register an HTTPS URL, and the platform POSTs JSON arrays of changed objects to it.

Example:

Models you can subscribe to: call (every change to active calls: ringing, answered, ended), call_origid, cdr (one event when a call completes), agent (queue agent availability), presence, subscriber (user record changes), voicemail (a new voicemail; the transcription may arrive later), message and messagesession (SMS and chat), auditlog_lite (create and delete of key objects). Create one subscription per model.

Good to know:

• Delivery is near-real-time, not instant: the platform checks for changes about every 3 seconds. A screen pop typically appears by the second ring.
• Each POST carries an X-Correlation-ID header holding the subscription ID; use it to check that the post is genuine and to route posts when several subscriptions share one URL.
• post-url should be HTTPS with a valid certificate. Custom ports are allowed.
• A subscription created with a timed token expires with that token unless you set subscription-expires-datetime; one created with an API key lasts much longer. Re-create subscriptions when they expire.
• The response shows status (pending, active or error), posts-count and error-count, which help you troubleshoot.

Errors, limits and good practice

• Paging: collection reads accept start (offset, starting at 0) and limit. CDR reads return at most 1,000 records per page. Keep requesting until fewer than limit records come back. Count endpoints (/count) tell you the total first.
• Dates: CDR and statistics filters accept YYYY-MM-DD HH:MM:SS or RFC 3339 with an offset. State the time zone explicitly.
• Rate limits: NetSapiens does not publish fixed limits. Avoid polling faster than a few seconds, use event subscriptions for live data, and use exponential back-off on errors or 5xx responses.
• Logging tag: add the header X-NetSapiens-Log: <your-tag> to a request when Empire Telecom support is helping you trace a problem; it lets the request be found in the platform logs.
• Security: keep the client secret, refresh tokens and API keys in a secrets vault, never in source code or browser JavaScript. Restrict keys to your server IP addresses where possible, share credentials with as few people as possible, test against a non-production user first, and log your own API activity so you can audit changes.
• Least privilege: use a Basic User login for single-user tools (click-to-call, personal call history) and Office Manager only when the integration truly needs the whole organisation.

Common tasks

Pull yesterday's call log

Download a call recording

Get notified when a call ends

Click-to-call from your CRM

Change where the main number rings after hours

Add a new staff member

Build a simple wallboard

More information

• NetSapiens API developer hub - home of the official API documentation, guides and community.
• API reference, version 44.4 - every endpoint with parameters and examples; choose the 44.4 version to match EmpireUC.
• Authentication overview - access tokens, JWT tokens and API keys compared.
• API keys - key format, scopes, read-only keys and revoking keys.
• Limited access API keys - restricting keys by IP, domain, scope and data model.
• Event subscriptions - models, delivery and the X-Correlation-ID header.
• Pagination and API data - using start and limit.
• CDR field mappings - what each call-record field means.
• Attended transfer guide - hold, consult and transfer step by step.
• Headers and on-demand logging - required headers and the X-NetSapiens-Log tag.
• Changelog - documentation and API changes.
• Community discussions - questions and answers from other developers.
• Empire Telecom support - for API access, credentials, your server address, scope changes, SMS registration and service status. Ask Empire Telecom; do not contact the platform vendor directly.