List purchased-number inventory

List the purchased-number records whose stored owner matches the account represented by your API credentials. A record being present is distinct from a successful live-call test.

Request

Use server-side API credentials over HTTPS. The examples read credentials from environment variables; they contain no working credentials. Inspect status.code in the JSON body as well as the HTTP status. These legacy handlers do not consistently set an HTTP error status for an application error.

curl --user "$MULTITEL_API_USER:$MULTITEL_API_PASSWORD" \
  "https://api.multitel.net/v3/inventory"

To filter by a single stored telephone number, use the optional path form:

curl --user "$MULTITEL_API_USER:$MULTITEL_API_PASSWORD" \
  "https://api.multitel.net/v3/inventory/12025550100"

Use the stored international telephone number as digits, including country code. Do not pass a PBX extension, number UUID, area ID or prefix ID in its place. The supplied number selects an existing record; it does not purchase or configure one.

Response

The response member is always an array on success, including the single-number path form. status.results is the array length.

This is an illustrative response shape, not account data or a current price quote.

{
  "status": {
    "code": 200,
    "msg": "",
    "results": 1
  },
  "response": [
    {
      "number": "12025550100",
      "uuid": "NUMBER_UUID",
      "description": "Main reception",
      "isocode": "US",
      "config": {
        "uri": "sip:reception@example.com",
        "uri2": "",
        "uri3": "",
        "forward_destination": "",
        "sms_uri": "",
        "sms_forward_destination": ""
      },
      "features": {
        "voice": "1",
        "sms": "1",
        "mms": "0"
      },
      "status": {
        "capacity": {
          "assigned_channels": "2",
          "used_channels": "0",
          "overflow": "0",
          "overage_charge": "0.01"
        },
        "origination": {
          "origination_trunk_id": "ORIGINATION_ID",
          "origination_trunk_name": "ORIGINATION_NAME",
          "origination_country_iso": "US",
          "origination_continent_iso": "NA",
          "origination_continent_name": "North America"
        },
        "service_active": "1",
        "force_codec": "",
        "force_dtmf": ""
      },
      "billing": {
        "cnam": "0",
        "overflow": "0",
        "autorenew": "1",
        "persistent": "0",
        "date_created": "2026-01-01 00:00:00"
      },
      "price": {
        "setup_price": "0.00",
        "monthly_price": "1.00",
        "per_minute": "0.01",
        "free_minutes": "0",
        "remaining_minutes": "0"
      }
    }
  ]
}

Returned number fields
Field	Meaning
`number, uuid, description, isocode`	The stored telephone number, opaque number identifier, description and country code.
`config`	Stored voice destinations, external forwarding, SMS destination and SMS forwarding fields. This endpoint does not edit them.
`features`	Stored voice, SMS and MMS capability flags. Legacy stored flags are not guaranteed to be JSON booleans.
`status.capacity`	Assigned and used channel values, overflow setting and stored overage charge. This is stored metadata, not a fresh capacity quotation or a live call test.
`status.origination`	Stored origination metadata. Treat identifiers as opaque; do not derive application logic from internal names.
`status.service_active, force_codec, force_dtmf`	Stored activation and media configuration fields. A flag alone does not prove successful inbound delivery.
`billing`	Stored CNAM, overflow, renewal, persistence and creation values. Reading them does not change renewal or other billing settings.
`price`	Stored setup/monthly/per-minute prices and minute allowances. The handler supplies no currency field or fresh quote. Do not infer currency from the sample values or use them as a current purchase quotation.

Filtering and pagination

This handler has no pagination, page-size limit or explicit sort order. It returns all non-void records selected by its query. It does not implement a service-active-only filter or a separate archived-number view. Do not assume the order of returned records is stable.

No matching numbers

If the account has no matching non-void records, the JSON body has status.code 404 and a message containing no numbers found. It does not return an empty successful array. The message includes a source-reference suffix that clients should not parse as a stable identifier.

Next steps

Use numberinfo when you need the additional legacy registration and number-reference fields for one number. Inspect voice and messaging destinations before changing any route through a separate configuration operation.