Numbers

Check a list

Current documentation

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.

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).

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.