Your app should store one consent record per phone number and per purpose, holding who agreed, when, how, the exact wording they saw, and where they agreed. Ready doesn't keep that per-contact record for you. It records an attestation when you send, so the opt-in evidence has to live in your own database or CRM.

This post gives developers a schema to copy and adapt. It's engineering guidance, not legal advice. Compliance is the sender's responsibility, and your counsel decides what evidence your business needs. For the non-technical view of why records matter, read how to document SMS consent.

What Ready stores, and what it doesn't

Be precise about the split, because the schema depends on it.

When you send through the API and set consent_attested, Ready records the sender's attestation: who sent, to how many numbers, and when. That builds an audit trail of sends. It isn't a per-contact consent record. No recipient opt-in time, wording or page URL is stored, and a keyword reply doesn't create one either. (The one exception is a sign-up on a Ready-hosted opt-in page, which is stored per contact with the time, IP and exact wording. The customer has no download of those sign-ups: support@tryready.com can send a copy.)

Also, an API send without consent_attested still goes out today, with a warning, and leaves no attestation. So don't treat the flag as optional paperwork. It's your promise that the recipient agreed, and your own records are what back it.

The core table

Keep consent as its own table, not a boolean on the contact. A boolean can't tell you when, how or what the person agreed to, and it gets overwritten.

FieldTypeWhy it exists
iduuidStable reference for audits
contact_iduuidThe person in your CRM
phone_e164textThe exact number, in E.164
purposetextFor example marketing, reminders, account alerts
statustextgranted, revoked or expired
granted_attimestamptzWhen they agreed
revoked_attimestamptz, nullWhen they withdrew
sourcetextweb_form, paper, verbal, keyword, import
wording_iduuidPointer to the exact disclosure text
wording_snapshottextThe text itself, copied at capture time
page_urltext, nullWhere the form lived
ip_addressinet, nullNetwork origin for web captures
user_agenttext, nullBrowser detail for web captures
evidence_reftext, nullLink to a screenshot, recording or signed form
captured_bytextUser id, system or integration name

Store the phone number in E.164, as our post on E.164 formatting explains. Matching a consent row to a contact by a loosely formatted number is a classic way to lose the link.

Version your wording

The most useful field is the one people skip: the disclosure text itself. Consent applies to what the person was shown, so you need that text as of the day they agreed.

Keep a consent_wordings table with an id, the full text, an effective date and the form or flow it belongs to. When you change the disclosure, insert a new row; never edit an old one. Each consent row then points at the version it was captured under. Copying the text into the consent row as well costs a few hundred bytes and saves you if the wordings table is ever edited by mistake.

For wording that holds up at registration, see consent language that passes registration. Carriers review the same disclosure your forms show.

Make it append-only

Don't update rows to change status. Write events. A revocation is a new row or a new event, not an overwrite of the grant. That gives you a timeline: granted on one date, revoked on another, granted again after a fresh opt-in.

A simple approach is a consent_events table with contact_id, purpose, event_type (granted, revoked, reconfirmed), occurred_at, source and the evidence fields above. The current status is derived from the latest event per contact and purpose. Add a database rule or permission so application code can insert but not update or delete these rows.

Handle revocation as a first-class event

Opt-outs must flow into your table. Ready honors inbound STOP and blocks the number in the sub-account that received it. Clear phrases such as "please stop texting me" are caught too. But your consent table is separate, so your code should record the revocation when it learns of one, and stop enrolling that number in drip campaigns.

Two practical notes. First, GET /v1/opt-outs lists only opted-out contacts on this account. Add ?scope=all to include the Ban list, which holds a STOP from a deleted contact and a dialer do-not-call entry. Only a STOP held on another account of the same family needs the per-number check, so don't call the list a complete mirror. Second, before a send from another tool, or after a provider migration, check GET /v1/opt-outs/:phone for the number. Our post on syncing opt-outs across channels covers the wider design.

Re-consent matters too. A person who texted STOP and later fills out a fresh form is a new grant, with its own evidence, not a quiet flip of the old row.

Tie the send to the record

Gate every send on the consent table, then pass the attestation:

POST https://api.tryready.com/v1/messages
X-API-Key: <key>
Idempotency-Key: <a new UUID for each text>

{"to": "+12125550199", "body": "Your appointment is tomorrow at 10. Reply C to confirm.", "consent_attested": true}

The order matters. Look up the latest consent event for that number and purpose, send only if it's a live grant, and only then set consent_attested to true. Don't hard-code the flag to true in a shared helper. That turns a promise into a habit.

Store the Ready message id or your own send id against the consent row you relied on. When someone asks what you did, you can answer with one query instead of a week of digging.

Retention and access

Keep consent evidence for as long as you might need to defend a text, which is a question for your counsel rather than a number we can give you. Restrict who can read the IP and user agent columns, since they're personal data. If a contact deletes their account, decide up front whether you keep a minimal suppression record, because forgetting that a person opted out is its own risk.

Don't put health details in a consent record or a text body. Ready isn't HIPAA compliant and doesn't sign BAAs, so keep PHI such as diagnoses, medications and test results out of both.

A short implementation checklist

  1. Create consent_events and consent_wordings, append-only.
  2. Capture wording, source, time and, for web forms, page URL and IP on every grant.
  3. Gate sends on the latest event per number and purpose.
  4. Record revocations from inbound STOP and from your own UI.
  5. Set consent_attested only after step 3 passes.
  6. Test with a revoked contact and confirm nothing sends.

For related build guidance, see our conversation data model for CRM developers. To try the send, sign up and follow the API quickstart, then read the messages reference.