Build an account reminder by reading existing IllyVoIP phone-number orders and sending an SMS to an approved administrative contact before a reported renewal date. Your application owns the reminder schedule and ledger. This does not enable a native renewal-SMS setting, renew a number or add funds to the account.
Use a backend with authorized account API access and keep X-Api-Key out of browser code. The API base is https://api.illyvoip.com. Check HTTP status and the JSON result. Examples below are request templates, not records of completed transactions.
SMS submissions can incur charges. Use the standard IllyVoIP sender or a custom sender approved and available for this account. Recipient eligibility, content review, encoding and current service limits still apply. Store an Idempotency-Key with the exact request before submission; preserve both after an uncertain response.
1. Read the current owned orders
Request GET /api/v1/dids/orders with the authorized account-owner key. The current response contains orders.active, orders.pending, orders.cancelled and orders.rejected. It is a grouped list, not a paginated call-history response; do not invent a cursor or page loop for this endpoint.
Use the stable order_id and read status.code, the displayed number and fees.renewal_date. Select an active order with an explicit valid date for the reminder policy. Keep pending, canceled, rejected and missing-date orders separate. A number awaiting issuance should not be described as an active assigned number.
2. Treat a renewal date as a date
The returned renewal value is a calendar date such as 2026-11-01, not a timestamp with a guaranteed hour. Choose and record the application’s business timezone for its reminder schedule. Do not parse the date as UTC midnight and then shift it into a different calendar day for local display.
A null date is unknown, not today and not a promise that renewal is disabled. The public list does not expose every internal auto-renewal or scheduled-cancellation detail. An active entry with a date does not by itself prove that renewal will occur. Use cautious wording such as “reported renewal date” and direct the owner to Phone Numbers to review the current state.
3. Choose the recipient and reminder window
- Ask the account owner to choose an authorized, verified administrative contact.
- Do not send to the purchased IllyVoIP number merely because it appears in the order.
- Choose one explicit lead time, such as three calendar days, and record the timezone.
- Decide whether missed scheduler runs may catch up and when an overdue reminder expires.
- Limit repeated reminders and preserve the owner’s notification preferences.
For example, a three-day reminder for 1 November becomes eligible on 29 October in the chosen business calendar. That is an application policy, not an IllyVoIP cutoff or guarantee. Do not promise a specific renewal hour from the date alone.
4. Recheck before creating the SMS submission
Use a unique reminder identity combining account, order ID, reported renewal date and reminder stage. Before dispatch, read the orders again. If the order is no longer active, the date changed or the recipient preference was withdrawn, cancel the obsolete unsent intent and reassess the current state.
There is no atomic transaction spanning a read-only order lookup and an SMS send. The order can change afterward, so include the review context in your wording and avoid a guaranteed renewal claim. This example contains fictional values:
{
"from": "IllyVoIP",
"to": ["+12025550123"],
"message": "Your IllyVoIP phone-number order has a reported renewal date of 1 Nov. Open Phone Numbers to review its status and your account balance."
}Send through /api/v1/sms/messages with the saved request key and exact payload. The notification can itself incur an SMS charge. Do not present it as a free service reminder or as evidence that the balance will cover renewal.
5. Keep reminders separate from number management
Save accepted message IDs and follow delivery without submitting the reminder again. If the response is uncertain, reconcile the original key and body. If a later order update makes the reminder outdated, update your application record; do not assume an accepted SMS can be recalled.
This worker should not call purchase, cancellation or other number-management mutations. A delivered reminder does not reserve the number, complete a renewal, verify sufficient balance or prove the owner read it. Use the existing Portal or API number-management guides for an owner’s deliberate action.
6. Check date and state changes with fixtures
Test month/year boundaries, leap days, a null or invalid date, a changed renewal date, an active order with scheduled cancellation not visible in the public list, a canceled order and two simultaneous scheduler runs. Verify that each stage creates at most one application intent and that old unsent reminders are invalidated. Keep the last successful order-read time visible to operators so a failed lookup never appears to be a fresh empty inventory.
Related guides
- Cancel a phone-number order or stop renewal through the IllyVoIP API
- Find, quote and order a phone number by API
- Send an SMS with the IllyVoIP API and track delivery
Reference
Current instructions and technical reference: IllyVoIP API documentation.
Reviewed 13 October 2026 against the current IllyVoIP controls, implementation and applicable references. Available options depend on account permissions and service state.