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
country	ISO country code the number belongs to, e.g. IN
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	MISSING_API_KEY	No Authorization header was sent at all
401	INVALID_API_KEY	Key not found, or the header is present but malformed
401	REVOKED_API_KEY	Key exists but is not active
402	INSUFFICIENT_CREDITS	Balance below what the request needs
500	INTERNAL_ERROR	Our bug — credit refunded if one was already reserved
429	RATE_LIMITED	Per-key rate limit exceeded — see "Rate limiting" below
503	PROVIDER_UNAVAILABLE	[TO BE CONFIRMED] Cannot fire by current design — see below

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

Rate limiting

Every API key is limited to 2 requests/second, with a burst allowance up to 5. Exceeding it returns 429 RATE_LIMITED with a Retry-After header (seconds until the next token). Need a higher limit? Email us — it's a per-key setting we can raise on request.

Why 503 is listed but can't happen yet

[TO BE CONFIRMED] 503 PROVIDER_UNAVAILABLE is listed for completeness but cannot actually occur today: an unreachable/timing-out upstream call is absorbed per-type as a refunded, 200-status UNDETERMINED result (see /docs/errors), never as a request-level failure. 500 INTERNAL_ERROR is the one error code above that's real and live right now.