Getting started with the Spoofey API

The Spoofey API gives you the same callback bridge as the dashboard, as a plain REST API you can call from your own code. It rings your phone first, then connects the destination showing the caller ID you chose. This guide covers generating a key and placing your first call.

1. Generate a key

Go to Settings → API while signed in, give the key a name (e.g. "Production server"), and click Generate key. The full secret is only shown once, right after you create it, so copy it somewhere safe. After that, only its name and the first few characters are ever shown again.

See Authenticating with an API key for how to send it and how to keep it safe.

2. Place a call

text

curl https://api.spoofey.com/v1/calls \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "+15195551234",
    "destination": "+14165557890",
    "caller_id": "+18005551234"
  }'

agent: the number to ring first. Like on the dashboard, this should be a phone you control.
destination: the number to connect once you answer.
caller_id: what the destination sees ring in.

A successful call returns immediately:

text

{
  "id": "9f2c1a7e-4b3d-4e2a-8f11-2b6a7c9d0e12",
  "status": "calling",
  "agent": "15195551234",
  "destination": "14165557890",
  "caller_id": "18005551234",
  "caller_id_name": null,
  "minutes_remaining": 42.5,
  "business_call": false
}

3. Check what happened

The response comes back before the call connects, so it only tells you the call was placed, not how it went. Poll its status with the id from the response:

text

curl https://api.spoofey.com/v1/calls/9f2c1a7e-4b3d-4e2a-8f11-2b6a7c9d0e12 \
  -H "Authorization: Bearer sk_live_..."

Each endpoint has its own page under API reference: start with POST /v1/calls and GET /v1/calls/:id, and see API errors and rate limits for what a rejected request looks like.

There's no sandbox

Every call the API places is a real call against your real balance, exactly like placing one from the dashboard. There's no test mode and no range of fake numbers. Validation errors (a bad number, an insufficient balance, a blocked destination) are free and instant, so you can safely test your error handling before you ever place a real call.

Not in the API yet

Renting, buying, or releasing a number (only calling/texting from one you already hold).
Creating or editing IVR flows, and the call queue. Build those in the dashboard. You can list them and look up their ids over the API (GET /v1/ivr-flows), and trigger a published outbound flow (POST /v1/outbound-ivr-calls).
The number-intelligence lookup report (an internal tool, not a customer-facing feature).