API reference

Every endpoint, every field, every error code.

POST /api/v1/filter

Checks a single phone number synchronously. Returns in under 1.5 seconds typically, under 100ms on a cache hit.

Field	Type	Notes
phone	string	E.164 format, e.g. +919876543210
source	string	Optional. Where this number came from — "facebook", "instagram", "website", "youtube", "bulk", etc. Defaults to "internal".

Which check type(s) run is an account setting now, not a request field — see Settings for the three you can enable: Network Connection Status (on by default), Phone Number Type, and Portability Status. Enabling an optional signal costs more credits per call, but never changes the shape of this response.

{
  "country": "IN",
  "valid": true,
  "status": "CONNECTED",
  "carrier": "Jio",
  "line_type": "MOBILE",
  "is_ported": false
}

Field	Meaning
valid	Whether the number is well-formed and live
status	CONNECTED \| ABSENT \| UNDETERMINED
carrier	Operator name, when determinable
line_type	e.g. MOBILE
is_ported	Whether the number has been ported between operators

That's the whole response — no cache flag, no per-request credit count. Credits are still deducted per the credit logic below; check your balance separately whenever you want it, with GET /api/v1/balance.

GET /api/v1/balance

curl https://api.usefilter.io/api/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

Errors

HTTP	error.code	When
400	INVALID_REQUEST	Malformed body, missing phone, or no check type enabled in Settings
401	INVALID_API_KEY	Key not found or malformed header
401	REVOKED_API_KEY	Key exists but is not active
402	INSUFFICIENT_CREDITS	Balance below what the request needs
429	RATE_LIMITED	Plan rate limit breached — see Retry-After header
503	PROVIDER_UNAVAILABLE	Upstream network unreachable — credit refunded

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "You have run out of credits. Top up at https://usefilter.io/billing"
  }
}

API reference

POST /api/v1/filter

GET /api/v1/balance

Errors

See also