sinch-verification-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sinch Verification API

Overview

概述

The Sinch Verification API verifies phone numbers through SMS OTP, Flashcall (missed call CLI), Phone Call (spoken OTP), Data (carrier-level), and WhatsApp OTP. Used for registration, 2FA, and number ownership confirmation.

Base URL:

https://verification.api.sinch.com

URL path prefix:

/verification/v1/

Auth: Application Key + Secret (NOT project-level OAuth2 — see Authentication Guide)

Sinch Verification API支持通过SMS OTP、Flashcall（未接来电CLI）、语音电话（语音播报OTP）、数据（运营商级）以及WhatsApp OTP方式验证手机号，可用于注册、2FA和号码归属确认场景。

基础URL：

https://verification.api.sinch.com

URL路径前缀：

/verification/v1/

身份验证： 应用密钥+应用密码（不是项目级OAuth2——详见《身份验证指南》Authentication Guide）

Agent Instructions

Agent使用说明

Before generating code, you MUST ask the user:

Which verification method? —
```
sms
```
,
```
flashcall
```
,
```
callout
```
,
```
seamless
```
, or
```
whatsapp
```
SDK or direct HTTP? — If SDK, which language?

Do not assume defaults or skip these questions. Wait for answers before generating code.

For SDK syntax, fetch the appropriate reference:

For direct HTTP, use the API Reference (Markdown) for request/response schemas.

在生成代码前，必须询问用户以下信息：

选择哪种验证方式？ —
```
sms
```
、
```
flashcall
```
、
```
callout
```
、
```
seamless
```
或
```
whatsapp
```
使用SDK还是直接调用HTTP？ — 如果使用SDK，说明具体语言？

请勿默认选项或跳过这些问题，需等待用户答复后再生成代码。

如需SDK语法，可参考对应语言的参考文档：

如果直接调用HTTP，请参考API参考文档（Markdown）中的请求/响应 schema。

Getting Started

快速入门

Authentication

身份验证

See sinch-authentication skill for dashboard setup.

The Verification API uses Application Key + Application Secret (from your Sinch dashboard app), not project-level OAuth2. Three auth methods are supported:

Method	Use for
Application Signed Request	Secure authentication method for production traffic
Basic Auth	Simple method for prototyping and trying out API calls
Public Auth	Insecure environments (end user's device). Android/iOS SDK only, requires callback webhook

Minimum auth level is configurable in the Sinch Dashboard — requests below that level are rejected. See the Authentication Guide for signing details.

关于控制台设置，可参考sinch-authentication技能文档。

Verification API使用应用密钥+应用密码（来自Sinch控制台的应用），而非项目级凭据。支持三种身份验证方式：

方式	适用场景
应用签名请求	生产环境流量的安全身份验证方式
基础身份验证	原型开发和API调用测试的简单方式
公共身份验证	不安全环境（终端用户设备）。仅支持Android/iOS SDK，需配置回调Webhook

最低身份验证级别可在Sinch控制台配置——低于该级别的请求将被拒绝。签名细节详见《身份验证指南》Authentication Guide。

SDK Setup

SDK设置

Language	Package	Install
Node.js	`@sinch/sdk-core` or `@sinch/verification`	`npm install @sinch/sdk-core`
Python	`sinch`	`pip install sinch`
Java	`com.sinch.sdk:sinch-sdk-java`	Maven dependency
.NET	`Sinch`	`dotnet add package Sinch`

All SDKs initialize with

applicationKey

applicationSecret

(not project credentials).

语言	包名称	安装命令
Node.js	`@sinch/sdk-core` 或 `@sinch/verification`	`npm install @sinch/sdk-core`
Python	`sinch`	`pip install sinch`
Java	`com.sinch.sdk:sinch-sdk-java`	Maven依赖
.NET	`Sinch`	`dotnet add package Sinch`

所有SDK均通过

applicationKey

applicationSecret

初始化（而非项目凭据）。

Canonical Example — Start SMS Verification

典型示例——启动SMS验证

bash

undefined

bash

undefined

Uses Basic Auth (-u) for simplicity. Use Application Signed Requests in production.

为简化演示使用基础身份验证(-u)。生产环境请使用应用签名请求。

curl -X POST https://verification.api.sinch.com/verification/v1/verifications
-H 'Content-Type: application/json'
-u YOUR_APPLICATION_KEY:YOUR_APPLICATION_SECRET
-d '{ "identity": { "type": "number", "endpoint": "+12025550134" }, "method": "sms" }'


Response includes `id` (verification ID), `sms.template`, `sms.interceptionTimeout`, and `_links` with localized URLs for status/report actions.


响应内容包含`id`（验证ID）、`sms.template`、`sms.interceptionTimeout`，以及包含状态/报告操作本地化URL的`_links`字段。

Key Concepts

核心概念

Verification Methods

验证方式

Method	Value	Behavior
SMS	`sms`	Sends OTP via SMS. User enters code.
FlashCall	`flashcall`	Missed call — caller ID is the OTP. Auto-intercepted on Android; manual entry on iOS/JS.
Phone Call	`callout`	PSTN call dictates an OTP code. User enters the code into the app (same flow as SMS).
Data	`seamless`	Carrier-level verification via mobile data. No user interaction. Requires account manager to enable.
WhatsApp	`whatsapp`	Sends OTP via WhatsApp message. User enters code.

方式	参数值	行为说明
SMS	`sms`	通过SMS发送OTP，用户手动输入验证码
FlashCall	`flashcall`	未接来电——来电显示号码即为OTP。Android设备可自动拦截；iOS/JS需用户手动输入
语音电话	`callout`	通过PSTN电话语音播报OTP，用户在应用中输入验证码（与SMS流程一致）
数据验证	`seamless`	通过移动数据实现运营商级验证，无需用户交互。需联系客户经理开通
WhatsApp	`whatsapp`	通过WhatsApp消息发送OTP，用户手动输入验证码

Core Model

核心模型

Identity: Always

{ "type": "number", "endpoint": "+E164_NUMBER" }

Verification ID: Returned on start. Used to report code or query status.
Reference: Optional unique tracking string in start request. Queryable via status endpoint.
Statuses:
```
PENDING
```
|
```
SUCCESSFUL
```
|
```
FAIL
```
|
```
DENIED
```
|
```
ABORTED
```
|
```
ERROR
```
Failure reasons (most common):
```
Invalid code
```
,
```
Expired
```
,
```
Fraud
```
,
```
Blocked
```
,
```
Denied by callback
```
. Full list in the API Reference.

身份信息：固定格式为

{ "type": "number", "endpoint": "+E164_NUMBER" }

验证ID：启动验证时返回，用于上报验证码或查询状态
参考标识：启动请求中的可选唯一跟踪字符串，可通过状态端点查询
状态值：
```
PENDING
```
|
```
SUCCESSFUL
```
|
```
FAIL
```
|
```
DENIED
```
|
```
ABORTED
```
|
```
ERROR
```
失败原因（常见）：
```
Invalid code
```
、
```
Expired
```
、
```
Fraud
```
、
```
Blocked
```
、
```
Denied by callback
```
。完整列表详见API参考文档。

API Endpoints

API端点

All endpoints documented in the Verification API Reference.

所有端点详情均记录在Verification API参考文档中。

Start Verification

启动验证

POST /verification/v1/verifications

Set

method

sms

flashcall

callout

seamless

, or

whatsapp

. Optional fields:

```
reference
```
— unique tracking string, passed to all events
```
custom
```
— arbitrary text (max 4096 chars), passed to all events
```
Accept-Language
```
header — controls SMS language (default
```
en-US
```
)

Method-specific options (backend-originated signed requests only):

smsOptions

flashCallOptions

calloutOptions

whatsappOptions

. See the API Reference for full schemas.

POST /verification/v1/verifications

设置

method

为

sms

、

flashcall

、

callout

、

seamless

或

whatsapp

。可选字段：

```
reference
```
— 唯一跟踪字符串，会传递至所有事件
```
custom
```
— 任意文本（最大4096字符），会传递至所有事件
```
Accept-Language
```
请求头 — 控制SMS语言（默认
```
en-US
```
）

特定方式的配置选项（仅后端发起的签名请求支持）：

smsOptions

、

flashCallOptions

、

calloutOptions

、

whatsappOptions

。完整schema详见API参考文档。

Report Verification

上报验证结果

Report by identity:

PUT /verification/v1/verifications/number/{endpoint}

Report by ID:

PUT /verification/v1/verifications/id/{id}

Body includes

method

and a method-specific object with the user's input:

SMS / Phone Call / WhatsApp:
```
{ "method": "sms", "sms": { "code": "1234" } }
```
(replace method name + key accordingly)
FlashCall:
```
{ "method": "flashcall", "flashCall": { "cli": "+46000000000" } }
```
— the
```
cli
```
is the full international caller ID from the incoming missed call

通过身份信息上报：

PUT /verification/v1/verifications/number/{endpoint}

通过验证ID上报：

PUT /verification/v1/verifications/id/{id}

请求体需包含

method

和对应方式的用户输入对象：

SMS / 语音电话 / WhatsApp：
```
{ "method": "sms", "sms": { "code": "1234" } }
```
（替换对应方式名称和键名即可）

FlashCall：

{ "method": "flashcall", "flashCall": { "cli": "+46000000000" } }

—

cli

为未接来电的完整国际来电显示号码

Get Verification Status

查询验证状态

By ID:

GET /verification/v1/verifications/id/{id}

By method + number:

GET /verification/v1/verifications/{method}/number/{endpoint}

By reference:

GET /verification/v1/verifications/reference/{reference}

Note: The by-identity endpoint requires

{method}

in the path — it is NOT

/verifications/number/{endpoint}

通过ID查询：

GET /verification/v1/verifications/id/{id}

通过方式+号码查询：

GET /verification/v1/verifications/{method}/number/{endpoint}

通过参考标识查询：

GET /verification/v1/verifications/reference/{reference}

注意： 通过身份信息查询的端点要求路径中包含

{method}

——并非

/verifications/number/{endpoint}

。

Common Patterns

常见模式

Standard Verification Flow

标准验证流程

Start —
```
POST /verification/v1/verifications
```
with identity + method → receive verification
```
id
```
Report — User receives code/call →
```
PUT /verification/v1/verifications/id/{id}
```
with the code/CLI

Check status —

GET /verification/v1/verifications/id/{id}

→ confirm

SUCCESSFUL

If the code expires or verification fails, you cannot re-report — start a new verification.

启动 — 调用
```
POST /verification/v1/verifications
```
，传入身份信息+验证方式 → 获取验证
```
id
```
上报 — 用户接收验证码/来电 → 调用
```
PUT /verification/v1/verifications/id/{id}
```
，传入验证码/CLI

查询状态 — 调用

GET /verification/v1/verifications/id/{id}

→ 确认状态为

SUCCESSFUL

如果验证码过期或验证失败，无法重新上报——需发起新的验证请求。

Webhooks (Callbacks)

Webhook（回调）

For production flows, configure a callback URL in the Sinch Dashboard. The API sends:

VerificationRequestEvent — fired when a verification starts. Respond with
```
action: allow
```
or
```
action: deny
```
to approve/reject.
VerificationResultEvent — fired when a verification completes (success or failure). Use for logging, analytics, or triggering downstream actions.

Callbacks are signed — verify signatures using Callback Signing.

生产环境流程中，需在Sinch控制台配置回调URL。API会发送以下事件：

VerificationRequestEvent — 验证启动时触发。返回
```
action: allow
```
或
```
action: deny
```
以批准/拒绝验证请求。
VerificationResultEvent — 验证完成时触发（成功或失败）。可用于日志记录、数据分析或触发后续操作。

回调请求会被签名——需使用《回调签名验证》Callback Signing中的方法验证签名。

Gotchas and Best Practices

注意事项与最佳实践

Auth is Application Key + Secret, not OAuth2. Do not use project-level credentials.
Use Application Signed Requests in production. Application auth protects integrity of a request
Base64-decode the secret before signing. The dashboard value is base64-encoded.
FlashCall auto-intercepts on Android only. iOS/JS users must manually enter the incoming number. Android SDK is required to intercept calls.
Method availability varies by country. SMS is the most widely available.
Codes expire. Configurable via
```
smsOptions.expiry
```
. Start a new verification if expired — you cannot re-report on a completed/expired verification.
Report by ID is more precise than reporting by phone number.
Rate limit: avoid rapid re-verification of the same number. Implement backoff.
Data verification requires account manager and mobile data (not Wi-Fi).
SMS language may be overridden by carrier compliance (e.g., US shortcode requirements).

身份验证使用应用密钥+密码，而非OAuth2。 请勿使用项目级凭据。
生产环境使用应用签名请求。 应用级身份验证可保障请求的完整性。
签名前需Base64解码密码。 控制台中显示的密码是Base64编码的。
FlashCall仅在Android设备支持自动拦截。 iOS/JS用户需手动输入来电号码。需使用Android SDK实现来电拦截功能。
验证方式的可用性因国家/地区而异。 SMS是支持范围最广的方式。
验证码会过期。 可通过
```
smsOptions.expiry
```
配置过期时间。如果验证码过期，需发起新的验证请求——无法对已完成/过期的验证重新上报。
通过ID上报更精准，比通过手机号上报更可靠。
限流控制： 避免频繁重复验证同一号码，需实现退避策略。
数据验证需联系客户经理开通，且需使用移动数据（而非Wi-Fi）。
SMS语言可能被运营商合规要求覆盖（例如美国短码规则）。

sinch-verification-api

Original

Translation

Sinch Verification API

Sinch Verification API

Overview

概述

Agent Instructions

Agent使用说明

Getting Started

快速入门

Authentication

身份验证

SDK Setup

SDK设置

Canonical Example — Start SMS Verification

典型示例——启动SMS验证

Uses Basic Auth (-u) for simplicity. Use Application Signed Requests in production.

为简化演示使用基础身份验证(-u)。生产环境请使用应用签名请求。

Key Concepts

核心概念

Verification Methods

验证方式

Core Model

核心模型

API Endpoints

API端点

Start Verification

启动验证

Report Verification

上报验证结果

Get Verification Status

查询验证状态

Common Patterns

常见模式

Standard Verification Flow

标准验证流程

Webhooks (Callbacks)

Webhook（回调）

Gotchas and Best Practices

注意事项与最佳实践

Links

相关链接