You are adding a phone number validation API call to a signup form, and you need to decide what your code does with each answer before any real lookup runs. The trap is treating every result as pass or reject. This article walks through the four synthetic branches of the downloadable example, shows the exact fixture outputs, and separates what the example implements from the application design we propose. One limit up front: the current free Basic Lookup route does not request line type, ownership, reachability or OTP delivery, so your design must not depend on them.
The problem and the decision
A signup handler calls a phone check and receives a result. Sometimes it is a clean valid answer. Sometimes the answer is unknown, sometimes the provider call failed, and sometimes the question asked is one the route cannot answer at all, such as whether a code was delivered. If your handler rejects everything that is not a clean pass, a temporary outage becomes a lost signup and an unsupported question becomes a false accusation of a bad number. Your decision is narrow: which branch leads to continuing under your own policy, which leads to bounded recovery or review, and which hands off to a separate OTP provider you already operate. The example lets you make that decision against fixed, checked outputs before you request a sandbox integration.
What the example implements
The four-branch example is a dependency-free Python 3.10+ script in the verification_delivery directory of the downloadable ZIP. It needs no credentials and makes no network calls. You run the phone task with one of four branches: normal, unknown, provider_failure and otp. The only input is the branch; the output fields are mode, branch, state, valid, line_type, next, otp_sent and live_line_type_available. Every output carries mode synthetic_fixture, otp_sent false and live_line_type_available false. An unrecognized branch raises UNSUPPORTED_FIXTURE. This is a synthetic fixture, not a live provider adapter. It is also distinct from the anonymous three-scenario HTTP trial: do not treat results from one as evidence about the other. The bundled unit tests cover simulated transitions; they do not prove production success.
Worked hypothetical scenario and expected outputs
Hypothetically, a small B2B team wires its signup form to the fixture and runs each branch. Expected outputs: normal returns state simulated, valid true, line_type mobile, next continue_customer_policy. The mobile value exists only in the fixture; the live Basic Lookup route does not return line type, which is why live_line_type_available stays false. unknown returns state unknown, valid null, line_type null, next review_or_existing_otp. provider_failure returns state unknown, valid null, line_type null, next bounded_retry_then_review. otp returns state unsupported, valid null, line_type null, next customer_otp_provider, and otp_sent remains false: no message is sent. The team records these eight fields per branch as its acceptance fixtures and asserts on them exactly, including the null values, so a later change cannot silently turn unknown into invalid.
Proposed failure handling in your application
The following is proposed design, not implemented behavior. Treat valid true as permission to continue only under your own signup policy, never as proof of ownership or identity. Map unknown to a review queue or to the OTP step you already run elsewhere. Map provider_failure to a small, fixed number of retries with backoff, then review; do not retry indefinitely and do not reject the user because your dependency failed. Map unsupported to a handoff to your existing OTP provider, and wait for that provider's own confirmation rather than the fixture. Keep valid null distinct from valid false in storage and logs. Log the branch and next value so reviewers can see why a signup paused. Remember the live route has a technical rate limit of 60 requests per minute; a rate-limit response belongs in the failure path, not the invalid path.
Limits to keep visible
The fixture outputs are checked synthetic results, not live answers. A phone validity signal does not establish who holds the number, whether it can receive SMS, or whether a code arrived. Eligible businesses can self-enroll for the free Basic Lookup as an application adjunct, but live route availability for your case requires separate confirmation. Search interest in this topic is not evidence of demand, and passing the fixture is not evidence that a production integration works.
Acceptance checklist
Before requesting a sandbox integration, confirm: all four branches run locally and match the expected fields exactly; an unknown branch name fails with UNSUPPORTED_FIXTURE; no branch path rejects a user for unknown or provider_failure; retries are bounded and end in review; the otp path never displays a code-sent message based on the fixture; otp_sent false is asserted in tests; no logic reads line_type from the live route; valid null and valid false are stored separately; and your team notes record these as synthetic results. If every item holds, the sandbox request is a reasonable next step.
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.
curl https://gridzen.ai/console/api/quickstart/trial \
-H 'Content-Type: application/json' \
-d '{"task": "signup_phone", "scenario": "success"}'
This is synthetic integration testing, not identity verification or production authorization. Real payments are disabled.
Create a free sandbox account · Integration guide
Written and tested by the GridZen team with AI assistance.
Top comments (0)