强大而简洁的 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_request 400 — 请求体不是有效的 JSON,或某个字段类型错误。
  • unauthorized 401 — Authorization 请求头缺失、格式错误,或 key/secret 不正确。
  • insufficient_balance 402 — 您的余额不足以支付费用。error.details 中包含费用和余额信息。
  • not_found 404 — 端点不存在。请检查路径和 /v1 前缀。
  • method_not_allowed 405 — HTTP 方法错误;Allow 响应头会给出正确的方法。
  • validation_failed 422 — 某个字段缺失或无效;error.message 会指明是哪个字段。
  • internal_error 500 — 我们这边出现故障。请重试,若仍失败请联系支持。
  • provider_rejected 502 — 运营商拒绝了该短信或呼叫;未产生任何费用。
  • service_unavailable 503 — 某项依赖服务暂时不可用。请采用退避策略重试。
{
    "error": {
        "code": "insufficient_balance",
        "message": "Insufficient balance.",
        "details": {
            "cost": 0.0906,
            "balance": 0.02
        }
    }
}
连接您的 AI 助手(MCP)
5 tools

Spoofcallerid MCP 服务器将每个端点变成 Claude 或任何 MCP 客户端可用的工具:get_account、get_balance、get_prices、send_sms 和 make_spoof_call。单个文件,无依赖,支持 Node.js 18+。两个会消耗余额的工具会先请求确认。

下载 MCP 服务器 · JSON 清单

{
    "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 客户端即可查询您的余额和价格、发送短信并拨打电话。会产生费用的工具会先请求确认。