DIDs

Listing phone numbers (DIDs), the four state-change methods (terminate, close, make free, stop subscription), creating a DID, and assigning or unassigning one to a device.

dids_get

Lists DIDs, filtered by any combination of search parameters. What comes back is scoped to the caller automatically: admin/accountant see everything, a reseller or partner only their own numbers, a plain user only the numbers assigned to their own account.

Who may call it: any account type.

Parameter	Required	Meaning
`search_did_number`	No	Substring match on the number.
`search_did_owner`	No	Any non-empty value restricts to DIDs that aren't free.
`search_provider`	No	Admin/accountant, or a reseller with their own providers, only.
`search_dialplan`	No	Not usable by a plain `user`.
`search_language`	No	DID language code, or `all`.
`search_status`	No	`free`, `active`, `closed`, `terminated`, `reserved`.
`search_user`	No	Numeric user or reseller id that owns the DID.
`search_device`	No	Numeric device id, or `all`.
`search_hide_terminated_dids`	No	`1` excludes terminated numbers.
`from` / `max_results`	No	Paging: 1-based start row / page size.

Note

Hash parameter order: this method has no dedicated order, and none of the search_*/from/max_results parameters above appear in the shared fallback list either (it uses the older s_* names for other methods, not search_*). In practice, a normal dids_get call hashes to SHA1(secret key) alone.

curl -X POST https://api.example.com/api/dids_get \
  -d "u=admin" \
  -d "search_status=active" \
  -d "hash=PLACEHOLDER_HASH"

<page>
  <dids>
    <did>
      <did>41440000099</did>
      <provider>Demo Carrier</provider>
      <language></language>
      <status>Active</status>
      <owner>Demo Company</owner>
      <device>SIP/1010</device>
      <dial_plan></dial_plan>
      <simultaneous_call_limit>Unlimited</simultaneous_call_limit>
      <tone_zone></tone_zone>
      <id>91</id>
    </did>
  </dids>
</page>

Errors: Access Denied (anonymous), No DIDs found (nested in <status>).

DIDs list in the product: status totals (total, free, active, reserved, closed, terminated), search filters, and a table with DID, Status, Provider, Owner / device, Language, Limit and Reputation columns. — The DIDs list — the same numbers and status values `dids_get` returns.

The four state-change methods

These share one access rule and one response shape.

Who may call them: admin, accountant or reseller — not a partner, not a plain user.

Each takes one parameter, dids_id (the DID's numeric id, not the number itself), which is also the whole fixed hash order. A response — success or error — is a <status> tag nested inside a block that is also called <status>:

<page>
  <status>
    <status>DID successfully terminated</status>
  </status>
</page>

curl -X POST https://api.example.com/api/did_terminate \
  -d "u=admin" \
  -d "dids_id=91" \
  -d "hash=PLACEHOLDER_HASH"

did_terminate

Frees a DID permanently back to the pool (only from free with no reseller attached, or from closed).

Success: DID successfully terminated. Errors: DID was not found, DID was not terminated, DID is not assigned to Device.

did_close

Closes an active, unassigned-to-dialplan DID for the configured number of days.

Success: DID successfully closed. Errors: DID was not found, DID is assigned to Dial Plan, DID is already closed, DID is not assigned to Device.

did_make_free

Releases a terminated, reserved or closed DID back to free.

Success: DID successfully made available. Error: DID was not found, or DID is not assigned to Device if it's still active.

did_subscription_stop

Closes an active DID the same way as did_close, under the older name used for subscription-based numbers.

Success: DID was successfully closed. Errors: DID was not found, DID is not assigned to Device.

did_create

Creates a new DID under one of the caller's providers.

Who may call it: admin, accountant or reseller.

Parameter	Required	In hash	Meaning
`u`	Yes	—	Caller's username.
`provider_id`	Usually — a reseller can omit it if the installation has a default reseller provider configured	1st	Numeric provider id, must belong to the caller (admin/accountant) or be their own/the default reseller provider.
`did`	Yes	2nd	The number itself, digits only. Must not already exist.

Hash parameter order: provider_id, then did (shared list).

curl -X POST https://api.example.com/api/did_create \
  -d "u=admin" \
  -d "provider_id=515" \
  -d "did=41440000099" \
  -d "hash=PLACEHOLDER_HASH"

<page>
  <status>
    <success>DID created</success>
  </status>
  <did_details>
    <id>91</id>
  </did_details>
</page>

Errors: Dont_be_so_smart (plain user or partner), Provider was not found, Your are not authorized to use this Provider (sic — that's the product's own wording), You are not authorized to manage DIDs, Invalid DID specified, DID already exists, DID creation failed.

did_device_assign

Assigns a free DID to a device, making it active.

Who may call it: admin, accountant or reseller.

Also reachable as: /api/did_assign_device.

Parameter	Required	In hash	Meaning
`u`	Yes	—	Caller's username.
`device_id`	Yes	1st	The target device, must be in the caller's scope.
`did`	Yes	2nd	The DID number to assign — must belong to the caller and currently be `free` (or `reserved` for the same user).

Hash parameter order: device_id, then did.

curl -X POST https://api.example.com/api/did_device_assign \
  -d "u=admin" \
  -d "device_id=3327" \
  -d "did=41440000099" \
  -d "hash=PLACEHOLDER_HASH"

<page>
  <status>
    <success>Device assigned to DID</success>
  </status>
</page>

Errors: Device was not found, Your are not authorized to use this Device (sic), DID was not found, Your are not authorized to use this DID (sic), DID is terminated, DID is not free.

did_device_unassign

Frees a DID from its device, back to free.

Who may call it: admin, accountant or reseller.

Also reachable as: /api/did_unassign_device.

Parameter	Required	In hash	Meaning
`u`	Yes	—	Caller's username.
`did`	Yes	1st	The DID number to unassign — must belong to the caller, be `active` and not on a dial plan.

Hash parameter order: did.

curl -X POST https://api.example.com/api/did_device_unassign \
  -d "u=admin" \
  -d "did=41440000099" \
  -d "hash=PLACEHOLDER_HASH"

<page>
  <status>
    <success>Device was unassigned from DID</success>
  </status>
</page>

Errors: DID was not found, You are not authorized to use this DID (spelled correctly this time), DID is terminated, DID is already free, DID is assigned to dialplan.

Check

Call dids_get with search_status=active and confirm every DID it returns really shows Active on the DIDs page in the product.