> For the complete documentation index, see [llms.txt](https://developer.parvenu.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.parvenu.io/enrichments/validate-phone/list-lookup.md).

# List Lookup

Check the mobile phone of every contact in a Parvenu list with your own Phone Validator key. Asynchronous, writes results back into the list.

<mark style="color:green;">`POST`</mark> `/validate_phone_list`

{% hint style="info" %}
This is an **asynchronous** endpoint. It returns a job acknowledgement, not data. Poll `/check_list_status` until the list reports `done`, then fetch the rows with `/download_list`. **Free in Parvenu credits**: it uses your own Phone Validator key, saved on the [Integrations](https://app.parvenu.io/app/integrations) page, so Phone Validator bills your account for each number. Results are written to the `phone_type`, `phone_company`, `fake_number` and `phone_location` columns.
{% endhint %}

Use this to check every mobile number in a list in one call, rather than looping over Individual Lookup per row.

Only the `phone_number` (Mobile Phone) column is checked. Contacts with no mobile phone are skipped. A fake number is never removed: it stays on the row with `fake_number` set to `Yes`, so you can filter it out.

**Headers**

| Name         | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |

**Body**

| Name         | Type   | Description                                                                                                                                                                                                                                                           |
| ------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api_key`    | string | Your API Key.                                                                                                                                                                                                                                                         |
| `listname`   | string | Name of the existing Parvenu list to check.                                                                                                                                                                                                                           |
| `view`       | string | Optional. Which rows of the list to process. `all` (default) processes every contact in the list; `verified` restricts the run to contacts whose email address is verified.                                                                                           |
| `saved_view` | string | Optional. Name of a saved view on this list. Runs only on the contacts in that view. Don't combine with `view`, `filter_stack` or `search`.                                                                                                                           |
| `wait_for`   | string | Optional. Set to `phone` to start the check now but run it on each contact only once Find Mobile Phone has filled their number. Use it when a [Find Mobile Phone](https://developer.parvenu.io/enrichments/find-mobile-phone/list-lookup.md) list run is still going. |

**Saved views.** To run only on the contacts in a saved view, send its name as `saved_view`. See [List Saved Views](https://developer.parvenu.io/manage-lists/list-saved-views.md).

**Response**

Every list-scoped trigger answers with the same job acknowledgement.

| Field               | Type    | Description                                                                                        |
| ------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `status`            | string  | `queued` when the run is accepted. Poll `/check_list_status`; the finished status there is `done`. |
| `job_id`            | string  | Identifier for this run. Always a string.                                                          |
| `list_name`         | string  | The list being checked.                                                                            |
| `view`              | string  | Which rows were selected, `all` or `verified`.                                                     |
| `rows_selected`     | number  | How many rows matched your `view` before the page limit was applied.                               |
| `rows_fetched`      | number  | How many rows this run actually picked up.                                                         |
| `truncated`         | boolean | `true` when the list held more rows than `max_rows`.                                               |
| `max_rows`          | number  | The ceiling a single run will fetch.                                                               |
| `credits_estimated` | number  | Always `0`.                                                                                        |

See [Response Format](https://developer.parvenu.io/getting-started/response-format.md) for the fields every endpoint returns.

**What each column holds**

| Column           | Values                                                                                                    |
| ---------------- | --------------------------------------------------------------------------------------------------------- |
| `phone_type`     | `Cell Phone`, `Landline`, `VOIP`, `Toll-Free`, `Unknown`, `Fake` or `Invalid`.                            |
| `phone_company`  | The phone company, for example `T-MOBILE`.                                                                |
| `fake_number`    | `Yes` or `No`.                                                                                            |
| `phone_location` | Where the number was issued, from its area code, for example `LAS VEGAS, NV`. Not where the phone is now. |

Each checked row also gets a line in its `log`, for example `Validate Phone - Phone Validator - Cell Phone, T-MOBILE ✅ - 10-20-26 - 0 Credits - API`.

**Example**

{% tabs %}
{% tab title="Input" %}

```json
{
  "api_key": "your_api_key",
  "listname": "my_list"
}
```

{% endtab %}

{% tab title="Output" %}

```json
{
  "status": "queued",
  "job_id": "3f0c2a9e-6b1d-4c8e-9a7f-2d5e8b1c4a90",
  "list_name": "my_list",
  "view": "all",
  "rows_selected": 2,
  "rows_fetched": 2,
  "truncated": false,
  "max_rows": 5000,
  "credits_estimated": 0.0,
  "credits_used": 0,
  "credits_remaining": 4823,
  "message": "Job created",
  "success": true
}
```

{% endtab %}

{% tab title="Error: no key saved" %}

```json
{
  "status": "error",
  "error": {
    "code": "http_error",
    "message": "No Phone Validator key found. Add your key on the Integrations page, then try again.",
    "detail": "no_phone_validator_key"
  },
  "success": false
}
```

{% endtab %}
{% endtabs %}

With no Phone Validator key saved, the call answers `400` before anything is looked up, and nothing is charged.

**Retrieving results**

* [Check List Status](https://developer.parvenu.io/get-enrichment-results/check-list-status.md)
* [Download List Data](https://developer.parvenu.io/get-enrichment-results/download-list-data.md)
