GET /v1/lines/available

GET /v1/lines/available?channel=imessage

Use this when a person is about to write to you first — on a sign-up page, in an app, on a printed card — and you need to tell them which number to text. If your project has several lines, it answers with the one the platform would give somebody new right now.

It picks the line the same way a first send to a new person does. Of your active lines on the channel whose connection is up and that have a place left, it takes the one with the healthiest connection, then one that has not reached today's pace for new people, then the one with the most places left, then the oldest. Lines that are paused, full or whose connection is down are never picked.

It reserves nothing. Two people shown the same number can both text it, and a send in between can change the answer. Ask again each time you show a number, rather than caching one.

If the person is new to your project, texting that number pins them to that line and takes a place on it. Someone already on another of your lines keeps that as their first line, and their message opens a conversation on this one. Later sends that name no line go out on the number they last wrote to, so on this one; the whole order is in Replying.

curl "https://api.mapier.ai/v1/lines/available?channel=imessage" \
  -H "Authorization: Bearer $MAPIER_API_KEY"

Request

Response

{
  "lineId": "0192a7b0-3e4f-7051-8c6d-7e8f9a0b1c2d",
  "address": "+14155550142",
  "channel": "imessage"
}

With a test key

A test key answers with the sandbox's line for the channel. The sandbox has one number, so the address is the same every time.

When no line can take somebody new

When every line on that channel is full, paused or down, this answers with the same 503 a first send to somebody new would get — no_line when there is no active line at all, no_line_capacity when every line is full (capacity_exhausted at x-mapier-version: 2026-10-15 or later), and line_unavailable with details.reason: "relay_down" (transport_down at 2026-10-15 or later) when every line's connection is down. Show the person something other than a number until it clears. GET /v1/whoami shows each line's room in contactsAssigned, maxContacts and takesNewContacts.

Errors

Related