---
title: "Update SMS preferences"
method: PUT
path: "/users/sms-preferences"
tags: ["Users", "SmsPreferences"]
---

# Update SMS preferences

`PUT /users/sms-preferences`

## Request

- Base URL: `https://api.purplegrain.com/api/v1`
- URL: `https://api.purplegrain.com/api/v1/users/sms-preferences`
- Auth: HTTP bearer

Turns SMS to the current user's account on or off — the in-app equivalent
of replying **STOP** to a message.

Applies to every number on the account (the canonical `mobile` and any
`contact_info.mobile`), and is stored against the number rather than the
account, so it also silences messages sent to that number in another
context.

Opting out silences notifications and any marketing message. It does
**not** silence one-time verification codes: those are requested by the
user in the moment, and blocking them would lock the account out of
phone sign-in.

Acts on the authenticated user only — there is no id in the path. Call
this only when the person explicitly asks to turn SMS on or off.

## Request body

- object
  - `sms_opted_out` boolean, required: `true` silences SMS to this account, `false` re-enables it. Required — an absent or non-boolean value is rejected rather than treated as "no change".

## Response `200`

The updated user, with the new `sms_opted_out` value.

- UsersShowResponseAttributes
  - `data` UserModelAttributes: User in attributes-adapter shape (Accept application/json); fields at top level.
    - `id` string
    - `type` string
    - `email` string, email
    - `name` string, nullable
    - `about` string, nullable
    - `account_mode` 'grower' | 'contractor', nullable: Grower vs Contractor mode; only present for the current user.
    - `default_record_mode` 'ai' | 'general': Which record type the composer opens on: `ai` (PurpleGrain AI, the default) or `general`. Only present for the current user. A null value is ignored on update.
    - `free_trial_used` boolean, nullable: Whether the free trial has been used. Only populated when viewing your own profile; null otherwise.
    - `mobile` string, nullable: Canonical login mobile (E.164); only present for the current user.
    - `mobile_verified` boolean, nullable: Whether the mobile has been verified by SMS one-time code; only present for the current user.
    - `sms_opted_out` boolean, nullable: Whether SMS to this account is silenced (by replying STOP, or from the account screen); only present for the current user.
    - `handle` string
    - `url` string
    - `avatar_url` string, nullable
    - `avatar_thumb_url` string, nullable
    - `updated_at` string, date-time
    - `created_at` string, date-time
    - `contact_info` object
      - `mobile` string, nullable
      - `phone` string, nullable
      - `facebook` string, nullable
      - `url` string, nullable
      - `email` boolean, nullable
    - `city` object: Inlined when include=city
    - `place` object: Inlined when include=place
    - `services` unknown[], nullable: Inlined when include=services
      - unknown
    - `location` object: Inlined when include=location

## Other responses

- `400`: `sms_opted_out` was missing or not a boolean.
- `401`: Not authenticated.

---

[API](https://skmtc.dev/purplegrain/apis/purple-grain-api.md) · [All operations](https://skmtc.dev/purplegrain/apis/purple-grain-api/llms.txt) · [OpenAPI document](https://skmtc.dev/purplegrain/apis/purple-grain-api/revisions/4bedbc1c784c?raw)