Skip to content
FacilydevelopersDashboard
Build with Facily
DocsREST APIsRecord Sms Consent
Search the full API reference Esc to close

Record Sms Consent

Tenants · REST API reference

Get support
POST/v1/tenants/{tenant_id}/sms-consent
Record an SMS consent that already happened.

Authentication

Bearer API key or Facily session, subject to permissions and facility scope.

Authentication and scope

Request example

Replace bracketed path values with real IDs from your environment. The body, where shown, is generated from the schema and uses illustrative values.

cURL
curl --request POST \
  --url 'https://api.staging.facily.ai/v1/tenants/<TENANT_ID>/sms-consent' \
  --header "Authorization: Bearer $FACILY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "attestation": false,
  "obtained_at": "2026-10-29T12:00:00Z",
  "source": "staff_in_person",
  "evidence_document_id": "00000000-0000-4000-8000-000000000001",
  "release_suppression": false
}'
An example for building your request, not an executed call. Check required fields, allowed values, and environment configuration before sending.

Parameters

tenant_idpath · stringrequired

Format: uuid

Request body

application/json · Required

attestationbooleanrequired

Must be true. The staff member states that they obtained this consent themselves, or are recording it from a document they have seen.

evidence_document_idstring | null

Document backing the consent. Required when source is signed_document, and must belong to this tenant or to one of its leases.

Format: uuid

Show evidence_document_id schema
string | null

Document backing the consent. Required when source is signed_document, and must belong to this tenant or to one of its leases.

Variant 1: string
string
Variant 2: null
null
obtained_atstringrequired

When the tenant gave consent. May not be in the future.

Format: date-time

release_suppressionboolean

Release an active SMS suppression on this number as part of recording the consent. Requires communication.configure -- overruling a carrier-honoured STOP is a separately permissioned decision.

Default: false

sourcestringrequired

How the consent was obtained. Deliberately excludes storedge_import and inbound_sms_start: an API caller must never be able to claim system provenance it did not earn.

Values: "staff_in_person", "staff_phone", "signed_document"

Responses

Expand a status to inspect its schema. Generated examples show structure and synthetic values.

200Successful Response
JSON · generated example
{
  "data": {
    "preferences": {
      "email_suppressed": false,
      "invoice_delivery": "string",
      "marketing_sms_opt_in_evidence_id": "00000000-0000-4000-8000-000000000001",
      "marketing_sms_opt_in_recorded_by": "00000000-0000-4000-8000-000000000001",
      "marketing_sms_opt_in_source": "string",
      "marketing_sms_opted_in_at": "2026-10-29T12:00:00Z",
      "marketing_sms_revoked_at": "2026-10-29T12:00:00Z",
      "preferred_channels": [
        "string"
      ],
      "sms_opt_in_evidence_id": "00000000-0000-4000-8000-000000000001",
      "sms_opt_in_recorded_by": "00000000-0000-4000-8000-000000000001",
      "sms_opt_in_source": "storedge_import",
      "sms_opted_in_at": "2026-10-29T12:00:00Z"
    },
    "sms_suppression_active": false,
    "consent_recorded_by_name": "string",
    "marketing_sms_blocked_reason": "string",
    "sms_blocked_reason": "string"
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

dataCommunicationPreferencesResponserequired
Show data schema
consent_recorded_by_namestring | null

Display name of the user who recorded the SMS consent, resolved from sms_opt_in_recorded_by. Null when there is no consent, when a system path recorded it, or when the id no longer resolves.

Show consent_recorded_by_name schema
string | null

Display name of the user who recorded the SMS consent, resolved from sms_opt_in_recorded_by. Null when there is no consent, when a system path recorded it, or when the id no longer resolves.

Variant 1: string
string
Variant 2: null
null
marketing_sms_blocked_reasonstring | null

Why a PROMOTIONAL text to this tenant would be refused, or null. One of `no_phone`, `sms_opted_out`, `marketing_sms_no_recorded_consent`, `marketing_sms_revoked`, `active-suppression`. Marketing SMS is not sent yet; this reports the consent that has accrued.

Show marketing_sms_blocked_reason schema
string | null

Why a PROMOTIONAL text to this tenant would be refused, or null. One of `no_phone`, `sms_opted_out`, `marketing_sms_no_recorded_consent`, `marketing_sms_revoked`, `active-suppression`. Marketing SMS is not sent yet; this reports the consent that has accrued.

Variant 1: string
string
Variant 2: null
null
preferencesTenantCommunicationPreferencesrequired

How one tenant has agreed to be contacted (design 6.4).

Show preferences schema
email_suppressedboolean

Default: false

invoice_deliverystring | null
Show invoice_delivery schema
string | null
Variant 1: string
string
Variant 2: null
null
marketing_sms_opt_in_evidence_idstring | null

Format: uuid

Show marketing_sms_opt_in_evidence_id schema
string | null
Variant 1: string
string
Variant 2: null
null
marketing_sms_opt_in_recorded_bystring | null

Format: uuid

Show marketing_sms_opt_in_recorded_by schema
string | null
Variant 1: string
string
Variant 2: null
null
marketing_sms_opt_in_sourcestring | null
Show marketing_sms_opt_in_source schema
string | null
Variant 1: string
string
Variant 2: null
null
marketing_sms_opted_in_atstring | null

Format: date-time

Show marketing_sms_opted_in_at schema
string | null
Variant 1: string
string
Variant 2: null
null
marketing_sms_revoked_atstring | null

Format: date-time

Show marketing_sms_revoked_at schema
string | null
Variant 1: string
string
Variant 2: null
null
preferred_channelsstring[]
Show preferred_channels schema
string
sms_opt_in_evidence_idstring | null

Format: uuid

Show sms_opt_in_evidence_id schema
string | null
Variant 1: string
string
Variant 2: null
null
sms_opt_in_recorded_bystring | null

Format: uuid

Show sms_opt_in_recorded_by schema
string | null
Variant 1: string
string
Variant 2: null
null
sms_opt_in_sourcestring | null

Values: "storedge_import", "staff_in_person", "staff_phone", "signed_document", "inbound_sms_start", "web_form", "partner"

Show sms_opt_in_source schema
string | null
Variant 1: string
string

Values: "storedge_import", "staff_in_person", "staff_phone", "signed_document", "inbound_sms_start", "web_form", "partner"

Variant 2: null
null
sms_opted_in_atstring | null

Format: date-time

Show sms_opted_in_at schema
string | null
Variant 1: string
string
Variant 2: null
null
sms_opted_outboolean

Default: false

sms_blocked_reasonstring | null

Why an SMS to this tenant would be refused today, or null if it would not be. One of `no_phone`, `sms_opted_out`, `sms_no_recorded_consent`, `active-suppression`, reported in the order the send path would hit them. A preference for SMS does not override this.

Show sms_blocked_reason schema
string | null

Why an SMS to this tenant would be refused today, or null if it would not be. One of `no_phone`, `sms_opted_out`, `sms_no_recorded_consent`, `active-suppression`, reported in the order the send path would hit them. A preference for SMS does not override this.

Variant 1: string
string
Variant 2: null
null
sms_suppression_activebooleanrequired

Whether this tenant's number carries an active platform-wide SMS suppression. Its only other source is the org-wide suppression list, which needs communication.configure.

metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
400Validation error
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
401Unauthenticated
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
403Permission denied
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
404Not found
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
409Business logic error
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
503Temporary failure
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
Continue exploringAll tenants operations
Build something that works beautifully.

Facily API · Contract v1.200 · Reviewed October 29, 2026

Record Sms Consent | Facily Developers