> For the complete documentation index, see [llms.txt](https://apidocs.api19.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.api19.com/my-inventory/list-my-numbers.md).

# List My Numbers

List all of the numbers on your account, or look up a single number.

## List My Numbers

Use these endpoints to see the numbers (DIDs) on your account and how each one is configured.

| Endpoint                              | What it does                         |
| ------------------------------------- | ------------------------------------ |
| <https://v1.api19.com/dids/my/list>   | Returns every number on your account |
| <https://v1.api19.com/dids/my/single> | Returns one number on your account   |

{% hint style="info" %}
**Authentication:** send your API key as the `key` parameter (in the query string or the POST body), or as the HTTP Basic Auth password.
{% endhint %}

### List All Numbers

`GET | POST https://v1.api19.com/dids/my/list`

Returns a list of all numbers on your account.

#### Parameters

| Argument  | Required | Type   | Description                                        |
| --------- | -------- | ------ | -------------------------------------------------- |
| key       | yes      | string | Your API key                                       |
| show\_all | no       | string | When yes, will get the sub accounts DID's as well. |

{% tabs %}
{% tab title="cURL (POST)" %}

```
curl https://v1.api19.com/dids/my/list \
  -d 'key=YOUR_API_KEY' \
  -d 'show_all=yes'
```

{% endtab %}

{% tab title="cURL (GET)" %}

```
curl 'https://v1.api19.com/dids/my/list?key=YOUR_API_KEY'
```

{% endtab %}

{% tab title="200 OK" %}

```
{
  "status": "ok",
  "dids": [
    {
      "did": "7207742222",
      "call_flow": "0",
      "fax_flow": "1",
      "user_id": "177",
      "price_tag": "inbound_usa_fax",
      "number_location": "usa",
      "offnet_carrier": "none",
      "ratecenter": "DENVER",
      "state": "CO",
      "country": "US",
      "e911": "0",
      "voicemail": "0",
      "notes": "none",
      "call_forward": "0"
    },
    {
      "did": "7207921111",
      "call_flow": "3",
      "fax_flow": "0",
      "user_id": "177",
      "price_tag": "inbound_usa",
      "number_location": "usa",
      "offnet_carrier": "none",
      "ratecenter": "DENVER",
      "state": "CO",
      "country": "US",
      "e911": "0",
      "voicemail": "2",
      "notes": "none",
      "call_forward": "0"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

The `dids` array contains one <mark style="color:$primary;">number object</mark> per number on your account.

### Single Number Lookup

{% hint style="info" %}
GET | POST <https://v1.api19.com/dids/my/single>
{% endhint %}

Returns the details of one number on your account.

#### Parameters

| Argument | Required | Type   | Description                                                                  |
| -------- | -------- | ------ | ---------------------------------------------------------------------------- |
| key      | yes      | string | Your API key                                                                 |
| did      | yes      | string | The number to look up, 10 digits, no `+1` or punctuation (e.g. `3033033333`) |

#### Request

{% tabs %}
{% tab title="cURL (POST)" %}

```
curl https://v1.api19.com/dids/my/single \
 -d 'key=api_token' \
 -d 'did=3033033333'
```

{% endtab %}

{% tab title="cURL (GET)" %}

```
curl https://v1.api19.com/dids/my/single?key=apikey&did=3033033333
```

{% endtab %}

{% tab title="JSON Response" %}

```json
{
    "status": "ok",
    "data": [
        {
            "did": "7207742222",
            "call_flow": "0",
            "fax_flow": "1",
            "user_id": "177",
            "price_tag": "inbound_usa_fax",
            "number_location": "usa",
            "offnet_carrier": "none",
            "ratecenter": "DENVER",
            "state": "CO",
            "country": "US",
            "e911": "0",
            "voicemail": "0",
            "notes": "none",
            "call_forward": "0",
            "campaign_id": "3234324",
            "10dlc_campaign_id": "2823834",
            "crid": "HH239hghr",
            "campaign_status": "approved",
            "in_service": "yes"
        }
    ]
}

(in_service: "no" means it's still being ported)
```

{% endtab %}

{% tab title="Error: not found" %}

```
{
  "status": "error",
  "error": "did not found"
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
When using GET from a shell, wrap the URL in quotes. Otherwise the `&` is treated as a shell operator and the `did` parameter is dropped.
{% endhint %}

{% hint style="info" %}
The result is in `data` (an array with one item), not `dids` as in the list endpoint.&#x20;
{% endhint %}

### The Number Object

Both endpoints return numbers in this format. All values are returned as **strings**, including numeric ones

| Field            | Description                                                        |
| ---------------- | ------------------------------------------------------------------ |
| did              | The phone number, 10 digits                                        |
| call\_flow       | ID of the call flow assigned to the number. `0` = none             |
| fax\_flow        | ID of the fax flow assigned to the number. `0` = none              |
| user\_id         | Your account ID                                                    |
| price\_tag       | Pricing plan for the number, e.g. `inbound_usa`, `inbound_usa_fax` |
| number\_location | Region of the number, e.g. `usa`                                   |
| offnet\_carrier  | Outside carrier the number is hosted with. `none` if hosted by us  |
| ratecenter       | Ratecenter the number belongs to, e.g. `DENVER`                    |
| state            | Two-letter state code, e.g. `CO`                                   |
| country          | Two-letter country code, e.g. `US`                                 |
| e911             | ID of the e911 DID assigned                                        |
| voicemail        | ID of the voicemail box assigned to the number. `0` = none         |
| notes            | Your notes for this number. `none` if empty                        |
| call\_forward    | The DID for call forward. 0 = none                                 |

### Response Status

| status | meaning                                                  |
| ------ | -------------------------------------------------------- |
| ok     | The request succeeded                                    |
| error  | The request failed; see the `error` field for the reason |
