API reference

BillingInterval enum

How often a plan can be billed.

monthly annual

Coverage object

Which networks a plan can use.

• key string required
  The coverage's id; filter plans by it with ?coverage=.

  Example 3e8d1c5a-7f2b-4a90-b6e4-1d0c9f8a2b37

• label string required

  Example UK 4-network

• networks string[] required
  The UK networks it permits.

  Example ["EE","O2","Three","Vodafone"]

EsimActivation object

What a device needs to download its eSIM profile.

• iccid string required

  Example 8944110068298765432

• activationCode string required
  The full LPA string, as encoded in the QR code.

  Example LPA:1$smdp.example.net$K2-4N7Q2-1XZ9PQ

• smdpAddress string required

  Example smdp.example.net

• matchingId string required

  Example K2-4N7Q2-1XZ9PQ

• qrCodeSvg string required
  The QR code as an SVG document, ready to show or print.

  Example <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 41 41">…</svg>

FormFactor enum

Physical form of the SIM.

triSim mff2 esim

Money object

An amount of money. amount is a decimal string so it never loses pennies.

• amount string required
  Decimal amount, two places.

  Example 2.40

• currency string required
  ISO 4217 currency code.

  Example GBP

• includesVat boolean required
  Whether amount includes VAT. Prices are quoted ex VAT.

  Example false

Network object

A mobile network.

• mcc string or null
  Mobile country code.

  Example 234

• mnc string or null
  Mobile network code.

  Example 15

• name string or null

  Example Vodafone UK

Plan object

A plan your account can use, at your price.

• id string required
  Pass as planId to change a SIM's plan.

  Example 5b0e4f2a-8c1d-4e6f-9a3b-7d2c1e0f4a61

• name string required

  Example 1 GB, UK 4-network

• coverage Coverage or null
  The networks it can use; null when the plan names none.
• allowanceBytes integer required

  Example 1073741824

• monthlyPrice Money required
  Your price per month, ex VAT.
• billingIntervals BillingInterval[] required

  One of monthly annual

PlanChange object

The outcome of a plan change. Upgrades apply now and are prorated; downgrades apply at the next renewal.

• iccid string required

  Example 8944110068212345678

• fromPlan PlanSummary or null
  The plan before the change; null for a SIM that had none.
• toPlan PlanSummary required
  The plan a SIM is on.
• direction PlanChangeDirection required
  Whether a plan change is an upgrade (now) or a downgrade (at renewal).

  One of upgrade downgrade

• effectiveAt string (date-time) required
  When the new plan takes effect: now for an upgrade, the next renewal for a downgrade.

  Example 2026-09-25T00:00:00Z

• message string or null
  What we did, in words.

  Example Upgraded to 5 GB, UK 4-network; the difference for the rest of the period is charged now.

PlanChangeDirection enum

Whether a plan change is an upgrade (now) or a downgrade (at renewal).

upgrade downgrade

PlanChangeRequest object

The plan to move the SIM to.

• planId string required
  A plan id from GET /v1/iot/plans.

  Example 9c7a2e14-3b5d-4f60-8e21-6a4b0d9c3f75

PlanList object

Every plan available to your account. Not paginated.

• data Plan[] required

PlanSummary object

The plan a SIM is on.

• id string required
  Plan id, as listed by GET /v1/iot/plans.

  Example 5b0e4f2a-8c1d-4e6f-9a3b-7d2c1e0f4a61

• name string required

  Example 1 GB, UK 4-network

• allowanceBytes integer required
  Data included each month, in bytes.

  Example 1073741824

Problem object

An RFC 9457 problem document. type and code are stable; title and detail are for people.

• type string
  Identifies the kind of problem.

  Example https://partners.netavo.com/api/problems/not-found

• title string
  Short, human-readable summary of the problem type.

  Example Not found

• status integer
  The HTTP status code.

  Example 404

• detail string or null
  What went wrong with this request.

  Example No SIM with ICCID 8944110068212345678 in your account.

• instance string or null
  The request path.

  Example /api/v1/iot/sims/8944110068212345678

• code string
  Stable machine-readable code, the last segment of type.

  Example not-found

• traceId string or null
  Quote this if you contact support.

  Example 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

• errors map of string[] or null
  Per-field messages when code is validation-failed.

ScheduledPlanChange object

A plan change that takes effect later — a downgrade waits for the next renewal.

• plan PlanSummary required
  The plan a SIM is on.
• effectiveAt string (date-time) required

  Example 2026-10-01T00:00:00Z

Session object

One data session: from the device attaching to the network to it detaching.

• id string required

  Example ses_4f1c2a9e7b3d

• iccid string required

  Example 8944110068212345678

• startedAt string (date-time) or null

  Example 2026-09-25T06:02:41Z

• endedAt string (date-time) or null
  Null while the session is open.

  Example 2026-09-25T08:47:12Z

• bytesUp integer required
  Bytes sent by the device.

  Example 1843200

• bytesDown integer required
  Bytes received by the device.

  Example 7340032

• network Network or null
  The network the device was on, when the network reported it.
• radioAccess string or null
  2G, 3G, 4G, 5G, LTE-M or NB-IoT, when the network reported it.

  Example 4G

• ipAddress string or null

  Example 10.64.12.34

• endReason string or null
  Why the session ended, when the network says.

  Example userRequest

SessionList object

A page of results. Follow nextCursor for the next one.

• data Session[] required
  This page of results.
• hasMore boolean required
  Whether another page follows.

  Example true

• nextCursor string or null
  Pass as startingAfter to get the next page. Null on the last page.

  Example c2ltXzg5NDQxMTAwNjgyMTIzNDU2Nzg

Sim object

A SIM in your account.

• iccid string required
  The SIM's ICCID. Its identifier everywhere in the API.

  Example 8944110068212345678

• label string or null
  Your name for the SIM or the device it is in.

  Example Car park barrier 3

• tags string[] required
  Your tags, for filtering.

  Example ["site:leeds","barrier"]

• status SimStatus required
  Where the SIM is in its lifecycle. pending… states mean the network is still applying a change; a notification follows when it takes effect.

  One of inactive pendingActivation active pendingPause paused pendingResume suspended pendingCease ceased

• suspendedReason SuspendedReason or null
  Set when status is paused, pendingPause or suspended.

  One of customerPause allowanceReached nonPayment provider

• canResume boolean required
  Whether POST …/resume would succeed: the SIM is paused by you. False for every other state, including a suspension only we can lift.

  Example false

• formFactor FormFactor required
  Physical form of the SIM.

  One of triSim mff2 esim

• plan PlanSummary or null
  The plan the SIM is on; null for a SIM with no plan yet.
• msisdn string or null
  The SIM's number, in international format without +.

  Example 447700900123

• imsi string or null

  Example 234500012345678

• ipAddress string or null
  The SIM's private IP address on the network.

  Example 10.64.12.34

• organisationId string (uuid) required
  The organisation that owns the SIM. Partners see SIMs across their customers.

  Example 0f8b6c1e-5a2d-4c7e-9b3a-2d1e6f4a7c90

• activatedAt string (date-time) or null
  When the SIM was first activated. Billing starts here.

  Example 2026-09-01T08:15:00Z

• activationScheduledFor string (date-time) or null
  For a SIM awaiting activation: the day the network activates it. Activation runs on the next working day after it is requested.
• stopsAt string (date-time) or null
  When a ceased SIM stops passing data: the end of the period already paid for. Null unless a cease is pending.
• createdAt string (date-time) required

  Example 2026-08-20T14:02:11Z

• updatedAt string (date-time) required

  Example 2026-09-24T17:40:03Z

• canActivate boolean required
  Whether the SIM can be activated now: it has never been started and has a plan.

  Example false

• planStartedAt string (date-time) or null
  When the SIM's current plan started; null before activation.

  Example 2026-09-01T00:00:00Z

• scheduledPlanChange ScheduledPlanChange or null
  A downgrade waiting for the next renewal: the plan it moves to and when. Null when none is scheduled.

SimCeaseRequest object

Confirms which SIM to cease, because ceasing cannot be undone.

• confirmIccid string required
  Must equal the ICCID in the path.

  Example 8944110068212345678

• reason string or null
  Your note, kept in our logs of the SIM's history.

  Example Barrier removed

SimList object

A page of results. Follow nextCursor for the next one.

• data Sim[] required
  This page of results.
• hasMore boolean required
  Whether another page follows.

  Example true

• nextCursor string or null
  Pass as startingAfter to get the next page. Null on the last page.

  Example c2ltXzg5NDQxMTAwNjgyMTIzNDU2Nzg

SimStatus enum

Where the SIM is in its lifecycle. pending… states mean the network is still applying a change; a notification follows when it takes effect.

inactive pendingActivation active pendingPause paused pendingResume suspended pendingCease ceased

SimUpdate object

Fields to change. Leave a field out (or null) to keep it.

• label string or null
  New label; "" clears it. Null or left out keeps it (so a client that always sends every field cannot wipe a label by accident).

  Example Car park barrier 3

• tags string[] or null
  Replaces all tags; [] removes them. Null or left out keeps them.

  Example ["site:leeds","barrier"]

SimUsage object

Data used by one SIM in one allowance period.

• iccid string required

  Example 8944110068212345678

• periodStart string (date-time) required

  Example 2026-09-01T00:00:00Z

• periodEnd string (date-time) required

  Example 2026-10-01T00:00:00Z

• allowanceBytes integer required

  Example 1073741824

• usedBytes integer required
  For the current period, includes sessions still open.

  Example 612368384

• remainingBytes integer required

  Example 461373440

• percentUsed number required

  Example 57

• allowanceReached boolean required
  True once the SIM has paused for using its whole allowance this period.

  Example false

• updatedAt string (date-time) required
  When usage was last counted. Up to 15 minutes behind live traffic.

  Example 2026-09-25T09:15:00Z

• history SimUsagePeriod[] required
  Earlier periods, newest first (up to twelve). Only on the current period's response.

SimUsagePeriod object

A past allowance period's totals.

• periodStart string (date-time) required

  Example 2026-08-01T00:00:00Z

• periodEnd string (date-time) required

  Example 2026-09-01T00:00:00Z

• allowanceBytes integer required

  Example 1073741824

• usedBytes integer required

  Example 803209216

SimUsageSummary object

One SIM's data use in its current allowance period, as the fleet usage list reports it.

• iccid string required

  Example 8944110068212345678

• allowanceBytes integer required
  The current allowance period's data allowance; 0 when the SIM has no plan.

  Example 1073741824

• usedBytes integer required
  Data used so far this period, including the session still open.

  Example 52428800

• barredUntil string (date-time) or null
  Set while the SIM is stopped for having used its allowance: when it starts working again (the allowance resets). Null when it is not barred.
• online boolean required
  Whether the SIM has a data session open now.

  Example true

SimUsageSummaryList object

A page of results. Follow nextCursor for the next one.

• data SimUsageSummary[] required
  This page of results.
• hasMore boolean required
  Whether another page follows.

  Example true

• nextCursor string or null
  Pass as startingAfter to get the next page. Null on the last page.

  Example c2ltXzg5NDQxMTAwNjgyMTIzNDU2Nzg

SuspendedReason enum

Why a paused or suspended SIM is not passing data. Only customerPause can be resumed through the API.

customerPause allowanceReached nonPayment provider

ApiKey object

An API key. The secret is never returned after creation.

• id string
  The key's id, key_….

  Example key_0192a4c3e5f67b8d9e0f1a2b3c4d5e6f

• name string
  What the key is for.

  Example Fleet dashboard

• scopes string[]
  The scopes the key may use.

  Example ["iot.sims:read","iot.usage:read"]

• status string
  active, expired or revoked.

  Example active

• allowedIpRanges string[]
  Source addresses and CIDR ranges the key is limited to; empty for anywhere.

  Example ["203.0.113.0/24"]

• createdAt string (date-time)

  Example 2026-09-25T10:00:00Z

• expiresAt string (date-time)

  Example 2027-09-25T10:00:00Z

• lastUsedAt string (date-time) or null
  When the key was last used, to the nearest few minutes; null if never.

  Example 2026-09-25T11:30:00Z

• revokedAt string (date-time) or null
  When the key was revoked; null unless it has been.

ApiKeyCreate object

A new API key.

• name string required
  What the key is for, so you can recognise it later.

  Example Fleet dashboard

• scopes string[] required
  The scopes the key may use. Each must be one the calling credential holds itself: a key can never do more than the key that created it.

  Example ["iot.sims:read","iot.usage:read"]

• expiresAt string (date-time) or null
  When the key stops working, at most a year ahead (and no later than the calling key's own expiry). Leave out for a year.

  Example 2027-03-31T00:00:00Z

• allowedIpRanges string[] or null
  Limit the key to these source addresses or CIDR ranges. Leave out for anywhere — unless the calling key is itself limited, in which case the new key inherits its limits and may only narrow them.

  Example ["203.0.113.0/24"]

ApiKeyCreated object

A created key and its secret.

• apiKey ApiKey
  An API key. The secret is never returned after creation.
• secret string
  The key itself — send it as Authorization: Bearer …. Shown only in this response: store it now; it cannot be read back.

  Example eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.…

ApiKeyList object

The organisation's API keys.

• data ApiKey[]
  Newest first.

BrandingResponse object

API response model for organisation branding information Includes inline SVG logo content for authenticated users and extensions

• organisationId string (uuid)
  Organisation ID that owns this branding
• organisationName string or null
  Organisation name to display in the application
• primaryColor string or null
  Primary brand color (hex format, e.g., #5A66F1)
• secondaryColor string or null
  Secondary brand color (hex format, e.g., #60A5FA)
• supportPhone string or null
  Support contact phone number
• supportEmail string or null
  Support contact email address
• logoSvg string or null
  SVG logo content inline (full SVG markup)
• isInherited boolean
  Indicates if this branding is inherited from a parent organisation

BrandingResponseApiResponse object

Standard API response envelope for success responses

• success boolean
• data BrandingResponse
  API response model for organisation branding information Includes inline SVG logo content for authenticated users and extensions
• message string or null

ErrorDetail object

• code string
• message string
• details map of string[] or null

ErrorResponse object

Standard API response for error cases

• success boolean
• error ErrorDetail

EventList object

A page of results. Follow nextCursor for the next one.

• data WebhookEvent[] required
  This page of results.
• hasMore boolean required
  Whether another page follows.

  Example false

• nextCursor string or null
  Pass as startingAfter to get the next page. Null on the last page.

NotificationChannel enum

Ways a notification can reach a customer.

webhook email portal

NotificationType object

One entry in the notification catalogue.

• type string required

  Example iot.sim.allowance_reached

• serviceArea ServiceArea required
  The product area a notification belongs to; platform is the account itself.

  One of voice connectivity hosting iot platform

• description string required

  Example A SIM used its whole data allowance for the period and has stopped passing data.

• optIn boolean required
  High-volume types are only sent to webhooks that name them in types.

  Example false

• available boolean required
  False for a type that is catalogued (so it can be subscribed to and documented) but not yet raised by anything. Subscribing to it is allowed; nothing arrives until it is.

  Example true

• channels NotificationChannel[] required

  One of webhook email portal

• examplePayload object required
  An example of the type's data object.

NotificationTypeList object

The notification catalogue, filtered to the service areas your account has.

• data NotificationType[] required

Problem object

An RFC 9457 problem document. type and code are stable; title and detail are for people.

• type string
  Identifies the kind of problem.

  Example https://partners.netavo.com/api/problems/not-found

• title string
  Short, human-readable summary of the problem type.

  Example Not found

• status integer
  The HTTP status code.

  Example 404

• detail string or null
  What went wrong with this request.

  Example No SIM with ICCID 8944110068212345678 in your account.

• instance string or null
  The request path.

  Example /api/v1/iot/sims/8944110068212345678

• code string
  Stable machine-readable code, the last segment of type.

  Example not-found

• traceId string or null
  Quote this if you contact support.

  Example 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

• errors map of string[] or null
  Per-field messages when code is validation-failed.

SecretRotation object

A new signing secret. Events are signed with both secrets until previousSecretExpiresAt.

• signingSecret string required

  Example whsec_9pD2kR5tV8xA1cF4hJ7mN0qS3uW6yZ9b

• previousSecretExpiresAt string (date-time) required
  Events are signed with both secrets until then.

  Example 2026-09-26T09:30:00Z

ServiceArea enum

The product area a notification belongs to; platform is the account itself.

voice connectivity hosting iot platform

TestEventResult object

The test event that was queued.

• eventId string required
  The event's id; find its delivery in the webhook's delivery log.

  Example evt_0192a4c3e5f67b8d9e0f1a2b3c4d5e70

Webhook object

A webhook endpoint.

• id string required
  The webhook's id, wh_….

  Example wh_0192a4c3e5f67b8d9e0f1a2b3c4d5e6f

• organisationId string (uuid) required
  The organisation that owns the webhook.

  Example 0f8b6c1e-5a2d-4c7e-9b3a-2d1e6f4a7c90

• url string required
  Where we POST events. HTTPS on a public address; redirects are not followed.

  Example https://example.com/hooks/thingsim

• description string or null

  Example Ops alerts

• types string[] required
  Notification types to send. Empty with empty serviceAreas means every type your account can receive, except opt-in types.

  Example ["iot.sim.allowance_reached","iot.sim.usage_threshold"]

• serviceAreas ServiceArea[] required
  Send every type in these service areas.

  One of voice connectivity hosting iot platform

• includeSubtree boolean required
  Partners: also send events for customer organisations below you.

  Example false

• enabled boolean required

  Example true

• status string required
  active, failing while deliveries are being retried, or disabled (switched off, or after a day of failures).

  Example active

• disabledReason string or null
  Why a disabled webhook was switched off.
• createdAt string (date-time) required

  Example 2026-09-20T10:00:00Z

• updatedAt string (date-time) required

  Example 2026-09-20T10:00:00Z

WebhookCreate object

A new webhook endpoint.

• url string required
  Where we POST events. HTTPS on a public address; redirects are not followed.

  Example https://example.com/hooks/thingsim

• description string or null

  Example Ops alerts

• types string[] or null
  Notification types to send. Leave out (with serviceAreas) for every type your account can receive, except opt-in types.

  Example ["iot.sim.allowance_reached","iot.sim.usage_threshold"]

• serviceAreas ServiceArea[] or null
  Send every type in these service areas.

  One of voice connectivity hosting iot platform

• includeSubtree boolean or null
  Partners: also send events for customer organisations below you. Null or left out is false.

  Example false

• organisationId string (uuid) or null
  Partners: create the webhook for a customer organisation below you. Defaults to your own organisation.

WebhookCreated object

The new webhook and its signing secret. The secret is only ever returned here and by rotate-secret: store it now.

• webhook Webhook required
  A webhook endpoint.
• signingSecret string required
  Verifies the Webhook-Signature header.

  Example whsec_3yJ8mQ2vN6pR9tW1zC4fH7kL0sX5bE8g

WebhookDelivery object

One attempt to deliver an event to a webhook.

• id string required
  This attempt, dlv_…. Pass it to redeliver the event.

  Example dlv_0192a4c3e5f67b8d9e0f1a2b3c4d5e71

• eventId string required

  Example evt_0192a4c3e5f67b8d9e0f1a2b3c4d5e72

• eventType string required

  Example iot.sim.allowance_reached

• attempt integer required

  Example 1

• outcome string required
  succeeded, failed or pending (queued, not yet attempted).

  Example succeeded

• responseStatus integer or null
  Your endpoint's HTTP status; null if it could not be reached.

  Example 200

• durationMs integer required

  Example 184

• error string or null
• attemptedAt string (date-time) required

  Example 2026-09-25T09:12:45Z

• nextAttemptAt string (date-time) or null
  When a failed delivery will be retried.

WebhookDeliveryList object

A page of results. Follow nextCursor for the next one.

• data WebhookDelivery[] required
  This page of results.
• hasMore boolean required
  Whether another page follows.

  Example false

• nextCursor string or null
  Pass as startingAfter to get the next page. Null on the last page.

WebhookEvent object

The body of every webhook POST, and an item in the event log. data depends on type: see the notification catalogue.

• id string required
  evt_…. Unique per event; deliveries can repeat, so de-duplicate on it.

  Example evt_0192a4c3e5f67b8d9e0f1a2b3c4d5e72

• type string required
  The notification type.

  Example iot.sim.allowance_reached

• serviceArea ServiceArea required
  The product area a notification belongs to; platform is the account itself.

  One of voice connectivity hosting iot platform

• organisationId string (uuid) required
  The organisation the event is about.

  Example 0f8b6c1e-5a2d-4c7e-9b3a-2d1e6f4a7c90

• occurredAt string (date-time) required
  When the change took effect.

  Example 2026-09-25T09:12:44Z

• data object required
  The type's payload; see the notification catalogue.

  Example {"iccid":"8944110068212345678","label":"Car park barrier 3","planId":"5b0e4f2a-8c1d-4e6f-9a3b-7d2c1e0f4a61","allowanceBytes":1073741824,"usedBytes":1073741824,"periodEnd":"2026-10-01T00:00:00Z"}

WebhookList object

A page of results. Follow nextCursor for the next one.

• data Webhook[] required
  This page of results.
• hasMore boolean required
  Whether another page follows.

  Example false

• nextCursor string or null
  Pass as startingAfter to get the next page. Null on the last page.

WebhookUpdate object

Fields to change. Leave a field out to keep it.

• url string or null
  Where we POST events. HTTPS on a public address; redirects are not followed.

  Example https://example.com/hooks/thingsim

• description string or null

  Example Ops alerts

• types string[] or null
  Replaces the types sent.

  Example ["iot.sim.allowance_reached"]

• serviceAreas ServiceArea[] or null
  Replaces the service areas sent.

  One of voice connectivity hosting iot platform

• includeSubtree boolean or null

  Example false

• enabled boolean or null
  Re-enabling a disabled webhook resets its failure count.

  Example true