How an Android SIM Hosting API Runs USSD and SMS Jobs, Step by Step

Some things in Nigeria can still only be done the old way. You dial a code like *123#, follow a menu, and wait for an SMS. Banks, networks and some service providers never built a clean API for certain tasks.

A SIM hosting API is a way to automate that old way. A real Android phone, holding real SIM cards, stays online somewhere safe. Your software tells it what to dial or send. The phone does it and reports back.

We already wrote a general explanation in SIM Hosting Explained. This article is the developer's walk through: what happens, in order, from your request to the result.

One honest note first. The SIM Host on XpiriaTech is an early build. It works end to end against our platform, but we have not verified it against every network's real USSD menus. Menus change, and each network and bank word things differently. We say this up front so you test with your own SIM before you rely on it.

The pieces

1. The phone. An Android phone with a SIM, running the pairing app. It must stay powered, connected to the internet and on a network signal.
2. The service. A saved recipe that says what the phone should do: send this SMS, or dial this USSD code and reply to its menu.
3. The job. One run of a service, with the details filled in (for example, one phone number and one amount).
4. The result. What happened: it worked, it failed, or it timed out, plus the reply text.

Step 1: Pair a phone

You pair the Android phone with your account, usually by scanning a code. After that, the system knows the phone exists and whether it is online. Each SIM is a "slot" the system can use. A job needs a free slot.

Step 2: Write a service

A service is a template with blanks. For example, a USSD recipe might say:

1. Dial the code for transferring airtime.
2. Wait for the menu.
3. Reply with the amount.
4. Reply with the phone number.
5. Reply with the PIN.
6. Read the final message.

The blanks are written in double braces, like {{AMOUNT}} and {{PHONE}}. When you run the service, you provide the values and the system fills them in. This is why you can use one service for thousands of different jobs.

Two warnings about templates:

• Keep secrets out of logs. A SIM PIN in a template needs careful handling. Ask where it is stored and who can read it.
• Menus drift. If a network changes its menu order, your recipe breaks. Test it again after any change on their side.

Step 3: Trigger a job

There are two ways to start a job.

Through the API. Your server calls the SIM Host's public REST API with the service and the values. This is for any system you build yourself.

Wired into a VTU project. On XpiriaTech, you can attach a service to a network in your VTU site. When a customer buys, the order is routed to your phone instead of an online provider. This is useful when your own SIM gives you a better price than a reseller API.

Use an idempotency key or your own unique reference with each job. If your server retries after a network blip, the system should recognise the same request and not run it twice. A duplicated airtime transfer costs real money.

Step 4: The job runs on the phone

The system sends the job to the phone and marks it as running. The phone then:

1. Dials the code or sends the SMS.
2. Follows the menu steps in order, pausing for replies.
3. Reads the response.
4. Sends the outcome back to the server.

This is not instant. A USSD session can take several seconds, and some take much longer. If the phone has no signal, the job will wait or fail. If the phone is offline, no job can run on it, and the system should tell you so instead of queueing forever.

Step 5: Get the result

You have two choices.

Poll. Your code asks for the job's status every few seconds until it is finished. It is simple and works anywhere.

Webhook. The system calls a URL on your server when the job finishes. The message is signed, so your server can check it really came from the SIM Host. Always verify the signature, because the address of your webhook is public.

Whichever you use, treat these as three different endings:

• Success. The message says the action worked.
• Failure. A clear error came back (not enough balance, wrong menu option).
• Unknown. Nothing came back in time. Do not assume failure. The action may have worked. Check before you refund or retry.

What can go wrong

Plan for these before you go live.

• Phone offline or out of battery. Keep the phone on a charger, with a stable network. Ask the system for an alert when it goes offline.
• SIM runs out of balance. Jobs fail for a boring reason. Monitor the balance.
• Limits from the network. Some networks restrict how many USSD sessions a SIM can run, or flag unusual patterns.
• Wrong SIM or slot. On a dual-SIM phone, a job must use the right one.
• Terms of service. Your SIM's terms may restrict automated use. Read them.
• Physical safety. A phone with SIMs and money is a target. Keep it somewhere safe.

A sensible way to start

1. Pair one phone with one SIM that has a small balance.
2. Write one service and run it by hand ten times. Read every result.
3. Add your idempotency key and test a repeated request.
4. Add the webhook or polling.
5. Run a handful of real jobs a day for a week before you rely on it.

Where to go next

If you want to try it, the SIM Host is part of the XpiriaTech dashboard, and its developer documentation sits in the dashboard once you create an account. See the SIM Hosting service page for what it can do today and what we are still verifying. If you need something custom built on top, talk to us.