Let callers check an order status with the IllyVoIP Voice API

An IllyVoIP API-controlled phone line can collect an order reference and speak an authorized status from your own order system. Your backend provides the lookup and access checks. This is a custom integration; entering a reference or recognizing caller ID is not sufficient authentication for private order information.

Run Voice API requests on your backend with X-Api-Key authentication and JSON bodies. Use the API base https://api.illyvoip.com. Persist a separate Idempotency-Key for each paid call or prompt action and reuse that action’s key while its outcome is pending. Calling and speech can incur charges. Examples use placeholders and describe application logic; they are not records of completed calls.

1. Define the information you may disclose

1. Choose the minimum status information the phone workflow may reveal.
2. Define an approved verification step before private details are read aloud.
3. Decide how unknown orders, failed verification and unavailable order services will be handled.
4. Provide an appropriate assistance path without exposing whether another customer’s order exists.

Use the same authorization rules as your authenticated order application. Do not expose addresses, payment details or sensitive purchases based only on a telephone number match. A caller can know another person’s order reference, and caller ID is not proof of account ownership.

2. Answer the eligible incoming call and collect the reference

Follow the incoming Voice API guide to answer a call your integration controls and retain its call-control reference. Keep one controller responsible for the call. After the approved verification step, use POST /api/v1/voice/call-control/gather to request a bounded reference.

{
  "call_control_id": "YOUR_CALL_CONTROL_ID",
  "input": "dtmf",
  "prompt_text": "Enter your six digit order reference, then press hash.",
  "timeout_ms": 12000
}

This example assumes your application deliberately uses six-digit phone references. It does not convert arbitrary order IDs into six digits. The current gather path supports this length; do not add an undocumented digit-limit field to the request. If your actual references use letters or a different format, design and verify another collection method first.

3. Validate the complete result

1. On HTTP and API success, verify input is dtmf and read digits. Distinguish that result from timeout, disconnect or a failed request.
2. Require exactly six ASCII digits for this example.
3. Keep the value as a string so leading zeroes remain intact.
4. Apply a small, explicit retry limit and stop collection when the call is no longer active.

For example, 001234 is a different representation from the integer 1234. Reject extra digits and unrelated characters rather than stripping arbitrary input until it resembles an order number. Treat the terminator according to the actual gather response contract, not as part of the stored reference.

4. Perform an authorized backend lookup

Query your own order service using the verified customer context and the validated reference together. Use a parameterized query or the service’s typed API. Do not concatenate keypad input into SQL, a URL path or a command. Keep order-system credentials on the backend and restrict its access to the required read operation.

1. Recheck that the verification session is still valid for this call.
2. Find only an order the verified customer is entitled to access.
3. Map internal states to a small approved set of customer-facing phrases.
4. Treat missing, unauthorized or unavailable results according to the defined safe response.

Use consistent responses where necessary to avoid revealing another customer’s order existence. Do not invent a delivery date when the upstream service provides only a processing state. A successful HTTP response from the order service is not by itself permission to read every field it returned.

5. Speak a concise result and finish

Use the Voice API speech action with reviewed text and a voice available in the Voice API context. Avoid reading untrusted free-text notes verbatim. If you offer an assistance transfer, use the documented target and track the transfer result before assuming a person answered. Post call_control_id, approved text and wait_for_playback_completion: true to /api/v1/voice/call-control/speak. This completion option is supported by the current implementation. Await the completed speech result before posting the control ID to /api/v1/voice/call-control/hangup, so the message is not cut off.

6. Verify the security and failure paths

Before making an authorized test call, use fixtures for leading zeroes, invalid input, expired verification, another customer’s reference, duplicate results, service timeout and a disconnect during lookup. Confirm that no failure leaks order details or causes an unbounded retry. Then test the real call flow using an approved test account and number. Log the call reference, sanitized outcome and timing; exclude API keys, verification secrets and full order records.

Related guides

• Route an incoming number to Voice API Control and answer it from your application
• Build a keypad phone menu with the Voice API
• Place an outbound notification call with the Voice API

Reference

Current instructions and technical reference: IllyVoIP API documentation.

Reviewed 12 October 2026 against the current IllyVoIP controls, implementation and applicable references. Available options depend on account permissions and service state.