API reference.

Authentication

Send your API key in the Authorization header. Make requests from your server and keep the key private.

Authorization: Bearer YOUR_API_KEY

Create and manage keys in API keys & usage. For account setup and a first request, see the quickstart.

Request fields

POST https://quietpass.com/v1/phone/lookup

Send one phone number and select the checks to run. The same endpoint handles free and paid checks.

{
  "phone": "07400 123456",
  "defaultCountry": "GB",
  "checks": [
    "basic_line_type",
    "current_carrier",
    "whatsapp",
    "telegram"
  ],
  "currency": "GBP",
  "maxSpend": "0.05"
}

Include Content-Type: application/json and a unique Idempotency-Key header. Reuse that key for retries of the same lookup; a new key starts a new lookup.

Checks

Mobile numbers include free SMS support inferred from number type. The sms check above is a separate enablement check. Check coverage for your country and network.

{
  "quoteId": "11111111-1111-4111-8111-111111111111",
  "maxSpend": "0.05"
}

Response fields

{
  "requestId": "11111111-1111-4111-8111-111111111111",
  "number": {
    "e164": "+44740012••••",
    "country": "GB",
    "valid": true,
    "type": "mobile",
    "carrier": "Example network"
  },
  "contact": {
    "sms": {
      "supported": true,
      "assumed": true,
      "basis": "mobile_line_type"
    },
    "whatsapp": {
      "registered": true
    },
    "telegram": {
      "registered": false
    }
  },
  "billing": {
    "amount": "0.05",
    "currency": "GBP"
  }
}

Reading the answers

number.valid checks the number’s format against numbering rules. It does not confirm ownership or that the number is in use. SMS support, app registration, and network reachability do not guarantee delivery.

Where number-type sources differ, detailed type takes priority over basic numbering information. Conflicting detailed answers remain null with conflicting_data. Unknown number fields use typeReason, carrierReason, or portedReason; other unknown fields include reason.

Details and timestamps

Add ?includeDetails=true to a lookup or saved-result request to include the evidence behind each answer.

GET /v1/phone/lookup?includeDetails=true

The additional details object contains individual observations and timestamps, the rules used to combine them, and any conflicts. retrievedAt is when information was retrieved; observedAt is when it was observed. A missing observation time stays null.

You can request details from a saved result without running another lookup or using more credit. This option applies to result endpoints, including quote execution. Leave it off quote, wallet, and coverage requests.

Recover an interrupted lookup

Read GET /v1/phone/lookup with the original Idempotency-Key. If you started with a quote, read GET /v1/phone/results/{quoteId}.

Results are retained for 24 hours. Reusing a key returns the original lookup rather than buying it again; changing its number, checks, currency, or spending limit returns a conflict. An unresolved lookup is never a zero-cost result.

A direct lookup not yet recorded can return 404 DIRECT_LOOKUP_NOT_FOUND; retry with the original input and key. The starter files save this identity and check the original status when run again.

Billing

Each selected package is charged once per number when at least one requested check gives a definite answer. A definite “no” counts. If none of its requested checks can answer, that package costs zero.

maxSpend limits the charge; billing.amount reports what you actually paid. The maximum is held while a lookup runs, and unused credit is released when it settles. Currency values are local prices, with no automatic conversion between workspaces.

See package prices, trial credit, and top-ups.

Coverage

Coverage requests are public and do not require an API key. Filter by a two-letter country code.

GET https://quietpass.com/api/coverage?country=GB

This returns the coverage catalog without checking a phone number. Explore countries and networks.

Errors

Errors include error.code and a request ID. After a timeout or unresolved execution, recover the original status before starting another lookup.

Starter files