iMessage line settings

Test keys (rsms_test_) can read these settings but not change them, and can’t buy or cancel a line: every write here answers them 403 test_key_not_allowed.

An iMessage line is billed monthly at your price, paid by card: the first month when you buy it, then monthly until you cancel. If your account is a sub-account that pays Ready with its own card, you pay your agency’s price instead; List your iMessage lines returns yours in monthly_cents. Buying takes two calls, as in the app: Start a purchase holds the first month on the card, then Buy the line sets the line up and takes that payment.

#List your iMessage lines

Your iMessage lines, what one costs your account a month, and the consent sentence you agree to when you buy one. Every role can read it.

Returns

data.linesobject[]: One { line } per line, line being its phone number. Empty when you have none.
data.monthly_centsinteger: What one line costs your account a month, in cents. A purchase holds this for the first month.
data.consent_textstring: The sentence you agree to by sending consent_attested: true when you buy. Ready records it with your purchase.
data.auto_add_max_linesinteger: The most lines adding lines automatically can buy.

Errors

HTTP	Code	When
500	`internal_error`	We couldn’t read your lines. Retry.

curl "https://api.tryready.com/v1/imessage-lines" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/imessage-lines', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/imessage-lines",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": {
    "lines": [
      { "line": "+15125550188" }
    ],
    "monthly_cents": 9900,
    "consent_text": "By getting an iMessage line, you confirm everyone you text agreed to hear from you.",
    "auto_add_max_lines": 5
  }
}

#Start an iMessage line purchase

Holds the first month, at your price (or your agency’s price), on the card on file. Nothing is taken from the card until Buy the line succeeds; a hold that is never used drops off after about 7 days. With no card on file you get a client_secret to confirm with Stripe.js instead. The same checks and payment as buying a line in the app. Send an Idempotency-Key header: a retry with the same key never holds twice. Needs the manage_phones permission.

Parameters

consent_attestedbooleanRequired: true agrees to consent_text from List your iMessage lines: everyone you text agreed to hear from you. Ready records the sentence, who agreed and when, as it does in the app.
blue_namestringRequired for your first line: The name people see for your first line, up to 60 characters. Left out, the call is refused with 400 order_details_invalid. Send it again on the buy call. An added line takes the first line’s name.

More parameters

consent_attestation_textstring: The sentence you showed. When sent, it must match consent_text exactly, or nothing is held.
blue_photostring: A JPEG or PNG data URL for your first line.
expected_linesintegerDefault 0: How many lines you have now. Send it to add another line; an added line keeps the first line’s name and photo.
auto_addboolean: true also turns on adding lines automatically; false turns it off. Leave it out to keep the current setting.
auto_add_max_linesinteger: With auto_add: true, the most lines it may add, 2 to 5 (your account already holds one, so 1 would add none).
checkout_idstring: Your own id for this purchase. A retry with the same id gets the same hold back.

Returns

data.authorized, amount, payment_intent_id, card_brand, card_last4: Card on file: amount cents are held. Send payment_intent_id to Buy the line.
data.client_secret, amount, has_card: No card, or the card needs a check: confirm with Stripe.js, then send the payment_intent_id (the part of client_secret before _secret_) to Buy the line.
data.freeboolean: Nothing to pay on this account. Buy the line with no payment_intent_id.

Errors

HTTP	Code	When
400	`idempotency_key_required`	No `Idempotency-Key` header. Nothing was held.
400	`consent_required`	`consent_attested` isn’t `true`, the sentence doesn’t match, or `auto_add_max_lines` is out of range.
400	`line_unavailable`	400 only: iMessage lines aren’t offered on your account yet, or this account is set up for testing only and can’t buy a real line.
409	`line_refused`	No iMessage line is free right now. Nothing held or charged. Try again later.
409, 503	`line_unavailable`	Our iMessage provider can’t sell a line right now. Nothing held or charged. Try again in a minute.
400	`line_limit`	`expected_lines` is out of range.
400	`order_details_invalid`	The name or photo was refused.
402	card code	The card was declined. Nothing was held.
403	`test_key_not_allowed`	A test key.
409	`lines_changed`	You have fewer lines than `expected_lines`. Read your lines and try again.
409	`purchase_in_progress`	An earlier attempt is still on file. Nothing was held twice.
502	`checkout_unconfirmed`	We couldn’t confirm the hold. Check your card before you try again.
503	`checkout_unavailable`, `billing_check_unavailable`, `line_check_unavailable`	Nothing was held. Retry in a minute.

curl -X POST "https://api.tryready.com/v1/imessage-lines/checkout" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "consent_attested": true,
    "blue_name": "Acme Dental",
    "checkout_id": "order-1042"
  }'

const res = await fetch('https://api.tryready.com/v1/imessage-lines/checkout', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "consent_attested": true,
    "blue_name": "Acme Dental",
    "checkout_id": "order-1042"
  }),
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.post(
    "https://api.tryready.com/v1/imessage-lines/checkout",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "consent_attested": True,
        "blue_name": "Acme Dental",
        "checkout_id": "order-1042"
    },
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": {
    "charged": false,
    "authorized": true,
    "line": "blue",
    "amount": 9900,
    "card_last4": "4242",
    "card_brand": "visa",
    "payment_intent_id": "pi_3QabcExample"
  }
}

#Buy an iMessage line

Sets the line up on your account and takes the first month held by Start a purchase; from then on the line bills monthly until you cancel it. If no line could be set up, the hold is released and you pay nothing. Send the same body you sent to start the purchase, plus payment_intent_id. Sending it again is safe: a purchase that finished answers already_owned and takes nothing more. Needs the manage_phones permission.

Parameters

payment_intent_idstring: From Start a purchase. Leave it out only when that answered free: true.
consent_attestedbooleanRequired: As on Start a purchase.
consent_attestation_text, blue_name, blue_photo, expected_lines, auto_add, auto_add_max_lines: As on Start a purchase.

Returns

data.line_numberstring: The new line’s phone number.
data.first_monthenum: charged (the held amount was taken), exempt or free.
data.imessage_onboolean: Whether iMessage is on. false means our team has been told and will switch it on.
data.already_ownedboolean: This purchase had already finished. Nothing more was taken.

Errors

HTTP	Code	When
400	`consent_required`, `line_unavailable`, `order_details_invalid`	As on Start a purchase. Nothing was bought.
409	`line_refused`	No iMessage line is free right now. Nothing bought or charged. Try again later.
409, 503	`line_unavailable`	Our iMessage provider can’t sell a line right now. Nothing bought or charged. Try again in a minute.
400	`payment_invalid`	That payment can’t pay for this line. Start the purchase again.
402	`payment_not_held`	The card hold isn’t confirmed yet. Nothing was bought. Confirm the payment with Stripe.js, then send Buy the line again.
403	`test_key_not_allowed`	A test key.
403	`consent_needs_customer`	`auto_add: true` from someone signed in as you. Only the account holder can turn it on.
409	`price_changed`	The price changed since you started. Start again.
500	`line_unconfirmed`	We couldn’t confirm the line. Read your lines in a minute before you try again; a retry never buys or takes a second month.
500	`line_save_failed`	The line is bought but not yet on your account. Don’t buy another; our team will finish it.

curl -X POST "https://api.tryready.com/v1/imessage-lines" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "consent_attested": true,
    "blue_name": "Acme Dental",
    "payment_intent_id": "pi_3QabcExample"
  }'

const res = await fetch('https://api.tryready.com/v1/imessage-lines', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "consent_attested": true,
    "blue_name": "Acme Dental",
    "payment_intent_id": "pi_3QabcExample"
  }),
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.post(
    "https://api.tryready.com/v1/imessage-lines",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "consent_attested": True,
        "blue_name": "Acme Dental",
        "payment_intent_id": "pi_3QabcExample"
    },
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": {
    "line": "blue",
    "line_number": "+15125550188",
    "first_month": "charged",
    "imessage_on": true,
    "note": "Your iMessage line is live."
  }
}

#Cancel an iMessage line

Stops the line’s monthly charge and takes it off your account, as Cancel iMessage line in the line’s ⋯ menu on Numbers does. When it’s your last line, iMessage goes off and your texts go out by SMS. Nothing is refunded for the current month. You can’t undo it. Needs the manage_phones permission.

Parameters

linestringRequired: The line’s phone number, from List your iMessage lines. Nothing is cancelled without it.

Returns

data.linestring: The cancelled line.
data.lines_leftinteger: Lines still on your account.

Errors

HTTP	Code	When
403	`test_key_not_allowed`	A test key.
400	`invalid_field`	You sent no `line`. Nothing was cancelled. Send the number to cancel, from List your iMessage lines.
404	`line_not_found`	No such line on your account, or it’s already cancelled.
500	no code	Not cancelled. Retry in a minute.

curl -X POST "https://api.tryready.com/v1/imessage-lines/cancel" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "line": "+15125550188"
  }'

const res = await fetch('https://api.tryready.com/v1/imessage-lines/cancel', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "line": "+15125550188"
  }),
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.post(
    "https://api.tryready.com/v1/imessage-lines/cancel",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "line": "+15125550188"
    },
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": {
    "line": "+15125550188",
    "lines_left": 0
  }
}

#Get adding lines automatically

Whether Ready adds an iMessage line for you when your account reaches the daily limit of 50 new people. Needs the view_billing permission.

Returns

data.onboolean: Whether it’s on.
data.max_linesinteger | null: The most lines it may add.
data.textstring | null: The exact terms you agreed to: the price, when a line is added and how to stop it.
data.price_changedboolean: The price changed since you agreed, so no line is added until you turn it on again.
data.offeredboolean: false when your agency pays for your account. It can’t be turned on then.

Errors

HTTP	Code	When
500	no code	We couldn’t read it. Retry.

curl "https://api.tryready.com/v1/imessage-lines/auto-add" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/imessage-lines/auto-add', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/imessage-lines/auto-add",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": {
    "on": false,
    "max_lines": null,
    "text": null,
    "price_changed": false,
    "offered": true
  }
}

#Set adding lines automatically

On: when your account reaches 50 new people in a day, Ready buys another iMessage line at your monthly line price and charges your saved card, up to max_lines lines. Turning it on records your agreement to those terms, as the app does. Nothing is charged by this call. Turning it off is always allowed. Needs the manage_billing permission.

Parameters

onbooleanRequired: Turn it on or off.
max_linesinteger: Required with on: true: the most lines it may add, 2 to 5 (your account already holds one, so 1 would add none).

Returns

The same fields as Get adding lines automatically.

Errors

HTTP	Code	When
400	no code	`max_lines` is missing or out of range.
403	`test_key_not_allowed`	A test key.
403	`agency_pays`	Your agency pays for your account, so there is nothing to turn on.
403	`consent_needs_customer`	Someone signed in as you. Only the account holder can turn it on.
500	no code	Not saved. Retry.

curl -X PUT "https://api.tryready.com/v1/imessage-lines/auto-add" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "on": true,
    "max_lines": 3
  }'

const res = await fetch('https://api.tryready.com/v1/imessage-lines/auto-add', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "on": true,
    "max_lines": 3
  }),
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.put(
    "https://api.tryready.com/v1/imessage-lines/auto-add",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "on": True,
        "max_lines": 3
    },
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": {
    "on": true,
    "max_lines": 3,
    "text": "…",
    "price_changed": false,
    "offered": true
  }
}

#Get iMessage status

Whether iMessage is on for your account. Buying an iMessage line turns it on (Start a purchase, then Buy the line). You can’t switch it on from this endpoint. Needs the view_billing permission.

Returns

data.configuredboolean: false when iMessage isn’t available on Ready yet. Then no other field is sent.
data.enabledboolean: Whether your account can send iMessages.
data.can_manageboolean: Whether the caller may switch it. false for every customer key.

Errors

HTTP	Code	When
500	no code	We couldn’t read the setting. This is a failure, not "off"; retry.

curl "https://api.tryready.com/billing/imessage" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/billing/imessage', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/billing/imessage",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": {
    "configured": true,
    "enabled": true,
    "can_manage": false
  }
}

#Get your iMessage line name and photo

The name and photo people see when your iMessage lines text them, as you last set them. data is null if you never set one.

Returns

data.namestring: The name people see.
data.photostring | null: The photo as a JPEG or PNG data URL (data:image/jpeg;base64,...), or null.

Errors

HTTP	Code	When
500	no code	We couldn’t read it. Retry.

curl "https://api.tryready.com/billing/imessage/profile" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/billing/imessage/profile', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/billing/imessage/profile",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": {
    "name": "Acme Dental",
    "photo": null
  }
}

#Set your iMessage line name and photo

Renames all your iMessage lines, and changes their photo when you send one. Leave the photo out to keep the current one. Nothing is charged. Needs the manage_phones permission. Test keys get 403 test_key_not_allowed.

Parameters

blue_namestringRequired: The name people see, up to 60 characters. Letters, digits, spaces and . , ' & ( ) ! + @ # / : -.
blue_photostring: A JPEG or PNG as a data URL (data:image/png;base64,...), up to 250,000 characters.

Returns

data.namestring: The saved name.
data.photostring | null: The saved photo, or null.
data.renamedinteger: How many lines were renamed.
data.skippedinteger: Lines set up by Ready support, which keep their name. Ask support to change those.

Errors

HTTP	Code	When
400	`invalid_field`	`blue_name` is missing or too long, or `blue_photo` is too long.
400	`unknown_field`	The body has a field other than `blue_name` and `blue_photo`.
400	`invalid_profile`	The name is blank or has a character we don’t take, or the photo isn’t a JPEG or PNG under 3 MB.
400	`profile_refused`	Our iMessage provider refused the name or photo. Try a shorter name or another photo.
404	`no_blue_line`	Your account has no iMessage line yet.
409	`name_set_by_support`	Your lines were set up by Ready support. Email support to change the name.
409	`shared_line_group`	Your line’s name is also used by a line on another account, so nothing changed. Email support and we’ll give your line its own name.
502	`line_unreadable`	We couldn’t read your line, so nothing changed. Retry.
502	`profile_unknown`	We didn’t hear back, so the change may not show yet. Save again in a minute.
503	`line_unavailable`	Names can’t be changed right now. Nothing changed.
503	`profile_unreadable`	We couldn’t read your current photo, and you sent no new one. Nothing changed.
500	no code	Not saved. Retry.

curl -X PUT "https://api.tryready.com/billing/imessage/profile" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "blue_name": "Acme Dental"
  }'

const res = await fetch('https://api.tryready.com/billing/imessage/profile', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "blue_name": "Acme Dental"
  }),
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.put(
    "https://api.tryready.com/billing/imessage/profile",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "blue_name": "Acme Dental"
    },
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": {
    "name": "Acme Dental",
    "photo": null,
    "renamed": 2,
    "skipped": 0
  }
}