Send SMS, Email Verification Code

POST 
/auth/v1/verification

API Description

Send SMS or email verification code API, used to send verification code to user's phone number or email, supports multiple scenarios such as login, registration, password recovery.

Input Requirements

Required Parameters

• target: Target for sending verification code (required, optional values: ANY, USER)
  • ANY: No restriction, send regardless of whether user exists
  • USER: Account must exist in system to send
  • NOT_USER: Account must not exist in system to send

Optional Parameters (Choose One)

• phone_number: Phone number (optional, valid domestic phone number, needs "+86 " prefix, e.g., "+86 15588665555")
• email: Email (optional, valid email address, format abc@xxx)

Request Header Parameters

• x-captcha-token: Verification code token (optional, obtained from Verify Image Verification Code API, required when API returns captcha_required error)

Prerequisites

• Need to enable phone number or email login on Cloud Development Platform
• Email login requires SMTP server configuration
• Phone number and email cannot be passed simultaneously, must choose one
• When API returns captcha_required error, need to complete image verification code verification first

Output Description

Successful Response

• verification_id: Verification code ID (required, used for subsequent verification API)
• expires_in: Expiration time (required, in seconds, default 600 seconds)
• is_user: Whether user exists (optional, true means registered, false or empty means not registered)

Request Examples

Send Email Verification Code Request Example

{
  "email": "user@example",
  "target": "ANY"
}

Send Phone Number Verification Code Request Example

{
  "phone_number": "+86 13800138000",
  "target": "ANY"
}

Send Verification Code to Existing User Request Example

{
  "email": "user@example",
  "target": "USER"
}

Response Examples

Send Success Response Example

{
  "verification_id": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJlIjoidG9wc29ud2FuZzE2M0AxNjMuY29tIiwiZXhwIjoxNzQ3OTc0MjUxLCJraWQiOiJmY2JlMzBlZC1mNTc3LTRhMDQtOWIyZi05YTI4ZTc0NjA5MzQiLCJwaiI6Imxvd2NvZGUtNWc5YWMyMHUyYTI3ZGE0NiIsInQiOiJBR055Y0hRT0F3NjN4MUhBIn0",
  "expires_in": 600,
  "is_user": true
}

Image Verification Code Required Response Example

{
  "error": "captcha_required",
  "error_code": 4028,
  "error_description": "Need to complete image verification code verification"
}

Phone Number Format Error Response Example

{
  "error": "invalid_phone_number",
  "error_code": 4001,
  "error_description": "Phone number format error, needs +86 prefix"
}

User Not Found Response Example

{
  "error": "user_not_found",
  "error_code": 4004,
  "error_description": "User does not exist"
}

Send Frequency Too High Response Example

{
  "error": "rate_limit_exceeded",
  "error_code": 4029,
  "error_description": "Verification code send frequency too high, please try again in 60 seconds"
}

Field Description

Request Parameters

Field Name	Type	Required	Description
target	string	Yes	Send target, optional values: ANY (no restriction), USER (user must exist)
phone_number	string	No	Phone number, format "+86 phone_number", choose one with email
email	string	No	Email address, choose one with phone_number
x-captcha-token	string	No	Image verification code token, passed in request header, required when API returns captcha_required error

Response Parameters

Field Name	Type	Required	Description
verification_id	string	Yes	Verification code ID, used for subsequent verification API
expires_in	integer	Yes	Expiration time, in seconds, default 600 seconds
is_user	boolean	No	Whether user exists, true means registered

Usage Flow

1. Determine if Image Verification Code is Needed

• Can call directly for first send
• If returns captcha_required error, need to complete image verification code verification first

2. Send Verification Code

• Call this API to send verification code
• Choose target parameter based on scenario
• Pass phone number or email

3. User Receives Verification Code

• User receives verification code in phone or email
• Verification code valid for 600 seconds (10 minutes)

4. Verify Verification Code

• Call Verify SMS, Email Verification Code API
• Pass verification_id and user input verification code
• Get verification_token

5. Subsequent Operations

• If is_user is true, use verification_token to call login API
• If is_user is false or empty, use verification_token to call registration API

Key Characteristics

Verification Code Characteristics

• Verification code length is 6 digits
• Valid for 600 seconds (10 minutes)
• Same phone number or email can only send once within 60 seconds
• Verification code becomes invalid immediately after use

Security

• Limit send frequency to prevent SMS bombing
• Support image verification code protection
• Record send logs
• Monitor abnormal send behavior

Usage Scenarios

Login Scenario (target=ANY)

• User logs in with phone number or email
• No restriction on whether user exists
• Suitable for login or registration flow

Password Recovery Scenario (target=USER)

• User forgets password
• Must be registered user
• Prevent user information leakage

Registration Scenario (target=ANY)

• User registers new account
• Must be unregistered user
• Prevent duplicate registration

Notes

Phone Number Format

• Must add "+86 " prefix
• Format example: "+86 13800138000"
• Does not support other country phone numbers

Email Format

• Must be valid email address
• Format example: "user@example"
• Supports common email service providers

Send Frequency Limit

• Same phone number or email can only send once within 60 seconds
• Same IP can send maximum 10 times per hour
• Need to wait after exceeding limit

Image Verification Code

• Require image verification code when abnormal send behavior detected
• Need to call image verification code API to complete verification first
• Pass captcha_token in request header after obtaining

Error Handling Strategy

• Friendly error messages
• Auto handle image verification code flow
• Implement send countdown
• Record error logs

Related APIs

• Verify SMS, Email Verification Code - Verify verification code
• Verify Image Verification Code - Get captcha_token
• Get Image Verification Code - Get image verification code
• User Login - Use verification_token to login
• User Registration - Use verification_token to register

Request

Header Parameters

x-captcha-token string

Verification code token, obtained from the image verification code interface, needs to be passed when the interface reports captcha_required

application/json

Body

phone_number Phone Number (string)

Valid domestic phone number, needs to be prefixed with "+86 ", e.g., "+86 15588665555"

email Email (string)

Valid email, format abc@xxx

target Target for sending verification code (string)required

Pass ANY, other optional values are USER (account must exist in the system)

Responses

200

Response Headers

application/json

Schema

Schema

verification_id Verification Code ID (string)

Used to pass to the verify SMS, email verification code /auth/v1/verification/verify interface for verification code verification

expires_in Verification code expiration time, in seconds (integer)
is_user User Exists (boolean)

Determine whether this phone number or email has been registered as a user, returns true if registered

Example (from schema)

{
  "verification_id": "string",
  "expires_in": 0,
  "is_user": true
}

Example

{
  "verification_id": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJlIjoidG9wc29ud2FuZzE2M0AxNjMuY29tIiwiZXhwIjoxNzQ3OTc0MjUxLCJraWQiOiJmY2JlMzBlZC1mNTc3LTRhMDQtOWIyZi05YTI4ZTc0NjA5MzQiLCJwaiI6Imxvd2NvZGUtNWc5YWMyMHUyYTI3ZGE0NiIsInQiOiJBR055Y0hRT0F3NjN4MUhBIn0",
  "expires_in": 600
}

Loading...