Phone lookup API: which signup decision can basic properties support?

The problem and the decision

Your signup form collects a phone number and your team wants a lookup before account creation. The tempting design is binary: valid passes, everything else rejects. That design fails in two ways. It rejects people whenever the lookup cannot answer, and it quietly upgrades a property check into proof that the user owns the number. The decision in front of you is narrower: which signup step may a basic property influence, and which outcomes must route to review, an existing OTP provider or a bounded retry instead of rejection. A lookup describes the number. It does not show that the person can receive messages on it, and it says nothing about who they are.

What the checked example actually returns

The downloadable example runs locally with Python 3.10 or newer, with no credentials and no network calls. Its phone task takes one input, branch, with four values: normal, unknown, provider_failure and otp. Every output carries mode set to synthetic_fixture, the branch name, otp_sent set to false and live_line_type_available set to false. The normal branch returns state simulated, valid true, line_type mobile and next continue_customer_policy. The unknown branch returns state unknown, valid null, line_type null and next review_or_existing_otp. The provider_failure branch returns state unknown, valid null, line_type null and next bounded_retry_then_review. The otp branch returns state unsupported, valid null, line_type null and next customer_otp_provider. Any other branch raises UNSUPPORTED_FIXTURE. Note that line_type mobile appears only in the synthetic normal branch: the current free Basic Lookup route does not request line type, ownership, reachability or OTP delivery, which is exactly what live_line_type_available false signals. This four-branch example is distinct from the anonymous three-scenario HTTP trial; do not treat one as the other.

Unknown versus provider failure

Both branches share state unknown and null properties, so code that only reads state cannot tell them apart. The difference is in next. Unknown means the lookup ran but could not characterise the number; retrying the same call immediately is unlikely to help, so the example points to review or to the OTP flow you already operate. Provider failure means the call itself did not complete; a retry may succeed, so the example suggests a bounded retry and then review. Neither is evidence that the number is bad, and neither should become automatic rejection. In your proposed application design, record which branch occurred, cap retries with a fixed count and backoff, and send exhausted retries to the same review queue as unknown results. That design is yours to implement; the fixture only names the next step.

A worked hypothetical scenario

Hypothetically, a small B2B tool lets new workspace admins sign up with a phone number used later for account notices. Its proposed policy: a valid result lets signup continue under the team's existing rules; nothing in the lookup grants seller or payout permissions. Run all four branches. For normal, the team expects valid true and next continue_customer_policy, and its code continues signup while still labelling the number unverified. For unknown, it expects next review_or_existing_otp and routes the user to its existing OTP step. For provider_failure, it expects next bounded_retry_then_review, retries twice in its own code, then flags review while letting the user finish the form. For otp, it expects state unsupported and next customer_otp_provider, and calls its own OTP vendor; otp_sent false confirms the example sent nothing. The team's assertions compare each field exactly, including the null values.

Failure handling and limits

Treat a raised UNSUPPORTED_FIXTURE as a programming error, not a user outcome. Never let valid null be coerced to false. Keep the provider failure retry bounded so a degraded provider cannot stall signup indefinitely. Remember the boundaries: the fixture is synthetic, its results are not live business permission, and engineering tests covering transitions do not prove production success. Eligible businesses can self-enroll for free Basic Lookup with a technical rate limit of 60 requests per minute, but live route availability for your case needs separate confirmation, and that route does not return line type.

Acceptance checklist

Before moving from the synthetic example to a sandbox request, confirm: all four branches run and match the expected fields exactly; unknown and provider_failure route to different next steps and neither rejects; retries are capped and end in review; otp_sent false is never read as a sent code; live_line_type_available false is respected, so no logic depends on line_type in live use; no lookup result is stored as ownership or identity; unsupported branches fail loudly. If each item holds, a sandbox integration fits the task; if your decision needs possession or identity, use OTP or identity verification instead.

Run the checked synthetic example

Download and extract https://gridzen.ai/downloads/verification-delivery.zip, enter verification_delivery, then run with Python 3.10+. This local example makes no network calls. Use a fresh database for an independent identity run.

python3 delivery.py phone --branch unknown
python3 delivery.py phone --branch provider_failure

Sources and scope

https://gridzen.ai/guides/signup-phone-check/ https://gridzen.ai/guides/current-capabilities/ Based on the checked source snapshot and local fixture; proposed application rules are design advice, not proven production behavior. Written with AI assistance and reviewed independently.