Registration changes

#Add another campaign

Adds a second campaign with a different use case. Your registration already includes one. Consent is given once, on the brand. No setup fee; billed monthly at your price from submission, first 30 days included. Don’t retry after a timeout: poll GET /v1/registration first. Needs the manage_brands permission.

Parameters

campaign_namestringDefault <business name> Campaign
use_caseenumRequired: One of the use cases, case-insensitive.
brand_idinteger: The brand’s registration_id. Send it when the brand is already approved so the campaign goes straight to review. Without it the campaign waits as awaiting_brand and is filed by itself within about 30 minutes of your account having an approved brand.
campaign_descriptionstring: Leave blank: Ready writes it from your use_case and business name.

Errors

HTTP	Code	When
400	`invalid_request`	Missing `use_case`.
400	`brand_required_first`	No brand yet (one awaiting payment counts).
400	`invalid_use_case`	`valid` lists them.
409	`duplicate_use_case`	Use case taken (`existing_reg_id`, `existing_campaign_name`). The campaign filed with your brand has the brand’s `use_case`, or `MIXED` if you sent none.
429	`duplicate_submission`	Repeat within 2 minutes.

curl -X POST "https://api.tryready.com/v1/registration/campaign" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_name": "Appointment reminders",
    "use_case": "ACCOUNT_NOTIFICATIONS",
    "brand_id": 481
  }'

const res = await fetch('https://api.tryready.com/v1/registration/campaign', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "campaign_name": "Appointment reminders",
    "use_case": "ACCOUNT_NOTIFICATIONS",
    "brand_id": 481
  }),
});
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/registration/campaign",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "campaign_name": "Appointment reminders",
        "use_case": "ACCOUNT_NOTIFICATIONS",
        "brand_id": 481
    },
    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": true,
    "amount": 0,
    "zero_fee": true,
    "registration_id": 482
  }
}

#Confirm a payment

After Stripe.js confirms a client_secret, this submits the registration now. Safe to call twice. Needs the manage_brands permission.

Parameters

payment_intent_idstringRequired: The part of client_secret before _secret_.

Errors

HTTP	Code	When
202	`payment_processing`	Still processing; retry shortly.
400	`payment_intent_id_required`	No `payment_intent_id`.
400	`payment_not_completed`	Payment failed (`status`).
403	`payment_owner_mismatch`	The payment is for another registration.
404	`payment_not_found`	No such payment.
404	`registration_not_found`	Paid, but no registration of yours matches it. Support has been told; don’t pay again.
409	`payment_refunded`	The payment was refunded. Start a new one.
500	`filing_failed`	Not filed yet. Retry; you won’t be charged again.
503	`payment_receipt_unavailable`, `registration_claim_unconfirmed`	Couldn’t confirm. Don’t pay again; retry in a minute.
503	`payment_check_unavailable`	Couldn’t check the payment. Retry.
503	`payments_unavailable`	Payments down. Retry later.

curl -X POST "https://api.tryready.com/v1/registration/confirm" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_intent_id": "pi_3Q8aZx2eZvKYlo2C0a1b2c3d"
  }'

const res = await fetch('https://api.tryready.com/v1/registration/confirm', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "payment_intent_id": "pi_3Q8aZx2eZvKYlo2C0a1b2c3d"
  }),
});
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/registration/confirm",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "payment_intent_id": "pi_3Q8aZx2eZvKYlo2C0a1b2c3d"
    },
    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,
  "registration_id": 481,
  "type": "brand"
}

{
  "success": true,
  "already_processed": true,
  "registration_id": 481
}

#Resubmit a registration

Resubmits a rejected registration, optionally with corrected fields. Needs the manage_brands permission.

Parameters

idinteger · pathRequired: The rejected registration’s id: the brand.id or campaign.id from GET /v1/registration, not a carrier id.
Idempotency-Keystring · header: Recommended. Resubmitting deregisters and re-registers with the carrier.
fieldsobject: Corrections. Only these keys apply: company_name, dba, ein, website, industry, entity_type, use_cases, campaign_description, street, city, state, zip, email, phone, first_name, last_name, sample_message_1, sample_message_2, optin_text. Others, and empty strings, are ignored. sample_message_1, sample_message_2 and optin_text apply to a campaign only: they are filed in place of the sample messages and opt-in description Ready writes for you. Ready adds your business name and the HELP and STOP line to each sample message. On a US brand, a new company_name or ein is checked against IRS records first; set ein_override to true to submit a brand-new EIN the IRS doesn’t list yet. A brand resubmit is filed with the carriers as a new brand, so any vetting the old brand had does not carry over.

Errors

HTTP	Code	When
400	`invalid_field`	`fields` isn’t an object.
400	`invalid_id`	The path id isn’t a valid registration id.
400	`invalid_fix`	A correction is over 500 characters, a sample message is too long once Ready adds your business name and the HELP and STOP line, or the EIN isn’t valid. Nothing changed; `error` says what to fix.
400	`ein_name_mismatch`	The corrected business name or EIN doesn’t match IRS records. Nothing changed; `ein_check` says which one is likely wrong and whether `ein_override` may submit it anyway.
404	`not_rejected`	Not rejected.
500	`resubmit_unconfirmed`	Don’t resubmit yet; poll `GET /v1/registration`.
502	`carrier_refused`, `missing_details`, `missing_website`, `not_saved`, `not_sent`, `state_changed`, `protected_registration`, `reconciliation_required`	Not sent to the carriers; `error` says what to do.

curl -X POST "https://api.tryready.com/v1/registration/482/resubmit" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "campaign_description": "Appointment reminders for patients who opted in at the front desk."
    }
  }'

const res = await fetch('https://api.tryready.com/v1/registration/482/resubmit', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "fields": {
      "campaign_description": "Appointment reminders for patients who opted in at the front desk."
    }
  }),
});
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, uuid, requests

r = requests.post(
    "https://api.tryready.com/v1/registration/482/resubmit",
    headers={"X-API-Key": os.environ["READY_API_KEY"], "Idempotency-Key": str(uuid.uuid4())},
    json={
        "fields": {
            "campaign_description": "Appointment reminders for patients who opted in at the front desk."
        }
    },
    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,
  "reg_id": 482,
  "type": "campaign",
  "status": "pending",
  "submit": {
    "ok": true,
    "status": "resubmitted"
  },
  "message": "…"
}

#Rename a registration

A Ready dashboard label; nothing changes with the carriers. Needs the manage_brands permission.

Parameters

idinteger · pathRequired: The registration id.
namestringRequired: Up to 80 characters; longer is cut. GET /v1/registration returns it as name in data.registrations[]; data.campaign.name stays the carrier campaign name.

Errors

HTTP	Code	When
400	`name_required`	`name` is missing.
404	`registration_not_found`	No registration with this id.

curl -X PUT "https://api.tryready.com/v1/registration/482/name" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Reminders (main office)"
  }'

const res = await fetch('https://api.tryready.com/v1/registration/482/name', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Reminders (main office)"
  }),
});
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/registration/482/name",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "name": "Reminders (main office)"
    },
    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": {
    "id": 482,
    "display_name": "Reminders (main office)"
  }
}

#Cancel a registration

Cancels a registration that isn’t approved yet and stops its monthly fee. This can’t be undone: what you already paid isn’t refunded, and to register again you file and pay again. To stop an approved one, use Turn off a registration. Needs the manage_brands permission and a key of the registration’s own account (its owner or an admin seat) or of its agency.

Parameters

idinteger · pathRequired: The registration id.

Returns { "success": true }.

Errors

HTTP	Code	When
400	`registration_approved`	Approved. Turn it off with POST /v1/registration/:id/deregister instead.
403	`owner_only`	The key isn’t the registration account’s owner, an admin seat there, or its agency.
404	`registration_not_found`	No registration with this id.
409	`registration_changed`	Status just changed; nothing removed.
502	`subscription_cancel_failed`	We couldn’t confirm the monthly fee stopped.

curl -X DELETE "https://api.tryready.com/v1/registration/482" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/registration/482', {
  method: 'DELETE',
  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.delete(
    "https://api.tryready.com/v1/registration/482",
    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
}

#Edit a registration

Changes the details of a registration before it’s filed with the carriers. Once the carriers have it, this answers 409: fix a rejected one with Resubmit. Needs the manage_brands permission and a key of the registration’s own account (its owner or an admin seat) or of its agency.

Path parameters

idintegerRequired: The registration id.

Body parameters

<field>stringRequired: One or more of company_name, dba, campaign_name, campaign_description, website, industry, street, city, state, zip, email, phone, first_name, last_name. Other fields are ignored.

Errors

HTTP	Code	When
400	`no_editable_fields`	None of the fields above in the body.
403	`owner_only`	The key isn’t the registration account’s owner, an admin seat there, or its agency.
404	`registration_not_found`	No registration with this id.
409	`registration_locked`	It’s already with the carriers, or changed while you were editing.
409	`registration_rejected`	It was rejected. Resubmit it instead.
500	`edit_failed`	Nothing was saved. Try again in a minute.

curl -X PATCH "https://api.tryready.com/v1/registration/482" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "website": "https://acmemotors.example",
    "zip": "80202"
  }'

const res = await fetch('https://api.tryready.com/v1/registration/482', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "website": "https://acmemotors.example",
    "zip": "80202"
  }),
});
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.patch(
    "https://api.tryready.com/v1/registration/482",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "website": "https://acmemotors.example",
        "zip": "80202"
    },
    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
}

#Turn off a registration

Stops an approved brand or campaign at the carriers. Its monthly fee stops first; if Ready can’t stop the fee, nothing is turned off. Your numbers stay on your account and keep their monthly fee, and can go on a new registration. Call it once with dry_run to see the name to confirm, then again with dry_run: false and that name. Send an Idempotency-Key header so a retry gets the first answer. Needs the manage_brands permission and a key of the registration’s own account (its owner or an admin seat) or of its agency.

Path parameters

idintegerRequired: The registration id.

Body parameters

dry_runboolean: Leave it out or send true to change nothing and get data.name and data.numbers (how many numbers are on it). false turns it off.
confirm_namestring: Required with dry_run: false: the data.name from the dry run, any case.

Returns

dry_runboolean: true on a dry run.
dataobject: On a dry run, { name, numbers }.

Errors

HTTP	Code	When
400	`registration_not_approved`	It isn’t approved. Cancel it with DELETE /v1/registration/:id.
400	`confirm_name_mismatch`	`confirm_name` doesn’t match the business name.
400	`nothing_to_deregister`	It isn’t linked to the carriers. Contact support.
403	`owner_only`	The key isn’t the registration account’s owner, an admin seat there, or its agency.
404	`registration_not_found`	No registration with this id.
409	`tcr_direct_registration`	Ready can’t turn this one off for you. Contact support.
502	`subscription_cancel_failed`	The monthly fee didn’t stop, so nothing was turned off. Try again in a minute.
502	`deregister_partial`	The fee is stopped, but the carriers didn’t confirm every step. Ready’s team is finishing it.

curl -X POST "https://api.tryready.com/v1/registration/481/deregister" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dry_run": true
  }'

const res = await fetch('https://api.tryready.com/v1/registration/481/deregister', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "dry_run": true
  }),
});
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/registration/481/deregister",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "dry_run": True
    },
    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,
  "dry_run": true,
  "data": {
    "name": "Acme Motors",
    "numbers": 3
  }
}

#Move a registration to a sub-account

Moves a registration, approved or still in review, to one of your own sub-accounts. The rest of its brand moves with it (the brand and every campaign under it), and with move_numbers the numbers sending on those campaigns move too. There is no charge and the monthly fees don’t change. Only a sub-account directly under the key’s account can receive it; any other account answers 404. A registration moved to a sub-account can’t be moved back to your own account through the API or the dashboard; contact support to undo a move. Needs the manage_brands permission and a key of the registration’s own account (its owner or an admin seat) or of its agency. Test keys can’t move registrations.

Path parameters

idintegerRequired: The registration id, a brand or a campaign.

Body parameters

target_user_idinteger: The sub-account to move it to, its id from GET /v1/sub-accounts. Send this or target_account_name.
target_account_namestring: The sub-account’s exact company name (case aside). A partial name is refused with 409 target_not_exact and the names that contain it, and if more than one has the name you get 409 target_ambiguous; send the id instead.
move_numbersboolean: true to move the numbers on these campaigns as well. Left out, they stay on your account.

Returns

data.transferred_tostring: The sub-account’s company name.
data.registrations_movedinteger: How many registrations moved, this one and the rest of its brand.
data.numbers_movedinteger: How many numbers moved.
data.ghl_relinkedinteger: How many moved numbers were relinked to the sub-account’s GoHighLevel location.

Once it has moved, calling it again answers 404, so a retry never moves it twice.

Errors

HTTP	Code	When
400	`target_required`	Neither `target_user_id` nor `target_account_name` was sent.
403	`owner_only`	The key isn’t the registration account’s owner, an admin seat there, or its agency.
403	`test_key_not_allowed`	A test key. Use a live key.
404	`registration_not_found`	No registration with this id in your account, or it has already moved.
404	`target_not_found`	The target isn’t a sub-account directly under the key’s account. Nothing moved.
409	`target_not_exact`	No sub-account has exactly that company name; the message lists the names that contain it. Nothing moved. Send the full name or `target_user_id`.
409	`target_ambiguous`	More than one sub-account has that name. Send `target_user_id`.
409	`registration_changed`	It was just moved by someone else. Nothing moved again.
429	`rate_limited`	Too many of these in a short time. Wait and try again.
500	`transfer_failed`	Nothing moved. Try again in a minute.

curl -X PUT "https://api.tryready.com/v1/registration/481/transfer" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_user_id": 90412,
    "move_numbers": true
  }'

const res = await fetch('https://api.tryready.com/v1/registration/481/transfer', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "target_user_id": 90412,
    "move_numbers": true
  }),
});
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/registration/481/transfer",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "target_user_id": 90412,
        "move_numbers": True
    },
    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": {
    "transferred_to": "Smith Roofing",
    "registrations_moved": 3,
    "numbers_moved": 2,
    "ghl_relinked": 0
  }
}