Activating SIMs with the ThingSIM API

If you install devices for customers, or build them on a bench, activating each SIM by hand in the portal soon becomes a chore. The ThingSIM API does the same job from your own tools: switch a SIM on when its device is installed, label it so you can find it later, and fetch eSIM codes without scanning a QR code. This guide walks through the basic flow.

Before you start

The API is one HTTPS endpoint, https://partners.netavo.com/api/v1, returning JSON. It is the same API the portal uses. Create a key in the portal under API keys, choosing the scopes it needs; for this guide that is iot.sims:read, iot.sims:write and, for eSIMs, iot.esim:read. The key is shown once, so store it somewhere safe. The full details are in the developer overview and the API reference.

export THINGSIM_API_KEY="your key"

List your SIMs

SIMs are identified by their ICCID, the number printed on the card. List them to find the one you are installing:

curl "https://partners.netavo.com/api/v1/iot/sims?limit=5" \
  -H "Authorization: Bearer $THINGSIM_API_KEY"

You can filter the list by status or tag, or use search.

Activate a SIM when its device goes live

SIMs arrive inactive and billing starts the day each one is switched on, so the natural moment to activate is when the device is installed and tested. Send a unique Idempotency-Key with each activation, and reuse the same value if you retry, so a dropped connection never activates twice:

curl -X POST "https://partners.netavo.com/api/v1/iot/sims/8944000000000000000/activate" \
  -H "Authorization: Bearer $THINGSIM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Label it while you know where it went

Each SIM can carry a label and tags. Set them at install time so the SIM can be found and filtered later:

curl -X PATCH "https://partners.netavo.com/api/v1/iot/sims/8944000000000000000" \
  -H "Authorization: Bearer $THINGSIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "Unit 4 gate camera", "tags": ["site-leeds", "camera"]}'

Fetch an eSIM code without a QR scan

For devices that take an eSIM, the activation code is available directly, so a provisioning script can load it onto the device:

curl "https://partners.netavo.com/api/v1/iot/sims/8944000000000000000/esim" \
  -H "Authorization: Bearer $THINGSIM_API_KEY"

Other controls you will want

The same API pauses and resumes SIMs, changes plans (POST .../plan with a plan id from GET /v1/iot/plans), reads usage and sessions, and ceases SIMs that are retired. Ceasing needs its own scope, iot.sims:cease, so a key used by an installer's app cannot permanently cease SIMs by mistake. Give each key only the scopes it needs.

To hear about events instead of polling for them, such as a SIM activating or nearing its allowance, use webhooks: see usage webhooks. For keeping a fleet tidy, see running a small fleet of SIMs.

Common questions

Is the API different from the portal?

No. It is the same API the portal uses, so anything you can do to a SIM in the portal you can automate.

What stops a retried request activating a SIM twice?

The Idempotency-Key header. Send a new unique value with each action and the same value when retrying it, and the API carries out the action once.

Can an API key be limited to certain actions?

Yes. Keys have scopes; ceasing a SIM, for example, needs the separate iot.sims:cease scope, so give each key only what it needs.