MOR API v2 DIDs

List DIDs via MOR API v2.

Documentation

Full MOR REST API documentation is available at /billing/api/v2/api-docs/.

Description

The DIDs API retrieves the list of DIDs visible to the authenticated admin or accountant user. Responses are JSON. The same data scope and VoiceAI integration fields as legacy dids_get apply. Authentication follows Usage on the parent page (JWT via Basic login).

Only admin and accountant users may call this endpoint. Reseller and simple user accounts receive HTTP 401.

API

Endpoint: GET /billing/api/v2/dids

Query parameters (all optional):

• search_did_number — filter by DID number (SQL LIKE partial match)
• search_status — lifecycle filter: free, reserved, active, closed, terminated (lowercase; see did_status in the response)
• search_hide_terminated_dids — 1 hide terminated DIDs, 0 show
• from — 1-based index of the first record to return (pagination; same as legacy dids_get)
• max_results — page size. When omitted, the server returns all matching rows (legacy parity). Integrators with large inventories should paginate (for example max_results=500).

Authentication

The DIDs API requires the same authentication as other MOR API v2 endpoints: Basic authentication to obtain a JWT, then a Bearer token on each request. See Usage on the parent page.

Basic authentication (login)
POST /billing/api/v2/authentication/login with HTTP Authorization header Basic base64(username:password). Use the user's GUI password (the same password as for the MOR web interface), not the global API Secret Key.

Example:

POST http://<SERVER_IP>/billing/api/v2/authentication/login HTTP/1.1
Authorization: Basic <base64(accountant:password)>

JWT authentication (list DIDs)
Pass the access_token from login in the Authorization header. The access token is valid for 15 minutes; use /billing/api/v2/authentication/refresh before expiry.

Example:

GET http://<SERVER_IP>/billing/api/v2/dids?search_status=free&from=1&max_results=500
Authorization: Bearer <access_token>

Authorization and visibility

• Accountant users need Manage DIDs read permission on their accountant permission group; otherwise the API returns HTTP 401 with {"errors":"Unauthorized"}.
• When API restricted is enabled on the user and an API permission group is assigned, the logical method dids_get must be allowed in that group (for example the VoiceAI DIDs Reader preset); otherwise the response is HTTP 401 with {"errors":"API method not permitted: dids_get"}.
• Admin and accountant (with Manage DIDs) see system-wide DIDs. Reseller and simple user are not permitted on this v2 endpoint.
• Fields such as provider and dial_plan are included for admin and accountant responses only.

Integration user setup

Typical read-only DID inventory integration (for example, VoiceAI sync):

1. SETTINGS → Setup → Accountant Permissions — grant Manage DIDs read on the integration accountant's group.
2. SETTINGS → Setup → API Permission Groups — create or use a group that allows dids_get read (preset: VoiceAI DIDs Reader).
3. SETTINGS → Users — create or edit an accountant user; enable API restricted and assign the API permission group.
4. Enable API globally (SETTINGS → Setup → Settings → API tab).
5. Authenticate with that accountant's username and GUI password via /billing/api/v2/authentication/login; call GET /billing/api/v2/dids with the returned Bearer token.

Returns

Success (HTTP 200)

{
  "dids": [
    {
      "id": 6501,
      "did": "37066105718",
      "did_number": "37066105718",
      "status": "Active",
      "did_status": "active",
      "ai_agent_compatible": true,
      "routes_to_openai_project_id": "proj_xxx",
      "updated_at": "2026-05-27T07:35:57Z",
      "owner": "User Resellers",
      "device": "IAX2/105",
      "provider": "Test Provider",
      "dial_plan": "testDialPlan (authbypin)"
    }
  ],
  "meta": {
    "from": 1,
    "max_results": 500,
    "returned": 42
  }
}

DID object fields

• id — DID record ID in the MOR database
• did / did_number — same DID number string (both returned for compatibility)
• status — capitalized GUI label (for example Active)
• did_status — lowercase lifecycle value from the database (for example free, active, reserved) — use for machine parsing
• ai_agent_compatible — true or false when the VoiceAI column exists on the server; omitted when the column is absent
• routes_to_openai_project_id — VoiceAI routing target (may be empty)
• updated_at — last change in RFC3339 UTC with Z suffix (for example 2026-05-27T07:35:57Z); omitted when not set. See Useful to know (API values are not reformatted by GUI date settings).
• owner — user display name
• device — assigned device label
• provider — provider name (admin/accountant only)
• dial_plan — dial plan name and type (admin/accountant only)

meta object

• from — 1-based offset used for this page
• max_results — page size requested (null when omitted in the request)
• returned — number of DID objects in this response

Empty result (HTTP 200)

{
  "dids": [],
  "meta": {
    "from": 1,
    "max_results": null,
    "returned": 0
  }
}

Errors

Errors are JSON and HTTP 401 unless noted. The DIDs endpoint uses an errors string; the login endpoint uses error.

Condition	HTTP	Example body
Invalid or missing JWT	401	{"errors":"Invalid token value"}
API disabled globally	401	{"errors":"API Requests are disabled"}
Wrong login password	401	{"error":"unauthorized"} (login endpoint)
User type not allowed (reseller, simple user)	401	{"errors":"Unauthorized"}
Accountant without Manage DIDs read	401	{"errors":"Unauthorized"}
API restricted — dids_get not permitted	401	{"errors":"API method not permitted: dids_get"}

Additional notes

• Legacy XML listing remains available via dids_get (API Secret Key + hash). Prefer this v2 endpoint for new integrations.
• More request/response examples are in /billing/api/v2/api-docs/ under the DIDs tag.

See also

• MOR API v2
• MOR API dids get — legacy XML DID listing