SIM Swap

SIM Swap（换卡）是指用户的手机号码与一张新的 SIM 卡绑定的过程，通常发生在以下场景：挂失补卡、升级 SIM 卡、携号转网、开通多卡服务，或新用户继承了曾被他人使用的号码等。

攻击者会利用 SIM Swap 劫持他人手机号，拦截短信验证码，进而重置密码、接管账户。SIM Swap API 可实时检测指定手机号是否发生过换卡，帮助业务方在短信 OTP 验证等关键环节识别潜在的 SIM 劫持风险，降低账户被接管的概率。

注意： 当前仅支持以下国家/地区的号码查询 SIM Swap：巴西、印尼。

本 API 提供两个独立接口：

Retrieve Date：查询指定手机号最近一次 SIM Swap 发生的时间
Check：检测指定手机号在过去 N 小时内是否发生过 SIM Swap

调用验证

这两个接口均采用 HTTP Basic Auth 的验证方式，在 HTTP Header 中添加 Authorization：

Authorization: Basic ${base64_auth_string}

              
              Authorization: Basic ${base64_auth_string}

此代码块在浮窗中显示

${base64_auth_string} 的生成算法为：base64(dev_key:dev_secret)。

更多详情可参考调用验证了解如何进行 API 鉴权。

Retrieve Date

查询指定手机号最近一次 SIM Swap 发生的时间。

调用地址

POST https://otp.api.engagelab.cc/v1/sim-swap/retrieve-date

请求示例

一个请求对象以 JSON 格式表达，因此请求头需要带 Content-Type: application/json。

请求头

POST /v1/sim-swap/retrieve-date HTTP/1.1 Content-Type: application/json Authorization: Basic ${base64_auth_string}

              
              POST /v1/sim-swap/retrieve-date HTTP/1.1
Content-Type: application/json
Authorization: Basic ${base64_auth_string}

此代码块在浮窗中显示

请求体

{ "phone_number": "+381692223535" }

              
              {
  "phone_number": "+381692223535"
}

此代码块在浮窗中显示

请求参数

参数	类型	选项	说明
`phone_number`	String	必填	查询目标手机号，建议使用 E.164 格式

返回参数

成功返回

字段	类型	选项	描述
`request_id`	String	必填	本次查询记录 ID
`latest_sim_change`	String / null	必填	最近一次 SIM Swap 时间，RFC3339 格式；从未换卡时返回首次激活时间；因隐私法规限制无法返回数据时为 `null`

成功返回示例：

{ "request_id": "2055136570436075520", "latest_sim_change": "2026-05-01T15:00:00Z" }

              
              {
  "request_id": "2055136570436075520",
  "latest_sim_change": "2026-05-01T15:00:00Z"
}

此代码块在浮窗中显示

失败返回

HTTP 状态码为 4xx 或 5xx，响应体包含字段如下：

字段	类型	选项	描述
`code`	int	必填	错误码，详见错误码说明
`message`	String	必填	错误详情

常见失败返回示例：

参数错误示例：

{ "code": 3002, "message": "invalid phone_number" }

              
              {
  "code": 3002,
  "message": "invalid phone_number"
}

此代码块在浮窗中显示

余额不足示例：

{ "code": 3005, "message": "balance not enough" }

              
              {
  "code": 3005,
  "message": "balance not enough"
}

此代码块在浮窗中显示

号码不在服务覆盖范围示例：

{ "code": 5101, "message": "phone number is not in sim swap service coverage" }

              
              {
  "code": 5101,
  "message": "phone number is not in sim swap service coverage"
}

此代码块在浮窗中显示

通用失败示例：

{ "code": 5100, "message": "failed to retrieve sim swap date" }

              
              {
  "code": 5100,
  "message": "failed to retrieve sim swap date"
}

此代码块在浮窗中显示

Check

检测指定手机号在过去 N 小时内是否发生过 SIM Swap。

调用地址

POST https://otp.api.engagelab.cc/v1/sim-swap/check

请求示例

一个请求对象以 JSON 格式表达，请求头同样需要带 Content-Type: application/json。

请求头

POST /v1/sim-swap/check HTTP/1.1 Content-Type: application/json Authorization: Basic ${base64_auth_string}

              
              POST /v1/sim-swap/check HTTP/1.1
Content-Type: application/json
Authorization: Basic ${base64_auth_string}

此代码块在浮窗中显示

请求体

{ "phone_number": "+381692223535", "max_age": 400 }

              
              {
  "phone_number": "+381692223535",
  "max_age": 400
}

此代码块在浮窗中显示

请求参数

参数	类型	选项	说明
`phone_number`	String	必填	查询目标手机号，建议使用 E.164 格式
`max_age`	Integer	必填	查询窗口，单位小时，取值范围 `1 ~ 2400`

返回参数

成功返回

字段	类型	选项	描述
`request_id`	String	必填	本次查询记录 ID
`swapped`	Boolean	必填	在指定时间窗口内是否发生过 SIM Swap

成功返回示例：

{ "request_id": "2055136570293469184", "swapped": true }

              
              {
  "request_id": "2055136570293469184",
  "swapped": true
}

此代码块在浮窗中显示

失败返回

结构与 Retrieve Date 接口一致。特有的失败返回示例：

参数错误（max_age 超出范围）：

{ "code": 3002, "message": "max_age must be between 1 and 2400" }

              
              {
  "code": 3002,
  "message": "max_age must be between 1 and 2400"
}

此代码块在浮窗中显示

错误码

错误码	HTTP Code	说明
`1000`	500	内部错误
`2001`	401	鉴权失败，未携带正确的 token
`2002`	401	鉴权失败，token 已过期或已被禁用
`2004`	403	无调用此 API 的权限
`3001`	400	请求参数格式无效，请检查是否符合参数格式的 JSON 内容
`3002`	400	请求参数有误，请检查请求参数是否符合要求
`3005`	400	余额不足
`5100`	400	SIM Swap 通用失败
`5101`	400	该号码不在 SIM Swap 服务覆盖范围内，包括国家、运营商、号段暂不支持或号码无法识别