# Check a list

> Screen a list of numbers for blue-bubble reachability before sending to it.

Check whether numbers can receive blue-bubble messages, before you message them. This is read-only: nothing is delivered and nobody is notified. See Check a list first for the team workflow.

## Check a list

POST https://beam.aisync.link/v1/screen

  
| Field | Type | Notes | 
  
| numbers | array of strings | The numbers to check. Either this or list is required. | 
  
| list | string | Pasted text or CSV. Beam picks the phone column and skips a header row. | 
  
| name | string, optional | A label so you can find this check later. | 
  
| wait | boolean, optional | Lists of 25 or fewer return results inline by default. Set false to always get a job id back instead. | 

curlJavaScriptPythonCopy
```
curl -X POST https://beam.aisync.link/v1/screen \
  -H "x-api-key: YOUR_WORKSPACE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "October leads",
    "numbers": ["+12125550199", "(480) 555-0134", "5551234567"]
  }'
```

```
const res = await fetch("https://beam.aisync.link/v1/screen", {
  method: "POST",
  headers: {
    "x-api-key": process.env.BEAM_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "October leads",
    numbers: ["+12125550199", "(480) 555-0134"],
  }),
});
const data = await res.json();
```

```
import os, requests

res = requests.post(
    "https://beam.aisync.link/v1/screen",
    headers={"x-api-key": os.environ["BEAM_API_KEY"]},
    json={"name": "October leads",
          "numbers": ["+12125550199", "(480) 555-0134"]},
)
data = res.json()
```

### Small list, answered inline

```
{
  "job_id": "12",
  "id": "12",
  "name": "October leads",
  "status": "done",
  "total": 3,
  "checked": 3,
  "progress": 100,
  "summary": { "blue": 1, "text_only": 1, "invalid": 1, "unknown": 0 },
  "blue_rate": "50.0%",
  "results": [
    { "raw": "+12125550199", "phone": "+12125550199", "result": "blue" },
    { "raw": "(480) 555-0134", "phone": "+14805550134", "result": "text_only" },
    { "raw": "5551234567", "phone": "+15551234567", "result": "invalid" }
  ]
}
```

### Larger list, checked in the background

```
{ "job_id": "13", "status": "running", "total": 4820 }
```

## Get results

GET https://beam.aisync.link/v1/screen/{job_id}
Returns progress and counts. Add ?results=1 for every row, and &only=blue to return just one group (blue, text_only, invalid, unknown).
curlCopy
```
curl "https://beam.aisync.link/v1/screen/13?results=1&only=blue" \
  -H "x-api-key: YOUR_WORKSPACE_KEY"
```

## Result values

  
| Value | Meaning | 
  
| blue | Can receive blue-bubble messages. | 
  
| text_only | A real number that cannot receive blue messages. Send a normal text. | 
  
| invalid | Not a usable phone number. | 
  
| unknown | The check could not be completed. Do not treat this as text-only; re-check later. | 

## Limits

  - 25,000 numbers per job.
  - Results are reused for 24 hours, so repeated checks of the same numbers are instant.
  - blue_rate counts only real, reachable numbers, so invalid rows never drag the number down.