Before building a telephone-number selector, agree how the ordering API handles availability, selection, checkout and confirmation. Then design the website around those rules, including what happens when an answer is delayed or a number is no longer available.
The important question is what the business can promise at each point. A number appearing in a search result, a number being selected and a number being ordered may represent different states. The provider’s actual contract needs to define them.
Use this checklist with the website team, backend owner and API provider. It is a planning guide for a new integration, not documentation of a particular supplier’s API.
Write down the ordering states in ordinary language
Ask the API owner to explain the journey without referring only to endpoint names. What does the visitor know after searching? Does selecting a number reserve it? When is the price confirmed? What response establishes that an order exists?
Create a small state table using the provider’s real terminology. These are illustrative questions, not assumed API behaviour:
| Stage | Question to resolve | Website decision |
|---|---|---|
| Results | How current is availability, and can it change? | What can the results honestly tell the visitor? |
| Selection | Is anything reserved, and is there an expiry? | Which explanation or time limit is needed? |
| Checkout | Which identifiers, options and price details are required? | What must be retained and checked before handoff? |
| Submission | How is an accepted request distinguished from a failed one? | When can the interface move to confirmation? |
| Confirmation | What proves the order was created? | Which reference and next step can be shown? |
Keep “unknown” as an explicit state where necessary. A request timing out does not prove that the backend rejected it. The interface needs a way to describe uncertainty without encouraging someone to create another order blindly.
Agree the information crossing each boundary
List the data passed from the selector into checkout and then into the backend. Define each field’s meaning, accepted format, source and owner. Include the identifiers required to distinguish the number and chosen options.
The browser should not be the authority for price or availability. Agree where those facts are validated before an order is accepted. If they change, decide how the visitor is told and what they can do next.
Separate trusted backend information from values supplied by the browser. Public page code is not a place for privileged credentials. OWASP’s REST security guidance covers endpoint access control and protecting credentials in transit; the actual integration still needs its own security design.
Check the handoff when the visitor changes their mind
People use the back button, choose another option or leave a page open. Define what survives each of those actions. If someone changes the number, the checkout summary and backend payload should refer to the new choice consistently.
Ask what happens when a selection expires or is no longer available. A useful recovery path explains the issue and lets the visitor make a fresh choice without silently carrying an outdated reference forward.
Do this before polishing the selector animation. The visible interaction depends on the promises the connected system can keep.
See the kind of website work this involves
For Telecoms World, our work included the marketing website, telephone-number selector, ordering API integration, checkout and backend connection, working with ECCE as a technology partner. We also handled visitor attribution and ongoing website work. The project article shows the public selector and explains that scope. It does not publish the provider’s private API contract.
Design retries around the operation
Searching again and submitting an order again are different actions. Do not apply one automatic retry rule to everything.
The HTTP semantics standard’s idempotency section explains why non-idempotent requests should not be retried automatically without a way to know that doing so is safe. In an ordering integration, ask the backend owner how duplicate submissions are recognised and how an uncertain result can be checked.
The provider may support an idempotency key, a unique client reference or another mechanism. Confirm the actual contract, including any limits, instead of adding a field the API does not understand.
Test the repeated-click case and the “request accepted, response lost” case separately. They expose different problems. Decide who can investigate an uncertain order and what information support will need.
Keep visitor attribution distinct from order authority
Marketing attribution can help a team understand the route into the website. It should not become the mechanism deciding whether a number is available or an order is valid.
Agree which attribution information is needed, how it is collected under the approved privacy configuration and what travels across the checkout boundary. Test the supported consent and script configurations. Do not assume every visitor arrives with the same cookies or campaign parameters.
Keep the operational order reference and the attribution context clearly named. A support colleague should be able to locate an order using the agreed reference without needing a campaign cookie. Your privacy and technical owners should also define what belongs in logs and how long it is retained.
Use a failure-focused test sheet
Run these cases with authorised test numbers and accounts in the provider’s test setup. Do not exercise a live purchasing flow without an agreed test arrangement.
| Test case | Evidence to collect |
|---|---|
| Number changes between selection and checkout | Summary, request and backend record refer to the agreed choice |
| Availability changes before acceptance | Clear explanation and a working recovery route |
| Connection fails before a request is accepted | Honest state and an appropriate retry path |
| Backend accepts a request but the response is lost | A documented status check without an unintended duplicate order |
| Visitor clicks twice or returns to checkout | The agreed duplicate-handling behaviour |
| Required option or identifier is missing | Validation and a recoverable message |
| Attribution context is absent | Ordering follows the agreed business rules without relying on optional marketing context |
| Provider changes its response or becomes unavailable | Detection, an owner and an agreed customer-facing response |
For each case, record the visible result and the backend evidence. A success message on the page is not enough to prove the order has reached the receiving system.
Leave an operating note after launch
The handover should include the API contract version, field map, state definitions, test results, credential ownership and the route for investigating failures. Record who approves changes on each side of the connection.
Keep the critical tests with the integration. A later script, form or checkout change can affect a previously working route. Include the relevant checks in the release process rather than relying on someone remembering the original build.
If you are planning this kind of connection, show us the public journey and the API documentation you can share. We can discuss the website and integration work around the systems you already have.
A few useful answers
Does selecting a number mean it is reserved?
Only if the provider’s actual API contract says so. Define the difference between results, selection, reservation, checkout and confirmed order before writing the interface.
Can a timed-out order request be retried automatically?
Do not assume it can. A timeout may leave an uncertain accepted result. The backend owner must define status checks and safe duplicate handling for the actual operation.
Does the Telecoms World screenshot prove private API behaviour?
No. It shows the public selector and empty form. The documented project scope covers the website and ordering connection, not the provider’s private reservation or retry contract.
