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

A phone lookup API provides information about a phone number, not about the person using it. Before integrating one into a signup process, it's important to decide which basic property decisions the lookup can support and what code should do if the lookup fails or returns no information. The article uses a synthetic four-branch example to map each possible lookup output to a specific next step in the signup flow, without treating a lookup as proof of possession or identity.

When designing the signup flow, the tempting binary approach of rejecting invalid numbers and passing valid ones fails. It rejects users when the lookup can't answer, and it silently upgrades property checks into proof of user ownership of the number. The real decision to be made is which signup step a basic property can influence, and which outcomes must route to review, an existing OTP provider, or a bounded retry instead of outright rejection.

The synthetic example returns a consistent JSON structure for all four branches, with the only difference being the next step field. The normal branch returns a valid phone number that can continue to customer policy. The unknown branch returns an unknown number, with next pointing to a review or existing OTP flow. The provider_failure branch returns an unknown number with next set to a bounded retry followed by review. The otp branch returns an unsupported number type with next set to customer OTP provider.

It's important to note that the lookup only describes the number, not whether the person can receive messages on it or who they are. The checked example returns only a simulated state with no line type information, which is in line with the current free Basic Lookup route limitations. The example is distinct from an anonymous three-scenario HTTP trial and should not be treated as such.

When handling unknown and provider_failure results, it's crucial to understand that they both share state unknown and null properties. The distinction lies in the next step - unknown means the lookup ran but couldn't characterize the number, while provider_failure means the call itself didn't complete. In both cases, a retry may succeed, so the example suggests a bounded retry followed by review. Neither result proves the number is bad, and neither should result in automatic rejection.

In your application design, it's essential to record which branch occurred, cap retries with a fixed count and backoff, and send exhausted retries to the same review queue as unknown results. This approach treats the lookup result as data rather than proof of ownership or identity. A raised UNSUPPORTED_FIXTURE error should be treated as a programming error, not a user outcome.

To move from the synthetic example to a sandbox request, confirm that all four branches run and match the expected fields exactly. Ensure unknown and provider_failure route to different next steps and neither rejects, and that retries are capped and end in review. Remember that the lookup result should never be stored as ownership or identity, and unsupported branches should fail loudly. If these conditions are met, a sandbox integration should fit the task.