Send your application’s one-time codes through the IllyVoIP SMS API

You can send your application’s one-time verification code through the IllyVoIP SMS API. Your application must generate, expire and verify the code; the SMS send endpoint queues the message and reports delivery separately. This is a custom application workflow, not a way to modify the Portal’s own sign-in verification.

Before you start

Use an IllyVoIP account with SMS access, sufficient balance and an allowed sender for the intended destination. Keep its API key on your backend. Obtain the recipient’s agreement to the verification workflow, and use a destination you are authorized to contact. An international-format number passing validation does not guarantee that an OTP message will be accepted or delivered.

1. Create a verification challenge on your server

1. Bind the challenge to the intended user or session, normalized telephone number and purpose—for example, verifying a newly entered contact number. A code for one purpose must not approve a different operation.
2. Generate the code using a cryptographically secure random generator. Give it a short expiry, a bounded number of attempts and single-use behavior. Store it securely rather than in analytics or ordinary logs.
3. Apply request and resend limits before sending, with controls beyond a single session so refreshing the page cannot reset them. Keep responses from revealing whether an unrelated person owns an account.
4. Save a durable challenge identity and a stable SMS idempotency key before asking IllyVoIP to send anything.

These are application security requirements. An SMS delivery receipt cannot enforce them for you. SMS possession also has limits, including number reassignment and SIM-swap risk; choose stronger verification for sensitive account recovery or high-risk changes. See the linked OWASP guidance when designing that policy.

2. Send the code as an SMS message

Use POST /api/v1/sms/messages on https://api.illyvoip.com, authenticated with X-Api-Key, and send the documented SMS fields. The exact approved sender, recipient array and message text belong to the saved challenge. The message should name your service, explain the purpose and say when the code expires without adding unrelated promotional content.

1. Prepare the message once for this challenge. Do not create a new code every time a network request retries.
2. Submit the send request with its stable Idempotency-Key.
3. Save the response, including accepted queued_message_ids and any invalid_numbers. For one OTP recipient, confirm that recipient was actually accepted rather than treating any success envelope as sufficient.
4. If the send response is lost, retry the identical request with the same idempotency key. Changing the text or generating a new key makes it different work and can cause another message.

Use the existing SMS send guide below for the complete request schema. Keep the code out of URLs, public client logs, screenshots and support tickets. Your frontend should call your own application endpoint; it should never hold the IllyVoIP API key.

3. Verify the user’s code separately

1. Accept the code only for the bound challenge and purpose. Check expiry and the remaining attempt budget on the server.
2. Compare it using your authentication framework’s secure verification approach. Consume a successful challenge atomically so simultaneous requests cannot use it twice.
3. On success, mark only the intended operation verified. Do not treat an SMS callback as equivalent to the user entering the code.
4. If the user requests another code, deliberately replace or invalidate the prior challenge while retaining abuse and attempt controls. Explain that only the current code should be used.

4. Handle delayed and failed delivery

Queued means accepted for sending, not delivered. Delivered means a delivery result was reported, not that the intended person read the message or proved ownership. Keep delivery status separate from challenge status in your database. A delayed message can arrive after its code expires; it must still be rejected by verification.

If no message arrives, first inspect acceptance and delivery for the saved message ID, the destination and sender eligibility. Do not repeatedly resend on every page refresh. Offer a controlled resend after your configured delay and an appropriate recovery route when SMS cannot be delivered. Avoid promising a universal delivery deadline.

Test the workflow without sending messages

Use local fixtures for a lost send response, duplicate callback, expired code, repeated failed attempts, a resend followed by the older code and two simultaneous successful submissions. Confirm that only one submission consumes the challenge and that a delivery update never verifies it. A later authorized real-message check should verify destination-specific delivery separately.

Related guides

• Send an SMS with the IllyVoIP API and track delivery
• Check SMS delivery

Reference

Current instructions and technical reference: OWASP: multifactor authentication.

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