Developer Documentation

DeviceBound Verification API · v1 preview

API access is currently in private beta for enterprise partners. To request credentials, contact support@devicebound.us.

Authentication

Authenticate every request with your secret API key in the Authorization header. Keys are issued per environment and can be revoked at any time. Keep keys server-side; never ship them in client code.

Authorization: Bearer db_live_xxxxxxxxxxxxxxxx

Create Verification

Creates a DeviceBound Live verification request and returns the one-time link to deliver to the recipient.

POST https://devicebound.us/api/v1/verifications

{
  "recipient_phone": "+15551234567",
  "requester_name": "Acme Security",   // optional, shown to the recipient
  "delivery": "sms"                    // "sms" | "none" (deliver the link yourself)
}

Sample response:

201 Created

{
  "live_id": "DBL-2026-00000042",
  "status": "pending",
  "verify_url": "https://devicebound.us/live/<one-time-token>",
  "expires_at": "2026-07-10T18:30:00Z"
}

Verify Status

Poll the current state of a verification.

GET https://devicebound.us/api/v1/verifications/DBL-2026-00000042

200 OK

{
  "live_id": "DBL-2026-00000042",
  "status": "verified",              // pending | verified | expired | failed
  "verified_at": "2026-07-10T18:04:12Z",
  "recipient_phone_masked": "•••• ••4567"
}

Webhooks

POST <your-webhook-url>
X-DeviceBound-Signature: sha256=...

{
  "event": "verification.verified",   // verification.created | .verified | .expired
  "live_id": "DBL-2026-00000042",
  "occurred_at": "2026-07-10T18:04:12Z"
}

Verify the signature by computing an HMAC-SHA256 of the raw body with your webhook secret and comparing it to the header value.

Error Codes

Status	Code	Meaning
400	invalid_request	Missing or malformed parameters (e.g. bad phone number).
401	unauthorized	Missing or invalid API key.
402	payment_required	The request is not covered by an active plan or payment.
404	not_found	Unknown verification ID.
410	expired	The verification link has expired or was already used.
429	rate_limited	Too many requests; retry with backoff.

Sample Request (cURL)

curl -X POST https://devicebound.us/api/v1/verifications \
  -H "Authorization: Bearer db_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_phone": "+15551234567",
    "requester_name": "Acme Security",
    "delivery": "sms"
  }'