Stytch OTP API

openapi: 3.2.0
info:
  title: Stytch Consumer Authentication OTP API
  version: 2.0.0
  description: Stytch's Consumer API for passwordless and password-based authentication. Supports Magic Links, SMS/email/WhatsApp OTP, OAuth social login, TOTP, WebAuthn/Passkeys, Crypto Wallets, Sessions, Users, M2M tokens, Fraud / Device Fingerprinting, Connected Apps (OAuth provider / MCP), Impersonation, IDP, and Consumer RBAC.
  contact:
    name: Stytch
    url: https://stytch.com/docs
  license:
    name: Proprietary
servers:
- url: https://api.stytch.com
  description: Production
- url: https://test.stytch.com
  description: Test
tags:
- name: OTP
paths:
  /v1/otps/authenticate:
    post:
      summary: Authenticate
      operationId: api_otp_v1_Authenticate
      tags:
      - OTP
      description: Authenticate a User given a `method_id` (the associated `email_id` or `phone_id`) and a `code`. This endpoint verifies that the code is valid, hasn't expired or been previously used, and any optional security settings such as IP match or user agent match are satisfied. A given `method_id` may only have a single active OTP code at any given time, if a User requests another OTP code before the first one has expired, the first one will be invalidated.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/api_otp_v1_AuthenticateRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_otp_v1_AuthenticateResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                status_code: 401
                request_id: request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141
                error_type: unauthorized_credentials
                error_message: Unauthorized credentials.
                error_url: https://stytch.com/docs/api/errors/401
        '429':
          description: Too Many Requests
          content:
            application/json:
              example:
                status_code: 429
                request_id: request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141
                error_type: too_many_requests
                error_message: Too many requests have been made.
                error_url: https://stytch.com/docs/api/errors/429
        '500':
          description: Internal server error
          content:
            application/json:
              example:
                status_code: 500
                request_id: request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141
                error_type: internal_server_error
                error_message: Oops, something seems to have gone wrong, please reach out to support@stytch.com to let us know what went wrong.
                error_url: https://stytch.com/docs/api/errors/500
      x-code-samples:
      - lang: csharp
        label: C#
        source: "// POST /v1/otps/authenticate\nconst stytch = require('stytch');\n\nconst client = new stytch.Client({\n  project_id: '${projectId}',\n  secret: '${secret}',\n});\n\nconst params = {\n  method_id: \"${phoneId}\",\n  code: \"${exampleCode}\",\n  session_duration_minutes: 60,\n};\n\nclient.OTPs.Authenticate(params)\n  .then(resp => { console.log(resp) })\n  .catch(err => { console.log(err) });"
      - lang: go
        label: Go
        source: "// POST /v1/otps/authenticate\npackage main\n\nimport (\n\t\"context\"\n\t\"log\"\n\n\t\"github.com/stytchauth/stytch-go/v17/stytch/consumer/otp\"\n\t\"github.com/stytchauth/stytch-go/v17/stytch/consumer/stytchapi\"\n)\n\nfunc main() {\n\tclient, err := stytchapi.NewClient(\n\t\t\"${projectId}\",\n\t\t\"${secret}\",\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"error instantiating client: %v\", err)\n\t}\n\n\tparams := &otp.AuthenticateParams{\n\t\tMethodID:               \"${phoneId}\",\n\t\tCode:                   \"${exampleCode}\",\n\t\tSessionDurationMinutes: 60,\n\t}\n\n\tresp, err := client.OTPs.Authenticate(context.Background(), params)\n\tif err != nil {\n\t\tlog.Fatalf(\"error in method call: %v\", err)\n\t}\n\n\tlog.Println(resp)\n}\n"
      - lang: java
        label: Java
        source: "// POST /v1/otps/authenticate\npackage com.example;\n\nimport com.stytch.java.common.StytchResult;\nimport com.stytch.java.consumer.models.otp.AuthenticateRequest;\nimport com.stytch.java.consumer.StytchClient;\n\npublic class Main {\n    public static void main(String[] args) {\n        StytchClient.configure(\"${projectId}\", \"${secret}\");\n\n        AuthenticateRequest params = new AuthenticateRequest();\n        params.setMethodId(\"${phoneId}\");\n        params.setCode(\"${exampleCode}\");\n        params.setSessionDurationMinutes(60);\n\n        Object result = StytchClient.getOTPs().authenticate(params);\n        if (result instanceof StytchResult.Success) {\n          System.out.println(((StytchResult.Success) result).getValue());\n        } else {\n          System.out.println(((StytchResult.Error) result).getException());\n        }\n    }\n}"
      - lang: kotlin
        label: Kotlin
        source: "// POST /v1/otps/authenticate\npackage com.example\n\nimport com.stytch.java.consumer.StytchClient\nimport com.stytch.java.consumer.models.otp.AuthenticateRequest\n\nfun main() {\n    StytchClient.configure(\n        projectId = \"${projectId}\",\n        secret = \"${secret}\",\n    )\n\n    when (\n        val result =\n            StytchClient.otps.authenticate(\n                AuthenticateRequest(\n                    methodId = \"${phoneId}\",\n                    code = \"${exampleCode}\",\n                    sessionDurationMinutes = 60,\n                ),\n            )\n    ) {\n        is StytchResult.Success -> println(result.value)\n        is StytchResult.Error -> println(result.exception)\n    }\n}\n"
      - lang: javascript
        label: Node.js
        source: "// POST /v1/otps/authenticate\nconst stytch = require('stytch');\n\nconst client = new stytch.Client({\n  project_id: '${projectId}',\n  secret: '${secret}',\n});\n\nconst params = {\n  method_id: \"${phoneId}\",\n  code: \"${exampleCode}\",\n  session_duration_minutes: 60,\n};\n\nclient.otps.authenticate(params)\n  .then(resp => { console.log(resp) })\n  .catch(err => { console.log(err) });"
      - lang: php
        label: PHP
        source: "$response = $client->otps->authenticate([\n    'method_id' => '${phoneId}',\n    'code' => '${exampleCode}',\n    'session_duration_minutes' => 60,\n]);"
      - lang: python
        label: Python
        source: "# POST /v1/otps/authenticate\nfrom stytch import Client\n\nclient = Client(\n    project_id=\"${projectId}\",\n    secret=\"${secret}\",\n)\n\nresp = client.otps.authenticate(\n    method_id=\"${phoneId}\",\n    code=\"${exampleCode}\",\n    session_duration_minutes=60,\n)\n\nprint(resp)\n"
      - lang: ruby
        label: Ruby
        source: "# POST /v1/otps/authenticate\nrequire 'stytch'\n\nclient = Stytch::Client.new(\n  project_id: \"${projectId}\",\n  secret: \"${secret}\"\n)\n\nresp = client.otps.authenticate(\n  method_id: \"${phoneId}\",\n  code: \"${exampleCode}\",\n  session_duration_minutes: 60\n  \n)\n\nputs resp"
      - lang: rust
        label: Rust
        source: "// POST /v1/otps/authenticate\nuse stytch::consumer::client::Client;\nuse stytch::consumer::otp::AuthenticateRequest;\n\nfn main() {\n    let client = Client::new(\"${projectId}\", \"${secret}\").unwrap();\n    let resp = client.otps.authenticate(\n        AuthenticateRequest{\n            method_id: \"${phoneId}\",\n            code: \"${exampleCode}\",\n            session_duration_minutes: 60,\n            ..Default::default()\n        }\n    ).await;\n    println!(\"The response is {:?}\", resp);\n}"
      - lang: bash
        label: cURL
        source: "# POST /v1/otps/authenticate\ncurl --request POST \\\n  --url https://test.stytch.com/v1/otps/authenticate \\\n  -u '${projectId}:${secret}' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"method_id\": \"${phoneId}\",\n    \"code\": \"${exampleCode}\",\n    \"session_duration_minutes\": 60\n  }'"
  /v1/otps/sms/send:
    post:
      summary: Send
      operationId: api_otp_v1_otp_sms_Send
      tags:
      - OTP
      description: '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`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/api_otp_v1_otp_sms_SendRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_otp_v1_otp_sms_SendResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                status_code: 401
                request_id: request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141
                error_type: unauthorized_credentials
                error_message: Unauthorized credentials.
                error_url: https://stytch.com/docs/api/errors/401
        '429':
          description: Too Many Requests
          content:
            application/json:
              example:
                status_code: 429
                request_id: request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141
                error_type: too_many_requests
                error_message: Too many requests have been made.
                error_url: https://stytch.com/docs/api/errors/429
        '500':
          description: Internal server error
          content:
            application/json:
              example:
                status_code: 500
                request_id: request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141
                error_type: internal_server_error
                error_message: Oops, something seems to have gone wrong, please reach out to support@stytch.com to let us know what went wrong.
                error_url: https://stytch.com/docs/api/errors/500
      x-code-samples:
      - lang: csharp
        label: C#
        source: "// POST /v1/otps/sms/send\nconst stytch = require('stytch');\n\nconst client = new stytch.Client({\n  project_id: '${projectId}',\n  secret: '${secret}',\n});\n\nconst params = {\n  phone_number: \"${examplePhoneNumber}\",\n};\n\nclient.OTPs.Sms.Send(params)\n  .then(resp => { console.log(resp) })\n  .catch(err => { console.log(err) });"
      - lang: go
        label: Go
        source: "// POST /v1/otps/sms/send\npackage main\n\nimport (\n\t\"context\"\n\t\"log\"\n\n\t\"github.com/stytchauth/stytch-go/v17/stytch/consumer/otp/sms\"\n\t\"github.com/stytchauth/stytch-go/v17/stytch/consumer/stytchapi\"\n)\n\nfunc main() {\n\tclient, err := stytchapi.NewClient(\n\t\t\"${projectId}\",\n\t\t\"${secret}\",\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"error instantiating client: %v\", err)\n\t}\n\n\tparams := &sms.SendParams{\n\t\tPhoneNumber: \"${examplePhoneNumber}\",\n\t}\n\n\tresp, err := client.OTPs.Sms.Send(context.Background(), params)\n\tif err != nil {\n\t\tlog.Fatalf(\"error in method call: %v\", err)\n\t}\n\n\tlog.Println(resp)\n}\n"
      - lang: java
        label: Java
        source: "// POST /v1/otps/sms/send\npackage com.example;\n\nimport com.stytch.java.common.StytchResult;\nimport com.stytch.java.consumer.models.otpsms.SendRequest;\nimport com.stytch.java.consumer.StytchClient;\n\npublic class Main {\n    public static void main(String[] args) {\n        StytchClient.configure(\"${projectId}\", \"${secret}\");\n\n        SendRequest params = new SendRequest();\n        params.setPhoneNumber(\"${examplePhoneNumber}\");\n\n        Object result = StytchClient.getOTPs().getSms().send(params);\n        if (result instanceof StytchResult.Success) {\n          System.out.println(((StytchResult.Success) result).getValue());\n        } else {\n          System.out.println(((StytchResult.Error) result).getException());\n        }\n    }\n}"
      - lang: kotlin
        label: Kotlin
        source: "// POST /v1/otps/sms/send\npackage com.example\n\nimport com.stytch.java.consumer.StytchClient\nimport com.stytch.java.consumer.models.otpsms.SendRequest\n\nfun main() {\n    StytchClient.configure(\n        projectId = \"${projectId}\",\n        secret = \"${secret}\",\n    )\n\n    when (\n        val result =\n            StytchClient.otps.sms.send(\n                SendRequest(\n                    phoneNumber = \"${examplePhoneNumber}\",\n                ),\n            )\n    ) {\n        is StytchResult.Success -> println(result.value)\n        is StytchResult.Error -> println(result.exception)\n    }\n}\n"
      - lang: javascript
        label: Node.js
        source: "// POST /v1/otps/sms/send\nconst stytch = require('stytch');\n\nconst client = new stytch.Client({\n  project_id: '${projectId}',\n  secret: '${secret}',\n});\n\nconst params = {\n  phone_number: \"${examplePhoneNumber}\",\n};\n\nclient.otps.sms.send(params)\n  .then(resp => { console.log(resp) })\n  .catch(err => { console.log(err) });"
      - lang: php
        label: PHP
        source: "$response = $client->otps->sms->send([\n    'phone_number' => '${examplePhoneNumber}',\n]);"
      - lang: python
        label: Python
        source: "# POST /v1/otps/sms/send\nfrom stytch import Client\n\nclient = Client(\n    project_id=\"${projectId}\",\n    secret=\"${secret}\",\n)\n\nresp = client.otps.sms.send(\n    phone_number=\"${examplePhoneNumber}\",\n)\n\nprint(resp)\n"
      - lang: ruby
        label: Ruby
        source: "# POST /v1/otps/sms/send\nrequire 'stytch'\n\nclient = Stytch::Client.new(\n  project_id: \"${projectId}\",\n  secret: \"${secret}\"\n)\n\nresp = client.otps.sms.send(\n  phone_number: \"${examplePhoneNumber}\"\n  \n)\n\nputs resp"
      - lang: rust
        label: Rust
        source: "// POST /v1/otps/sms/send\nuse stytch::consumer::client::Client;\nuse stytch::consumer::otp_sms::SendRequest;\n\nfn main() {\n    let client = Client::new(\"${projectId}\", \"${secret}\").unwrap();\n    let resp = client.otps.sms.send(\n        SendRequest{\n            phone_number: \"${examplePhoneNumber}\",\n            ..Default::default()\n        }\n    ).await;\n    println!(\"The response is {:?}\", resp);\n}"
      - lang: bash
        label: cURL
        source: "# POST /v1/otps/sms/send\ncurl --request POST \\\n  --url https://test.stytch.com/v1/otps/sms/send \\\n  -u '${projectId}:${secret}' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"phone_number\": \"${examplePhoneNumber}\"\n  }'"
  /v1/otps/sms/login_or_create:
    post:
      summary: Loginorcreate
      operationId: api_otp_v1_otp_sms_LoginOrCreate
      tags:
      - OTP
      description: 'Send a One-Time Passcode (OTP) to a User using their phone number. If the phone number is not associated with a user already, a user will be created.


        ### 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).


        ### 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`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/api_otp_v1_otp_sms_LoginOrCreateRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_otp_v1_otp_sms_LoginOrCreateResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                status_code: 401
                request_id: request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141
                error_type: unauthorized_credentials
                error_message: Unauthorized credentials.
                error_url: https://stytch.com/docs/api/errors/401
        '429':
          description: Too Many Requests
          content:
            application/json:
              example:
                status_code: 429
                request_id: request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141
                error_type: too_many_requests
                error_message: Too many requests have been made.
                error_url: https://stytch.com/docs/api/errors/429
        '500':
          description: Internal server error
          content:
            application/json:
              example:
                status_code: 500
                request_id: request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141
                error_type: internal_server_error
                error_message: Oops, something seems to have gone wrong, please reach out to support@stytch.com to let us know what went wrong.
                error_url: https://stytch.com/docs/api/errors/500
      x-code-samples:
      - lang: csharp
        label: C#
        source: "// POST /v1/otps/sms/login_or_create\nconst stytch = require('stytch');\n\nconst client = new stytch.Client({\n  project_id: '${projectId}',\n  secret: '${secret}',\n});\n\nconst params = {\n  phone_number: \"${examplePhoneNumber}\",\n};\n\nclient.OTPs.Sms.LoginOrCreate(params)\n  .then(resp => { console.log(resp) })\n  .catch(err => { console.log(err) });"
      - lang: go
        label: Go
        source: "// POST /v1/otps/sms/login_or_create\npackage main\n\nimport (\n\t\"context\"\n\t\"log\"\n\n\t\"github.com/stytchauth/stytch-go/v17/stytch/consumer/otp/sms\"\n\t\"github.com/stytchauth/stytch-go/v17/stytch/consumer/stytchapi\"\n)\n\nfunc main() {\n\tclient, err := stytchapi.NewClient(\n\t\t\"${projectId}\",\n\t\t\"${secret}\",\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"error instantiating client: %v\", err)\n\t}\n\n\tparams := &sms.LoginOrCreateParams{\n\t\tPhoneNumber: \"${examplePhoneNumber}\",\n\t}\n\n\tresp, err := client.OTPs.Sms.LoginOrCreate(context.Background(), params)\n\tif err != nil {\n\t\tlog.Fatalf(\"error in method call: %v\", err)\n\t}\n\n\tlog.Println(resp)\n}\n"
      - lang: java
        label: Java
        source: "// POST /v1/otps/sms/login_or_create\npackage com.example;\n\nimport com.stytch.java.common.StytchResult;\nimport com.stytch.java.consumer.models.otpsms.LoginOrCreateRequest;\nimport com.stytch.java.consumer.StytchClient;\n\npublic class Main {\n    public static void main(String[] args) {\n        StytchClient.configure(\"${projectId}\", \"${secret}\");\n\n        LoginOrCreateRequest params = new LoginOrCreateRequest();\n        params.setPhoneNumber(\"${examplePhoneNumber}\");\n\n        Object result = StytchClient.getOTPs().getSms().loginOrCreate(params);\n        if (result instanceof StytchResult.Success) {\n          System.out.println(((StytchResult.Success) result).getValue());\n        } else {\n          System.out.println(((StytchResult.Error) result).getException());\n        }\n    }\n}"
      - lang: kotlin
        label: Kotlin
        source: "// POST /v1/otps/sms/login_or_create\npackage com.example\n\nimport com.stytch.java.consumer.StytchClient\nimport com.stytch.java.consumer.models.otpsms.LoginOrCreateRequest\n\nfun main() {\n    StytchClient.configure(\n        projectId = \"${projectId}\",\n        secret = \"${secret}\",\n    )\n\n    when (\n        val result =\n            StytchClient.otps.sms.loginOrCreate(\n                LoginOrCreateRequest(\n                    phoneNumber = \"${examplePhoneNumber}\",\n                ),\n            )\n    ) {\n        is StytchResult.Success -> println(result.value)\n        is StytchResult.Error -> println(result.exception)\n    }\n}\n"
      - lang: javascript
        label: Node.js
        source: "// POST /v1/otps/sms/login_or_create\nconst stytch = require('stytch');\n\nconst client = new stytch.Client({\n  project_id: '${projectId}',\n  secret: '${secret}',\n});\n\nconst params = {\n  phone_number: \"${examplePhoneNumber}\",\n};\n\nclient.otps.sms.loginOrCreate(params)\n  .then(resp => { console.log(resp) })\n  .catch(err => { console.log(err) });"
      - lang: php
        label: PHP
        source: "$response = $client->otps->sms->login_or_create([\n    'phone_number' => '${examplePhoneNumber}',\n]);"
      - lang: python
        label: Python
        source: "# POST /v1/otps/sms/login_or_create\nfrom stytch import Client\n\nclient = Client(\n    project_id=\"${projectId}\",\n    secret=\"${secret}\",\n)\n\nresp = client.otps.sms.login_or_create(\n    phone_number=\"${examplePhoneNumber}\",\n)\n\nprint(resp)\n"
      - lang: ruby
        label: Ruby
        source: "# POST /v1/otps/sms/login_or_create\nrequire 'stytch'\n\nclient = Stytch::Client.new(\n  project_id: \"${projectId}\",\n  secret: \"${secret}\"\n)\n\nresp = client.otps.sms.login_or_create(\n  phone_number: \"${examplePhoneNumber}\"\n  \n)\n\nputs resp"
      - lang: rust
        label: Rust
        source: "// POST /v1/otps/sms/login_or_create\nuse stytch::consumer::client::Client;\nuse stytch::consumer::otp_sms::LoginOrCreateRequest;\n\nfn main() {\n    let client = Client::new(\"${projectId}\", \"${secret}\").unwrap();\n    let resp = client.otps.sms.login_or_create(\n        LoginOrCreateRequest{\n            phone_number: \"${examplePhoneNumber}\",\n            ..Default::default()\n        }\n    ).await;\n    println!(\"The response is {:?}\", resp);\n}"
      - lang: bash
        label: cURL
        source: "# POST /v1/otps/sms/login_or_create\ncurl --request POST \\\n  --url https://test.stytch.com/v1/otps/sms/login_or_create \\\n  -u '${projectId}:${secret}' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"phone_number\": \"${examplePhoneNumber}\"\n  }'"
  /v1/otps/whatsapp/send:
    post:
      summary: Send
      operationId: api_otp_v1_otp_whatsapp_Send
      tags:
      - OTP
      description: 'Send a One-Time Passcode (OTP) to a User''s WhatsApp. 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/whatsapp-login-or-create) 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).


        ### 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 WhatsApp 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`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/api_otp_v1_otp_whatsapp_SendRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_otp_v1_otp_whatsapp_SendResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                status_code: 401
                request_id: request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141
                error_type: unauthorized_credentials
                error_message: Unauthorized credentials.
                error_url: https://stytch.com/docs/api/errors/401
        '429':
          description: Too Many Requests
          content:
            application/json:
              example:
                status_code: 429
                request_id: request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141
                error_type: too_many_requests
                error_message: Too many requests have been made.
                error_url: https://stytch.com/docs/api/errors/429
        '500':
          description: Internal server error
          content:
            application/json:
              example:
                status_code: 500
                request_id: request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141
                error_type: internal_server_error
                error_message: Oops, something seems to have gone wrong, please reach out to support@stytch.com to let us know what went wrong.
                error_url: https://stytch.com/docs/api/errors/500
      x-code-samples:
      - lang: csharp
        label: C#
        source: "// POST /v1/otps/whatsapp/send\nconst stytch = require('stytch');\n\nconst client = new stytch.Client({\n  project_id: '${projectId}',\n  secret: '${secret}',\n});\n\nconst params = {\n  phone_number: \"${examplePhoneNumber}\",\n};\n\nclient.OTPs.WhatsApp.Send(params)\n  .then(resp => { console.log(resp) })\n  .catch(err => { console.log(err) });"
      - lang: go
        label: Go
        source: "// POST /v1/otps/whatsapp/send\npackage main\n\nimport (\n\t\"context\"\n\t\"log\"\n\n\t\"github.com/stytchauth/stytch-go/v17/stytch/consumer/otp/whatsapp\"\n\t\"github.com/stytchauth/stytch-go/v17/stytch/consumer/stytchapi\"\n)\n\nfunc main() {\n\tclient, err := stytchapi.NewClient(\n\t\t\"${projectId}\",\n\t\t\"${secret}\",\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"error instantiating client: %v\", err)\n\t}\n\n\tparams := &whatsapp.SendParams{\n\t\tPhoneNumber: \"${examplePhoneNumber}\",\n\t}\n\n\tresp, err := client.OTPs.WhatsApp.Send(context.Background(), params)\n\tif err != nil {\n\t\tlog.Fatalf(\"error in method call: %v\", err)\n\t}\n\n\tlog.Println(resp)\n}\n"
      - lang: java
        label: Java
        source: "// POST /v1/otps/whatsapp/send\npackage com.example;\n\nimport com.stytch.java.common.StytchResult;\nimport com.stytch.java.consumer.models.otpwhatsapp.SendRequest;\nimport com.stytch.java.consumer.StytchClient;\n\npublic class Main {\n    public static void main(String[] args) {\n        StytchClient.configure(\"${projectId}\", \"${secret}\");\n\n        SendRequest params = new SendRequest();\n        params.setPhoneNumber(\"${examplePhoneNumber}\");\n\n        Object result = StytchClient.getOTPs().getWhatsApp().send(params);\n        if (result instanceof StytchResult.Success) {\n          System.out.println(((StytchResult.Success) result).getValue());\n        } else {\n          System.out.println(((StytchResult.Error) result).getException());\n        }\n    }\n}"
      - lang: kotlin
        label: Kotlin
        source: "// POST /v1/otps/whatsapp/send\npackage com.example\n\nimport com.stytch.java.consumer.StytchClient\nimport com.stytch.java.consumer.models.otpwhatsapp.SendRequest\n\nfun main() {\n    StytchClient.configure(\n        projectId = \"${projectId}\",\n        secret = \"${secret}\",\n    )\n\n    when (\n        val result =\n            StytchClient.otps.whatsapp.send(\n                SendRequest(\n                    phoneNumber = \"${examplePhoneNumber}\",\n                ),\n            )\n    ) {\n        is StytchResult.Success -> println(result.value)\n        is StytchResult.Error -> println(result.exception)\n    }\n}\n"
      - lang: javascript
        label: Node.js
        source: "// POST /v1/otps/whatsapp/send\nconst stytch = require('stytch');\n\nconst client = new stytch.Client({\n  project_id: '${projectId}',\n  secret: '${secret}',\n});\n\nconst params = {\n  phone_number: \"${examplePhoneNumber}\",\n};\n\nclient.otps.whatsapp.send(params)\n  .then(resp => { console.log(resp) })\n  .catch(err => { console.log(err) });"
      - lang: php
        label: PHP
        source: "$response = $client->otps->whatsapp->send([\n    'phone_number' => '${examplePhoneNumber}',\n]);"
      - lang: python
        label: Python
        source: "# POST /v1/otps/whatsapp/send\nfrom stytch import Client\n\nclient = Client(\n    project_id=\"${projectId}\",\n    secret=\"${secret}\",\n)\n\nresp = client.otps.whatsapp.send(\n    phone_number=\"${examplePhoneNumber}\",\n)\n\nprint(resp)\n"
      - lang: ruby
        label: Ruby
        source: "# POST /v1/otps/whatsapp/send\nrequire 'stytch'\n\nclient = Stytch::Client.new(\n  project_id: \"${projectId}\",\n  secret: \"${secret}\"\n)\n\nresp = client.otps.whatsapp.send(\n  phone_number: \"${examplePhoneNumber}\"\n  \n)\n\nputs resp"
      - lang: rust
        label: Rust
        source: "// POST /v1/otps/whatsapp/send\nuse stytch::consumer::client::Client;\nuse stytch::consumer::otp_whatsapp::SendRequest;\n\nfn main() {\n    let client = 

# --- truncated at 32 KB (115 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stytch/refs/heads/main/openapi/stytch-otp-api-openapi.yml