> ## Documentation index
> Fetch the complete documentation index at: https://leadmcp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Look up phone numbers in batch

`POST /api/v1/contacts/from-phone`

Authentication: API key.

JSON batch lookup (same pattern as `POST /api/v1/enrich/from-email`). Each item accepts `phone` or `cellphone`. US phones are stored as `+1 XXX-XXX-XXXX` (space after country code). Optional `limit_per_item` (default 1, max 10).

### Body parameters

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `items` | array | no |  |  |
| `limit_per_item` | number | no |  |  |

### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `ok` | boolean | True when the request succeeded. |
| `results` | array | One result object for each item you sent, in the same order. |
| `creditsRemaining` | number | Plan credits left after this request. Null on unlimited plans. |

### Example request

```bash
curl -sS -X POST "https://leadmcp.ai/api/v1/contacts/from-phone" \
  -H "X-API-Key: lb_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"phone":"+1 415-555-0142"},{"phone":"5550000000"}],"limit_per_item":1}'
```

### Example response (200)

```json
{
  "ok": true,
  "results": [
    {
      "phone": "+1 415-555-0142",
      "success": true,
      "data": { "first_name": "Jane", "cellphone": "+1 415-555-0142" }
    },
    {
      "phone": "5551234567",
      "success": false,
      "data": null
    }
  ],
  "creditsRemaining": 4998
}
```