---
title: "Send"
method: POST
path: "/v1/otps/sms/send"
tags: ["Otp"]
---

# Send

`POST /v1/otps/sms/send`

## Request

- Base URL: `https://api.stytch.com`
- URL: `https://api.stytch.com/v1/otps/sms/send`
- Auth: HTTP basic

Send a one-time passcode (OTP) to a user's phone number. If you'd like to create a user and send them a passcode with one request, use our [log in or create](https://stytch.com/docs/api/log-in-or-create-user-by-sms) endpoint.

Note that sending another OTP code before the first has expired will invalidate the first code.

### Cost to send SMS OTP
Before configuring SMS or WhatsApp OTPs, please review how Stytch [bills the costs of international OTPs](https://stytch.com/pricing) and understand how to protect your app against [toll fraud](https://stytch.com/docs/guides/passcodes/toll-fraud/overview).

__Note:__ SMS to phone numbers outside of the US and Canada is disabled by default for customers who did not use SMS prior to October 2023. If you're interested in sending international SMS, please add those countries to your Project's allowlist via the [Dashboard](https://stytch.com/dashboard/country-code-allowlists) or [Programmatic Workspace Actions](https://stytch.com/docs/workspace-management/pwa/set-allowed-country-codes), and [add credit card details](https://stytch.com/dashboard/settings/billing) to your account.

Even when international SMS is enabled, we do not support sending SMS to countries on our [Unsupported countries list](https://stytch.com/docs/guides/passcodes/unsupported-countries).

### Add a phone number to an existing user

This endpoint also allows you to add a new phone number to an existing Stytch User. Including a `user_id`, `session_token`, or `session_jwt` in your Send one-time passcode by SMS request will add the new, unverified phone number to the existing Stytch User. If the user successfully authenticates within 5 minutes, the new phone number will be marked as verified and remain permanently on the existing Stytch User. Otherwise, it will be removed from the User object, and any subsequent login requests using that phone number will create a new User.

### Next steps

Collect the OTP which was delivered to the user. Call [Authenticate OTP](https://stytch.com/docs/api/authenticate-otp) using the OTP `code` along with the `phone_id` found in the response as the `method_id`.

## Request body

- ApiOtpV1OtpSmsSendRequest: Request type
  - `phone_number` string, required: The phone number to use for one-time passcodes. The phone number should be in E.164 format (i.e. +1XXXXXXXXXX). You may use +10000000000 to test this endpoint, see [Testing](https://stytch.com/docs/home#resources_testing) for more detail.
  - `expiration_minutes` integer: Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes.
  - `attributes` ApiAttributeV1Attributes
    - `ip_address` string: The IP address of the user.
    - `user_agent` string: The user agent of the User.
  - `locale` 'en' | 'es' | 'pt-br' | 'fr' | 'it' | 'de-DE' | 'zh-Hans' | 'ca-ES' | 'ja' | 'ru' | 'nl' | 'pl' | 'tr' | 'fa' | 'vi' | 'cs'
  - `user_id` string: The unique ID of a specific User. You may use an `external_id` here if one is set for the user.
  - `session_token` string: The `session_token` associated with a User's existing Session.
  - `session_jwt` string: The `session_jwt` associated with a User's existing Session.

## Response `200`

Successful response

- ApiOtpV1OtpSmsSendResponse
  - `request_id` string, required: Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.
  - `user_id` string, required: The unique ID of the affected User.
  - `phone_id` string, required: The unique ID for the phone number.
  - `status_code` integer, required: The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `429`: Too Many Requests
- `500`: Internal server error

## Changes

- **2026-06-24** `53efe07dcf8f`: 12 info
  - added the new `ca-ES` enum value to the request property `locale`
  - added the new `cs` enum value to the request property `locale`
  - added the new `de-DE` enum value to the request property `locale`
  - added the new `fa` enum value to the request property `locale`
  - …8 more
- **2026-03-07** `110f26a94e5b`: 1 info
  - endpoint added
- **2026-03-06** `9cab20b8eca7`: 1 breaking
  - api path removed without deprecation
- **2025-10-23** `4a2e3c0c0c05`: 2 breaking, 3 warning, 1 info
  - added the new required request property `phone_number`
  - removed the required property `email_id` from the response with the `200` status
  - removed the request property `email`
  - removed the request property `login_template_id`
  - …2 more
- **2025-09-17** `8270cf3a3d4c`: 3 info
  - added the media type `application/json` for the response with the status `401`
  - added the media type `application/json` for the response with the status `500`
  - added the non-success response with the status `429`

[Operation history](https://skmtc.dev/stytch/apis/stytch-api/changes/v1/otps/sms/send/post.md)

---

[API](https://skmtc.dev/stytch/apis/stytch-api.md) - [All operations](https://skmtc.dev/stytch/apis/stytch-api/llms.txt) - [OpenAPI document](https://skmtc.dev/stytch/apis/stytch-api/revisions/6d1ff7474803?raw)