Core concepts

The other pages use the terms this page defines, each with one meaning. Read it once before you integrate, and come back to it for the status tables.

Lines

A line is what sends and receives messages. Every message belongs to one line, and a send names the line it leaves from. A line has an id, a status, and fields that say what kind of line it is. The line’s device is the hardware that sends and receives for a line. iSnap hands each message to the line’s device, and the device reports what happened to it. A status such as delivered therefore exists only when the device reports it.

Field	Meaning
`id`	`line_` followed by 25 characters. See Identifiers.
`phone_number`	The line’s number in E.164 when it is known. It is never `null`: it is an empty string when the line has no number. A shared line has none, and a BYOD line has none until its device reports one. The number is masked on `GET /v1/lines`, and on `GET /v1/lines/{id}` for a caller who does not own the line.
`capabilities`	The services the line can use, as an array of lowercase names: `imessage`, `sms`, `rcs`.
`status`	See Line statuses.
`billing_tier`, `byod`, `shared`, `test_line`, `inbound_only`	The five fields that say what kind of line it is. See Line kinds.
`metadata`	The `metadata` object attached to the line, or `null`. A line created with `"metadata": {}` reads `{}`: treat `null` and `{}` the same. A line you reserve from the marketplace keeps the keys that an earlier owner set: remove them with `PATCH /v1/lines/{id}`.

The marketplace is the set of lines that GET /v1/lines lists: lines you can take now. GET /v1/lines/my lists your own lines whose status is active or reserved.

Line metadata is readable by anyone who holds the line id, and it stays on a line that returns to the marketplace. Never put personal data or secrets in line metadata.

Line kinds

Five fields of the line object tell the kinds of line apart.

Kind	`billing_tier`	`byod`	`shared`	`test_line`	`inbound_only`	What it is
Two-way rented line	`rental_iphone` or `rental_android`	`false`	`false`	`false`	`false`	A line on hardware that iSnap operates.
Inbound-only rented line	`rental_iphone` or `rental_android`	`false`	`false`	`false`	`true`	The same hardware. The line can message a contact only after that contact wrote to it.
BYOD line	`byod_imessage` or `byod_android`	`true`	`false`	`false`	`false`	A line on your own Mac and iPhone (`byod_imessage`), or on your own Android phone (`byod_android`). The line appears when the device completes pairing: see BYOD lines.
Shared line	`shared_imessage`	`false`	`true`	`false`	`false`	A line with no hardware and no number of its own. Each contact is served by one number of iSnap’s own iMessage lines, tied to the contact by a binding: see Shared lines.
Test line	`shared_pool`	`false`	`false`	`true`	`false`	A line set aside for the trials of its owner: a two-way rented line that a wholesale partner converted, which keeps its number, or a line that iSnap created for the account. Its owner can still send from it. See Managing lines.
Dedicated pool line	`shared_pool`	`false`	`false`	`false`	`false`	A line from iSnap’s own pool that iSnap set aside for your account. `GET /v1/lines/{id}` returns `404 not_found` for it, `terminate` returns `403 pool_line_not_terminable` and `cancel` returns `403 pool_line_not_cancellable`: to end it, write to support@isnap.ai.

capabilities follows the kind, except on a pool line that iSnap created for your account:

`billing_tier`	`capabilities`
`rental_iphone`, `byod_imessage`	`["imessage","sms"]`
`rental_android`, `byod_android`	`["sms","rcs"]`
`shared_imessage`	`["imessage"]`
`shared_pool`, on a test line that you converted from a rented line	The `capabilities` it had as a rented line.
`shared_pool`, on a test line that iSnap created for your account	Does not tell the services, and can be `["sms"]`. Such a test line is an iMessage line.
`shared_pool`, on a dedicated pool line	Does not tell the services, and can be `["sms"]`. A dedicated pool line is an iMessage line.

An Android line is a line whose billing_tier is rental_android or byod_android, or a test line whose capabilities include rcs. Every other line is an iMessage line: its device is a Mac, and a shared line sends from the numbers of iSnap’s own iMessage lines. The two have different default sending limits. These API values contain pool. billing_tier: shared_pool marks a test line or a dedicated pool line, and ownership: pool in GET /v1/attention marks the same lines. pool_line_id and pool_line_number name the pool line of a trial: see Trials. The code pool_line_not_terminable refuses to terminate a dedicated pool line, and pool_line_not_cancellable refuses to cancel a test line or a dedicated pool line. The code line_pool_exhausted means that no number of a shared line, or no pool line, is free.

Line statuses

status takes one of six values.

`status`	Meaning	Sends
`provisioning`	The line is being assembled for one of your pre-orders.	No
`available`	The line belongs to no account and can be reserved or assigned.	No
`reserved`	The line is reserved for one account until `expires_at`. It is not billed.	No
`active`	The line belongs to its owner. This is the only status in which a line sends.	Yes
`suspended`	The line still belongs to its owner, but a send returns `403 line_suspended`.	No
`cancelled`	The line is ended. This status is final.	No

A send from a line that is neither active nor suspended returns 400 line_not_active. What moves a line from one status to another:

Change	Cause
`available` to `reserved`	You call `POST /v1/lines/{id}/reserve`.
`reserved` to `available`	You call `POST /v1/lines/{id}/release`, or the reservation ends: at `expires_at`, or earlier when a payment started in the iSnap dashboard has not succeeded 23 hours after it started. See Reservations.
`reserved` to `active`	A wholesale partner calls `POST /v1/lines/{id}/activate`, or iSnap has recorded the first payment that a direct account made for the line in the iSnap dashboard. A direct account cannot activate a line through the API: see Accounts.
`available` to `active`	A wholesale partner calls `POST /v1/lines/assign`.
Created as `active`	A wholesale partner calls `POST /v1/lines/shared`, or a BYOD device completes pairing.
`provisioning` to `active`	The line of a pre-order is handed over.
`active` or `provisioning` to `suspended`	A payment of the line’s per-line subscription fails, or iSnap suspends the line.
`suspended` to its previous status	iSnap lifts the suspension.
`active` or `suspended` to `cancelled`	You call `POST /v1/lines/{id}/terminate`, or the date set by `POST /v1/lines/{id}/cancel` arrives.
`active` or `suspended` to `available`	The per-line subscription of a rented line ends. The line leaves the account: it is not `cancelled`.
`active` to `cancelled`	A BYOD line is no longer covered by the BYOD slots of the account.

Three things to know about these statuses:

Only iSnap lifts a suspension. Write to support@isnap.ai to ask for it. A suspended line of a wholesale partner still counts on the monthly invoice.
GET /v1/lines/my lists only active and reserved lines: a line that becomes suspended or cancelled leaves the list. Read a rented or BYOD line in any status with GET /v1/lines/{id}. A cancelled line keeps its owner. No read operation returns a shared line, a test line or a dedicated pool line that is suspended or cancelled: GET /v1/lines/my lists it only while it is active or reserved, and GET /v1/lines/{id} returns 404 not_found for it in every status. GET /v1/attention does not list a line for being suspended: keep the ids of your lines, and read each with GET /v1/lines/{id}.
No event announces a reservation, its expiry, a release, an activation by activate, by assign or by a payment in the dashboard, the creation of a shared line, a suspension, the end of a suspension, or the return of a rented line to the marketplace. See What events do not announce, and read the status from the API.

Getting a line and Managing lines describe each operation.

Accounts

Two kinds of account call the API.

A wholesale partner is an account that iSnap bills on one monthly invoice. iSnap grants this status: write to support@isnap.ai to ask for it.
A direct account is any account that is not a wholesale partner. It pays in the iSnap dashboard, by card: there it buys a marketplace line, pays the first month of a pre-order, buys BYOD slots and hosted macOS sessions, and saves a card. No operation that an API key can call makes these payments. Through the API, a direct account cannot activate a reserved line, assign a line, create a shared line or rent a hosted macOS session. It pays for an active rented line through a per-line subscription, whose id is the line’s stripe_subscription_id. That field is null on a rented line that the account received by transfer while the line was not active.

Payments, invoices and payment methods are managed in the iSnap dashboard. No field of any response says which kind your account is. The refusal codes below are the sign that an operation is for wholesale partners only.

Task	Any account	Wholesale partners only
Getting a line	Browse the marketplace, reserve a line and release it, order a line with a pre-order. A direct account buys a line, and pays the first month of a pre-order, in the dashboard.	Activate a reserved line, assign a line, create a shared line.
Managing a line	Read your lines, set their metadata, configure them, read the health of a BYOD line, list the lines that need attention, terminate a line, transfer a line, switch a rented line that has no per-line subscription between inbound-only and two-way.	Cancel a line at its anniversary, set the anniversary, convert a line to a test line and back.
Hosted macOS sessions	None through the API. A direct account buys sessions in the dashboard.	Rent a session through the API, and manage it.

What a direct account receives on those operations:

Operation	Refusal
`POST /v1/lines/{id}/activate`, `POST /v1/lines/assign`, `POST /v1/lines/{id}/convert-to-test`, `POST /v1/lines/{id}/convert-from-test`	`402 checkout_required`
`POST /v1/lines/shared`	`402 payment_required`
`POST /v1/lines/{id}/cancel`, `POST /v1/lines/{id}/anniversary`	`409 line_not_wholesale_metered`
`POST /v1/macos-sessions/rent`	`403 not_a_wholesale_partner`
`POST /v1/lines/{id}/variant` on a line with a per-line subscription	`409 variant_bound_to_stripe_price`

The operations table marks every operation that is for wholesale partners only.

Messages

A message is one text, one or more attachments, or both, exchanged between one line and one contact. The contact is the person on the other side. The recipient is the to of a send. A handle is what identifies a contact: a phone number in E.164, or an email address. A send takes a phone number only. An inbound message can come from an email address. The message object has one shape everywhere: in the response of a send, of a read and of a cancel, in each item of GET /v1/messages, and in the message field of message events.

Field	Meaning
`id`	`msg_` followed by 25 characters.
`direction`	`outbound`: the line sent it. `inbound`: the line received it.
`kind`	`message`, `voice` for a voice note, or `reaction` for a reaction stored as its own entry.
`to`, `from`	On an outbound message, `to` is the recipient in E.164 and `from` is the line’s number. On an inbound message, `from` is the sender and `to` is the line’s number. On a shared line, the line’s side is the number that serves that contact. `from` is an empty string when the line has no number. On a message typed on the line’s device, `to` is the contact’s handle as the device stores it.
`body`	The text. `null` when the message has no text.
`status`	See Message statuses.
`service`, `channel`	See Services.
`scheduled_for`, `schedule_reason`	On a held message, a message with `status: scheduled`: the planned departure time, and why iSnap holds it. On an outbound message that is not held, `scheduled_for` equals `queued_at` and `schedule_reason` is `null`. See Held messages.
`created_at`	When iSnap recorded the message.
`queued_at`	When iSnap accepted an outbound message, a held message included. `null` on an inbound message and on a message typed on the line’s device.
`sent_at`, `delivered_at`, `read_at`, `failed_at`, `cancelled_at`	When each step happened. Each is `null` until it happens.
`error_code`, `error_message`	`null` unless the message failed. See Sending messages.
`metadata`	The `metadata` object you sent with the message, or `null`.

iSnap deletes every message at least 72 hours after it recorded it, whatever its status: see Retention. A message carries personal data: the handles in to and from, the text in body, attachment file names, and whatever you put in metadata. Request it only when needed. Do not copy it into logs, tickets or other tools. Refer to a contact by an id of your own.

Message statuses

status takes one of seven values.

`status`	Meaning	Set by	Final
`queued`	iSnap accepted the message. It is waiting for the line’s device, or the line’s device has taken it and has not reported the outcome.	iSnap, at the send or when it releases a held message.	No
`scheduled`	iSnap holds the message until `scheduled_for`: because of a sending limit, the spacing between messages, quiet hours or an earlier message to the same recipient, or, on a shared line, because the number that serves the contact cannot send now. `schedule_reason` names the cause: a message held behind an earlier message to the same recipient takes that message’s reason, and `pending_retry` means that iSnap retries the release. A message still held 48 hours after iSnap accepted it becomes `failed`, even when its `scheduled_for` is later.	iSnap, when it accepts the message or holds it again.	No
`sent`	The line’s device reported that it sent the message. `sent_at` is set.	The line’s device.	No
`delivered`	The line’s device reported a delivery receipt. Every inbound message also has this status.	The line’s device.	No
`read`	The line’s device reported that the recipient read the message. Only an outbound message takes this status.	The line’s device.	No
`failed`	The message failed, or iSnap stopped waiting for its outcome (`error_code: no_terminal_ack`), in which case it can have reached the recipient. `failed_at` is set.	The line’s device, or iSnap.	Yes: treat it as final, see below
`cancelled`	You canceled the message with `DELETE /v1/messages/{id}` before the line’s device took it.	You.	Yes

An outbound message moves from scheduled to queued, then to sent, delivered and read. Around that path:

A queued or scheduled message can become cancelled.
A message in any status except cancelled can become failed, even after delivered or read.
cancelled never changes. Treat failed as final too: after a failure that the line’s device reported, a late send confirmation can set status back to sent, while failed_at stays set. A message that has a failed_at failed.
Nothing is guaranteed to follow sent, delivered or read. iSnap learns “delivered” and “read” only from the line’s device and never assumes them: with no report, a message stays sent until iSnap deletes it.
An inbound message is delivered from the start. There is no status for “received”.

The order is not strict. A delivery receipt can arrive before the device confirms the send: the confirmation then sets status back to sent while delivered_at stays set. A message can become read while delivered_at is still null. Use the timestamps, not only status: a message with a delivered_at was delivered. To build the status from events, apply Building the status from events. A message becomes failed in four cases: the device reported a failure, the device took the message and never reported an outcome, the message was still waiting 48 hours after iSnap accepted it (a held message included), or the line was terminated while the message was waiting. iSnap never resends a failed message. Sending messages describes each case and what to do.

Services

The service is what the line’s device used to carry a message: iMessage, SMS or RCS. The service field of a message reports it.

The device chooses the service when it sends. The API cannot choose it.
service is null until the device confirms the send. It stays null when the send fails, and when the device does not report the service.
channel is a request field of POST /v1/messages that only takes auto, its default.
In a response, channel is auto on a message sent through the API. On an inbound message, and on a message typed on the line’s device, it equals service. On a reaction it is iMessage.

The services a line can use are in its capabilities: see Line kinds.

Chats

A chat is the exchange between one line and one contact. iSnap creates it at the first message in either direction and uses the same chat for both directions. Its id is chat_ followed by 25 characters.

The message object has no chat id. GET /v1/chats gives the chat ids, and so does the chat_id field of message.received, of message.sent with origin: "device", of the message.read that follows your own mark-read call, and of the typing indicator events.
A message that the line receives in a group is recorded in one chat for that group. That chat shows a single contact_handle, the first sender seen, and nothing marks it as a group. iSnap does not send to groups.
A chat is never deleted. It stays listed after its messages are deleted.
A chat belongs to its line, not to your account. When a line leaves your account, by a transfer or by a return to the marketplace, its chats stay with the line, with their contact_handle, and the next owner lists them. When the next owner marks such a chat read, it receives in message.read each of your inbound messages of the chat that iSnap still keeps and that you had not marked read, with its text, the sender’s handle and the names of its files. The events about your earlier messages of the line go to the next owner too. Before you transfer a line or let it return to the marketplace, export what you need from its chats. After you take a line, ignore the chats and the events about messages older than the time the line became yours. Note that time when you get the line: no event announces a transfer. See A chat is never deleted, and Lines that change owner for the rule and for that time.

A chat carries the contact’s handle in contact_handle: it is personal data.

Identifiers

An id is a prefix, an underscore and 25 characters from 0-9A-Za-z, except the kinds of id that the end of the table lists. Ids are case-sensitive.

Identifier	Form	Example	Where it appears
Line	`line_` and 25 characters	`line_8Xk2mQ4vTn7Bw9Rz3Lc6Yp1Hd`	`id` of a line, `line_id`, `from_line_id`, `pool_line_id`
Message	`msg_` and 25 characters	`msg_3Lc6Yp1Hd8Xk2mQ4vTn7Bw9Rz`	`id` of a message, `message_id`, `reply_to_message_id`, `parent_message_id`
Chat	`chat_` and 25 characters	`chat_7Bw9Rz3Lc6Yp1Hd8Xk2mQ4vTn`	`id` of a chat, `chat_id`
Attachment	`att_` and 25 characters	`att_Q4vTn7Bw9Rz3Lc6Yp1Hd8Xk2m`	`id` of an attachment, the `attachments` of a send, `attachment_id`
Webhook subscription	`wh_` and 25 characters	`wh_Yp1Hd8Xk2mQ4vTn7Bw9Rz3Lc6`	`id` of a subscription, `webhook_id` of a delivery record (the `data.webhook_id` of a probe is another value)
Delivery	`whd_` and 25 characters	`whd_k2mQ4vTn7Bw9Rz3Lc6Yp1Hd8X`	`id` of a delivery, `delivery_id`, `replay_of`
Event	`evt_` and 25 characters	`evt_2Yc8RkP4mWq7Lx3Nv9Tb5Hs1D`	`event_id` of an event
Trial	`trl_` and 25 characters	`trl_n7Bw9Rz3Lc6Yp1Hd8Xk2mQ4vT`	`trial_id`
Hosted macOS session	`mcs_` and 25 characters	`mcs_Rz3Lc6Yp1Hd8Xk2mQ4vTn7Bw9`	`id` of a session, `macos_session_id`
Device session	`dvs_` and 25 characters	`dvs_5Tn8Kc3Wq6Zb9Lx2Hm7Vd4Ry1`	`device_session_id` of `line.connected`, `line.disconnected` and `line.degraded`
Lookup check	`lkp_` and 25 characters	`lkp_c6Yp1Hd8Xk2mQ4vTn7Bw9Rz3L`	`probe_id` of a pending lookup
Request	`req_` and 25 characters	`req_4Tn7Bw9Rz3Lc6Yp1Hd8Xk2mQv`	`request_id` of every response, `X-Request-Id`
Trace	32 lowercase hexadecimal characters	`0af7651916cd43dd8448eb211c80319c`	`trace_id` of every response and every event, `X-Trace-Id`
Pre-order	A UUID	`6f1c2a9e-4b7d-4c1a-9e55-0d2b8f3a7c41`	`id` of a pre-order, `pre_order_id`
Account	A UUID	`0b9d4e52-7c3a-4f18-8a6e-5d1c2b3a4f60`	`to_user_id` of a line transfer

A line, message, chat, webhook subscription, delivery, pre-order or hosted macOS session id of another form in a path returns 400 validation_failed. With a line-scoped key, an operation under /v1/lines/{id}/ checks the list first: an id that starts with line_ and is not in the list returns 403 forbidden, before the 400. Send only ids that start with line_: an id of another form returns 403 forbidden, or 500 internal_error when it is not a UUID.

Timestamps

A timestamp in a response is ISO 8601 in UTC, with milliseconds and a Z suffix: 2026-10-08T14:22:57.392Z. A timestamp in a request is ISO 8601 with a Z suffix. since and until on GET /v1/messages and GET /v1/chats also accept an explicit offset such as +02:00. Pagination gives the rule of each list. Two values are Unix times in seconds, not ISO 8601: the X-RateLimit-Reset header of a response, and the webhook-timestamp header of a webhook delivery.

Other terms

Each of these terms has one meaning on every page. Its guide defines its states and rules.

Term	Meaning	Guide
Operation	One method and path of the API, such as `POST /v1/messages`.	API reference
Dashboard	`https://platform.isnap.ai`, where you create and revoke API keys, and where a direct account pays.	Authentication, Accounts
Per-line subscription	How a direct account pays for one rented line. Its id is the line’s `stripe_subscription_id`.	Accounts
API key, trial key, line-scoped key	The three kinds of key.	Authentication
Metadata	The `metadata` object you attach to a resource: your own keys and values, which iSnap stores and returns unchanged.	Managing lines
Sending limit	One of the five counters that bound what a line sends, each on a rolling window.	The five limits
Held message	A message with `status: scheduled`.	Held messages
Quiet hours	The hours of the recipient’s local time in which iSnap holds the messages of a line, except a message in the reply lane or sent with `ignore_quiet_hours: true`.	Quiet hours
Reply lane	The rule that lets a reply to a contact who wrote to the line in the last 24 hours (by default), and a held message whose contact writes, leave despite quiet hours and four of the five sending limits. `reply_lane` on a message says whether it is in the lane.	Reply lane
Reaction	A mark that a person puts on a message, such as `love` or `like`: an iMessage tapback.	Chat features
Messages conversation	What the Messages app on the line’s device shows for one contact. It is not a chat: some features need it on the device.	Chat features
Webhook subscription	The resource under `/v1/webhooks`: a URL of yours and the events it receives. “Your endpoint” is that URL.	Webhooks overview
Event	One fact that iSnap reports, with an `event_id` and an `event_type`.	Event catalog
Delivery, attempt	A delivery is one event for one subscription. An attempt is one HTTP request of a delivery.	Delivery guarantees
Events feed	`GET /v1/webhooks/events`: the events of the last 72 hours that matched a webhook subscription of your account while it was active and not suspended. An account without such a subscription has an empty feed.	Events feed
Probe	The `webhook.test` request that iSnap sends to a suspended subscription.	Suspension
Signing secret	The secret of a subscription, with which you verify each delivery.	Verifying signatures
Trial, pairing code, pool line	A trial lets a prospect exchange messages with a line from their own phone. The pairing code is the `token` of a trial. The pool line is the line a trial runs on (`pool_line_id`, `pool_line_number`): a line of iSnap’s trial pool, or a test line of your account.	Trials
Live trial	A trial that is `pairing_pending` inside its pairing window, `active` or `dormant`.	Limits on live trials
BYOD	Bring your own device: a line that runs on your own Mac and iPhone, or on your own Android phone.	BYOD lines
BYOD slot	What a direct account needs for each BYOD line: each BYOD line that is not `cancelled` uses one slot. A wholesale partner needs none.	BYOD slots
Bridge app, activation code	The bridge app is the iSnap app installed on a BYOD device. The activation code is the `activation_code` that pairs the device.	BYOD lines
Device session	The pairing of one device with a line, identified by `device_session_id`. `line.disconnected` carries the id of a session that ended, or `null` when the line had none: its section lists the cases in which it is sent. `line.connected` and `line.degraded` carry the id of the session that serves the line.	Connectivity events
Pre-order	A request to iSnap to build one rented line for you.	Pre-orders
Hand-over	The moment the line of a pre-order becomes `active` on your account.	Pre-orders
Hosted macOS session	The resource under `/v1/macos-sessions`. It is not a line: it has no number and sends nothing.	Hosted macOS sessions
Binding	On a shared line, the tie between one contact and the number that serves them. The first message to the contact creates it, and `binding.released` announces its end.	Shared lines
Billing anchor, anniversary	`billing_anchor_at` and `anniversary_at` of a line.	Managing lines
Variant	Whether a rented line is two-way or inbound-only: its `inbound_only`.	Variant changes

Get started

Using the API

Messaging

Lines

Core concepts

Lines

Line kinds

Line statuses

Accounts

Messages

Message statuses

Services

Chats

Identifiers

Timestamps

Other terms

​Lines

​Line kinds

​Line statuses

​Accounts

​Messages

​Message statuses

​Services

​Chats

​Identifiers

​Timestamps

​Other terms

Lines

Line kinds

Line statuses

Accounts

Messages

Message statuses

Services

Chats

Identifiers

Timestamps

Other terms