强大而简洁的 REST API
集成、自动化,放心送达。
从您自己的代码发送短信、拨打改号电话、查询余额并获取实时价格。五个端点、一个 key、JSON 输入输出——价格和余额与您的仪表盘完全一致。
API 调试台
请求
curl https://app.spoofcallerid.com/v1/me \
-H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET"curl https://app.spoofcallerid.com/v1/balance \
-H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET"curl https://app.spoofcallerid.com/v1/prices?type=all \
-H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET"curl -X POST https://app.spoofcallerid.com/v1/sms \
-H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"to": "+447700900123",
"text": "Your code is 4821",
"sender_id": "Spoof",
"country": "GB"
}'curl -X POST https://app.spoofcallerid.com/v1/calls \
-H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"to": "+447700900123",
"caller_id": "+18005550199",
"to_country": "GB",
"record": false
}'curl -X POST https://app.spoofcallerid.com/v1/sms \
-H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"to": "+447700900123",
"text": "Your code is 4821",
"sender_id": "Spoof",
"country": "GB"
}'响应
{
"id": 1042,
"username": "you",
"email": "[email protected]",
"balance": 25.5,
"currency": "EUR",
"status": "active"
}{
"balance": 25.5,
"currency": "EUR"
}{
"success": true,
"type": "all",
"count": 200,
"cached_ttl": 3600,
"data": [
{
"country": "United Kingdom",
"iso": "GB",
"prefix": "44",
"call": 0.1,
"call_initblock": 1,
"call_billingblock": 1,
"call_tiers": [
{
"rate": 0.1,
"routes": 1
},
{
"rate": 0.4,
"routes": 1
},
{
"rate": 0.85,
"routes": 1
}
],
"sms": 0.0906,
"sms_routes": [
{
"name": "Route 1",
"rate": 0.0906
},
{
"name": "Route 2",
"rate": 0.0924
}
],
"hlr": null,
"currency": "EUR"
}
]
}{
"success": true,
"message": "SMS sent successfully.",
"data": {
"cost": 0.0906,
"newBalance": 25.4094,
"segments": 1,
"encoding": "gsm7",
"route": "",
"batchId": "7f3c2a91"
}
}{
"success": true,
"message": "Call placed successfully.",
"data": {
"id": 318,
"status": "dialing",
"cost": 0.5,
"newBalance": 25.0,
"currentBalance": 25.0,
"estimatedMinutes": 5,
"toNumber": "+447700900123",
"displayNumber": "+18005550199",
"ami_ref": "spoof_1042_1763190000"
}
}{
"error": {
"code": "insufficient_balance",
"message": "Insufficient balance.",
"details": {
"cost": 0.0906,
"balance": 0.02
}
}
}重要安全提示
请对您的 API key 和 secret 严格保密。只在您的服务器上使用,切勿放在客户端代码中。如果发生泄露,请在“账户 → API 与密钥”中重新生成——旧的密钥对会立即失效。
身份验证
Bearer每个请求都在同一个请求头中携带您的 key 和 secret,两者以冒号分隔。请求和响应均为基于 HTTPS 的 JSON。
Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET
基础 URL:https://app.spoofcallerid.com/v1
获取账户
GET /v1/me
返回拥有该 key 的账户:id、用户名、邮箱、余额和状态。
curl https://app.spoofcallerid.com/v1/me \
-H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET"{
"id": 1042,
"username": "you",
"email": "[email protected]",
"balance": 25.5,
"currency": "EUR",
"status": "active"
}获取余额
GET /v1/balance
您当前的欧元余额。调用成本很低——建议在大批量发送前先查询。
curl https://app.spoofcallerid.com/v1/balance \
-H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET"{
"balance": 25.5,
"currency": "EUR"
}获取价格
GET /v1/prices
所有目的地的实时通话和短信价格,与“覆盖范围与价格”中的列表一致。缓存一小时。
参数:
type:可选。all(默认)、sms或voice。
curl https://app.spoofcallerid.com/v1/prices?type=all \
-H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET"{
"success": true,
"type": "all",
"count": 200,
"cached_ttl": 3600,
"data": [
{
"country": "United Kingdom",
"iso": "GB",
"prefix": "44",
"call": 0.1,
"call_initblock": 1,
"call_billingblock": 1,
"call_tiers": [
{
"rate": 0.1,
"routes": 1
},
{
"rate": 0.4,
"routes": 1
},
{
"rate": 0.85,
"routes": 1
}
],
"sms": 0.0906,
"sms_routes": [
{
"name": "Route 1",
"rate": 0.0906
},
{
"name": "Route 2",
"rate": 0.0924
}
],
"hlr": null,
"currency": "EUR"
}
]
}发送短信
POST /v1/sms
使用您选择的发送方 ID 发送一条短信,并按短信分段从您的余额中扣费。
参数:
to:必填。带国家区号的收件人号码,例如+447700900123。text:必填。短信内容,最多 160 个字符。sender_id:必填。显示为发送方的名称或号码,1–20 个字母或数字。country:可选。当to不含国家区号时使用的 ISO 国家代码(例如GB)。route:可选。为目的地指定线路;默认使用最便宜的线路。
curl -X POST https://app.spoofcallerid.com/v1/sms \
-H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"to": "+447700900123",
"text": "Your code is 4821",
"sender_id": "Spoof",
"country": "GB"
}'{
"success": true,
"message": "SMS sent successfully.",
"data": {
"cost": 0.0906,
"newBalance": 25.4094,
"segments": 1,
"encoding": "gsm7",
"route": "",
"batchId": "7f3c2a91"
}
}发起改号呼叫
POST /v1/calls
发起一通显示您所选主叫号码的电话。呼叫开始时,系统会从您的余额中预留预估费用。
参数:
to:必填。被叫号码,使用国际格式,或使用本地格式并提供to_country。caller_id:必填。被叫方将看到的号码。to_country:可选。to的 ISO 国家代码,例如GB。caller_country:可选。caller_id的 ISO 国家代码。record:可选。设为true可录制通话。默认值为false。plan:可选。通话套餐 ID。每个套餐按各自的费率和计费单位计费;默认为 Worldwide。
curl -X POST https://app.spoofcallerid.com/v1/calls \
-H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"to": "+447700900123",
"caller_id": "+18005550199",
"to_country": "GB",
"record": false
}'{
"success": true,
"message": "Call placed successfully.",
"data": {
"id": 318,
"status": "dialing",
"cost": 0.5,
"newBalance": 25.0,
"currentBalance": 25.0,
"estimatedMinutes": 5,
"toNumber": "+447700900123",
"displayNumber": "+18005550199",
"ami_ref": "spoof_1042_1763190000"
}
}错误
4xx / 5xx每次失败都会返回下列 HTTP 状态码,以及包含稳定 error.code 的 JSON 响应体,供您据此进行分支处理。
invalid_request400 — 请求体不是有效的 JSON,或某个字段类型错误。unauthorized401 — Authorization 请求头缺失、格式错误,或 key/secret 不正确。insufficient_balance402 — 您的余额不足以支付费用。error.details中包含费用和余额信息。not_found404 — 端点不存在。请检查路径和/v1前缀。method_not_allowed405 — HTTP 方法错误;Allow响应头会给出正确的方法。validation_failed422 — 某个字段缺失或无效;error.message会指明是哪个字段。internal_error500 — 我们这边出现故障。请重试,若仍失败请联系支持。provider_rejected502 — 运营商拒绝了该短信或呼叫;未产生任何费用。service_unavailable503 — 某项依赖服务暂时不可用。请采用退避策略重试。
{
"error": {
"code": "insufficient_balance",
"message": "Insufficient balance.",
"details": {
"cost": 0.0906,
"balance": 0.02
}
}
}
连接您的 AI 助手(MCP)
5 toolsSpoofcallerid MCP 服务器将每个端点变成 Claude 或任何 MCP 客户端可用的工具:get_account、get_balance、get_prices、send_sms 和 make_spoof_call。单个文件,无依赖,支持 Node.js 18+。两个会消耗余额的工具会先请求确认。
{
"mcpServers": {
"spoofcallerid": {
"command": "node",
"args": [
"/path/to/spoofcallerid-mcp.mjs"
],
"env": {
"SPOOFCALLERID_API_KEY": "YOUR_API_KEY:YOUR_API_SECRET"
}
}
}
}
常见问题
我在哪里获取 API key?
登录仪表盘,打开“账户 → API 与密钥”。重新生成会创建新的 key 和 secret;secret 只显示一次,旧的密钥对会立即失效。
如何进行身份验证?
每个请求都需携带
Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET。请将 secret 保存在您的服务器上——切勿放在浏览器或移动应用中。每个请求的费用是多少?
读取账户、余额和价格均免费。
POST /v1/sms 和 POST /v1/calls 按与仪表盘相同的价格计费,价格可在“覆盖范围与价格”以及 GET /v1/prices 中查看。一条短信最长可以多少字?
每个请求最多 160 个字符。GSM-7 文本每段可容纳 160 个字符;含表情符号或非拉丁字母时会切换为 Unicode,每段可容纳 70 个字符,且按段计费。
AI 助手可以使用 API 吗?
可以。下载 Spoofcallerid MCP 服务器并填入您的 key,Claude 或任何 MCP 客户端即可查询您的余额和价格、发送短信并拨打电话。会产生费用的工具会先请求确认。