Submit a phone-number lookup

Server URLloading...

POST

/v1/lookup

Send

Authorization

Header

Body

Look up details for a phone number. Lookups are limited to US and Canada E.164 numbers. The call is synchronous and returns 200 OK with the result inline on every outcome except a platform error, which returns 502 LOOKUP_FAILED with your wallet refunded.

Lookups are available on every plan tier; the gate is your wallet balance, not your plan, so there is no 403 PLAN_REQUIRED on this endpoint. Under PAYG every org is credit-gated; insufficient credit returns 402 INSUFFICIENT_CREDIT.

Sending an Idempotency-Key header (up to 255 characters) is optional but recommended for retries. When a lookup already exists for that key, the existing result is returned without a new charge or a new lookup.

A lookup.completed webhook event fires on every successful and failed lookup, so fire-and-forget integrations can listen for it instead of holding the connection. Subscribe to it with POST /v1/webhooks. The synchronous response is authoritative; the webhook is additive.

Requires the lookups:write scope.

Header Parameters

Response Body

curl -X POST "https://example.com/v1/lookup" \  -H "Content-Type: application/json" \  -d '{    "phone_number": "+15551234567",    "lookup_type": "advanced"  }'

{
  "success": true,
  "data": {
    "id": "0190a1b2-c3d4-e5f6-a7b8-c9d0e1f2a3b4",
    "phone_number": "+15551234567",
    "lookup_type": "advanced",
    "status": "complete",
    "result": {
      "line_type": "MOBILE",
      "messaging_provider": "T-Mobile USA, Inc.",
      "voice_provider": "T-Mobile USA, Inc.",
      "country_code": "USA"
    },
    "result_redacted_at": null,
    "error_code": null,
    "error_message": null,
    "requested_at": "2026-04-30T15:23:01Z",
    "completed_at": "2026-04-30T15:23:01.847Z",
    "cost_cents": 2
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "authentication failed",
    "request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
  }
}

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDIT",
    "message": "insufficient credit",
    "request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
  }
}

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "missing required scope",
    "request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "validation failed",
    "request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM",
    "details": {
      "lookup_type": "must be \"advanced\""
    }
  }
}

{
  "success": false,
  "error": {
    "code": "LOOKUP_FAILED",
    "message": "internal server error",
    "request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
  }
}