MOR API dids get

List DIDs via the MOR API.

Description

MOR API DIDs get — list DIDs matching search filters. Returns XML (or HTML when test=1).

Usage

• Call (recommended): POST to /billing/api/ with action=dids_get (same as other MOR API methods).
• Alternate URL: /billing/api/dids_get — may work depending on server routing; prefer the main API endpoint above.
• Methods: POST (recommended), GET (if allowed in MOR Settings — not recommended).

Parametres

Required on every call

• hash — SHA1 hash constructed using API_Secret_Key ( more in Constructing hash). Required.
• u — username for authentication. Required.

Search and pagination (not included in the hash)

The following parameters are not concatenated into the hash string. For a typical request with only u and search filters, the hash is built from the API Secret Key alone (no search parameter values are added). See Constructing hash for hash-listed parameters on other actions.

• search_did_number — DID number (partial match)
• search_status — lifecycle filter: free, reserved, active, closed, terminated (lowercase in the request; see did_status in the response)
• search_did_owner — owner display name (admin / accountant)
• search_dialplan — dialplan id
• search_user — user id
• search_device — device id
• search_provider — provider id (admin / accountant, or reseller with own providers)
• search_language — language configured on the DID; use all to disable this filter (default when omitted)
• search_hide_terminated_dids — 1 hide terminated DIDs, 0 show
• from — 1-based index of the first record to return (pagination)
• max_results — maximum number of records to return

Optional test flag

• test — 1 renders the response in the browser for debugging (same as other API methods)

Authorization and visibility

• The caller is identified by u= only; the hash does not bind a different user identity.
• Accountant users need Manage DIDs read permission on their accountant group; otherwise the API returns You are not authorized to manage DIDs.
• When API restricted is enabled on the user (user edit form) and an API permission group is assigned, dids_get must be allowed in that group; otherwise the response is API method not permitted: dids_get.
• Admin and accountant (with Manage DIDs) see system-wide DIDs; reseller sees reseller-scoped rows; user sees only their own DIDs.
• Fields such as provider, dial_plan, and tone_zone may be omitted for user and/or reseller responses — do not assume every element in the admin example below is present for all roles.

Request

Example: search_status=free, API Secret Key = secret, hash computed per Constructing hash (search parameters are not part of the hash).

We send (recommended):

POST http://<SERVER_IP>/billing/api/?u=admin&action=dids_get&search_status=free&hash=6e79d4a82f68102f43be11d873177f47817f84df

With the same parameters, the matching free DIDs appear in the GUI DIDs list.

Returns

Success

<?xml version="1.0" encoding="UTF-8"?>
<page>
  <dids>
    <did>
      <did>37066xxxxxx</did>
      <did_number>37066xxxxxx</did_number>
      <provider>Test Provider</provider>
      <language>language</language>
      <status>Active</status>
      <did_status>active</did_status>
      <ai_agent_compatible>true</ai_agent_compatible>
      <routes_to_openai_project_id></routes_to_openai_project_id>
      <updated_at>2026-05-27T07:35:57Z</updated_at>
      <reseller>Test Reseller</reseller>
      <owner>User Resellers</owner>
      <device>IAX2/105</device>
      <dial_plan></dial_plan>
      <simultaneous_call_limit>Unlimited</simultaneous_call_limit>
      <tone_zone>it</tone_zone>
      <id>6501</id>
      <did_status>closed</did_status>
      <device_id>2</device_id>
      <user_id>2</user_id>
      <reserved_for_user_till>2026-06-09T12:00:00Z</reserved_for_user_till>
    </did>
    <did>
      <did>37066xxxxxx</did>
      <did_number>37066xxxxxx</did_number>
      <provider>Test Provider</provider>
      <language></language>
      <status>Active</status>
      <did_status>active</did_status>
      <reseller>Test Reseller</reseller>
      <device></device>
      <dial_plan>testDialPlan (authbypin)</dial_plan>
      <simultaneous_call_limit>Unlimited</simultaneous_call_limit>
      <tone_zone></tone_zone>
      <id>6502</id>
      <did_status>closed</did_status>
      <device_id>2</device_id>
      <user_id>2</user_id>
      <reserved_for_user_till>2026-06-09T12:00:00Z</reserved_for_user_till>
    </did>
  </dids>
</page>

Integration elements (inside each <did>)

• did_number — same value as did (returned for compatibility)
• did_status — lowercase lifecycle from the database (e.g. free, active, reserved) — use for machine parsing
• status — capitalized label for the GUI (e.g. Active) — same row, human-oriented display
• ai_agent_compatible — true or false when the column exists; omitted when the column is not on the server
• routes_to_openai_project_id — VoiceAI routing target (may be empty)
• updated_at — last change in RFC3339 UTC with Z suffix (e.g. 2026-05-27T07:35:57Z); omitted when not set. Fixed wire format for integrators — not the phpMyAdmin YYYY-MM-DD HH:MM:SS display string. See Useful to know (API values are not reformatted by GUI date settings).
• device_id — numeric ID of the device the DID is assigned to; omitted when there is no device assignment (same rule as MOR API v2 DIDs JSON).
• user_id — numeric ID of the end user the DID is assigned to; omitted when there is no user assignment.
• reserved_for_user_till — when did_status is closed, the date and time until the DID stays reserved for the user (RFC3339 UTC with Z suffix, for example 2026-06-09T12:00:00Z); omitted for free, active, reserved, and terminated rows. Matches the Reserved for user till line on the DID edit screen in the GUI.

Other elements (comment, reseller, etc.) follow the same rules as the DIDs GUI for the authenticated role.

Errors

• Incorrect hash — Hash was not correct. Check API_Secret_Key and parameter order while concatenating the hash string.
• Access Denied — User for u= not found, or invalid authentication.
• You are not authorized to manage DIDs — Accountant without Manage DIDs read on the accountant group.
• API method not permitted: dids_get — User has API restricted and the assigned permission group does not allow dids_get.
• No DIDs found — No DIDs matched the filters.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<page>
  <error>Error message</error>
</page>

See also

• MOR API
• MOR API v2 DIDs — JSON DID listing: GET /billing/api/v2/dids