# List Numbers

## GET or POST Request

{% hint style="info" %}
<https://v1.api19.com/dids/available/list?key=yourkey​>
{% endhint %}

Send us a GET/POST request with your key (in the URI as key or as http password)

**Ratecenter / State search**\
You can send ratecenter=\[ratecenter] and state=\[state]

**Area Code Search**\
If you would rather get by area code, you can send npa=\[areacode]

**Toll Free Search**\
To request toll free, send state=tf in your request

We give you the City and Ratecenter so you can get human readable data (for instance ratecenter LSAN DA 01 is actually Los Angeles: 01 as the City.

<table data-header-hidden><thead><tr><th width="154.63641357421875"></th><th width="145.36358642578125"></th><th></th></tr></thead><tbody><tr><td>Argument</td><td>Required</td><td>Type</td></tr><tr><td>state</td><td>yes</td><td>string</td></tr><tr><td>ratecenter</td><td>no</td><td>string</td></tr><tr><td>quantity</td><td>no</td><td>int</td></tr><tr><td>npa</td><td>no</td><td>int</td></tr><tr><td>nxx</td><td>no</td><td>int</td></tr><tr><td>related</td><td>no</td><td>yes<br>set to yes if you only want the specific area code requested and nothing else </td></tr><tr><td>random</td><td>no</td><td>yes<br>randomize numbers in response</td></tr><tr><td>key</td><td>yes</td><td>your API key</td></tr></tbody></table>

{% tabs %}
{% tab title="Curl Post" %}

```php
curl -X POST https://v1.api19.com/dids/available/list \
 -d 'ratecenter=AUSTIN' \
 -d 'state=TX' \
 -d 'quantity=2' \
 -d 'key=your-api-key'
 
or area code based

curl -X POST https://v1.api19.com/dids/available/list \
 -d 'npa=303' \
 -d 'quantity=2' \
 -d 'key=your-api-key'
 
or toll free request

curl -X POST https://v1.api19.com/dids/available/list \
 -d 'state=tf' \
 -d 'key=your-api-key'
```

{% endtab %}

{% tab title="Curl Get" %}

```php
curl https://v1.api19.com/dids/available/list?ratecenter=AUSTIN&state=TX&key=api_token

or area code based

curl https://v1.api19.com/dids/available/list?npa=720&key=api_token

or a toll free request

curl https://v1.api19.com/dids/available/list?state=tf&key=api_token
```

{% endtab %}

{% tab title="JSON Success" %}

```json
{
    "status": "ok",
    "numbers": {
        "17202224017": {
            "did": "17202224017",
            "number": "(720)&nbsp;222-4017",
            "tier": 1,
            "price_monthly": "1.5",
            "price_setup": "1.5",
            "price_minute": "0.0075",
            "ratecenter": "DENVER",
            "state": "CO"
        },
        "17209922019": {
            "did": "17209922019",
            "number": "(720)&nbsp;992-2019",
            "tier": 1,
            "price_monthly": "1.5",
            "price_setup": "1.5",
            "price_minute": "0.0075",
            "ratecenter": "DENVER",
            "state": "CO"
        }
    },
    "count": 2
} 
```

{% endtab %}

{% tab title="JSON Error Response" %}

```json
{
    "status": "error",
    "error": "no numbers available for search",
    "verbose": "none"
} 
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apidocs.api19.com/numbers-ordering/list-numbers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.