canonical: https://jentic.com/apis/1nceapi/main

# 1NCE API

The 1NCE API manages cellular connectivity for IoT devices, letting you activate and configure SIM cards, top up their data volume, send and receive SMS, and track quota, usage, and network events by ICCID. It also exposes connectivity orders, available products, and support service requests, all authenticated with OAuth2 client credentials. Built for machine-to-machine deployments, it identifies each SIM by its ICCID and returns status, location, and diagnostic information for remote fleets.

## For AI agents

Manage 1NCE IoT SIM connectivity: activate and configure SIM cards, top up data, send and receive SMS, and check quota, usage, and connectivity status by ICCID. Authenticates with OAuth2 client credentials.

## Scope

Does not handle device firmware, hardware provisioning, or non-cellular connectivity like WiFi or Bluetooth. Use for 1NCE cellular SIM connectivity management only.

## Capabilities

- Activate, deactivate, label, and IMEI-lock SIM cards for IoT devices
- Top up the data volume of individual SIMs or batches of SIMs
- Retrieve a SIM's data quota, SMS quota, daily usage, and connectivity status
- Send SMS to a SIM, list received messages, and cancel undelivered ones
- Look up connectivity information and events for a SIM by ICCID
- Place and track connectivity orders and open support service requests
- Transfer SIMs between customers and configure automatic top-ups

## Use cases

### Agent-Managed IoT Connectivity

An AI agent monitors a fleet of 1NCE SIMs, tops up a SIM's data before it runs dry, and toggles activation as devices are deployed or retired, without an operator opening the 1NCE portal. Through Jentic the agent discovers the SIM, quota, and top-up operations by intent and calls them with stored OAuth2 credentials.

Example prompt: Check the data quota for a SIM by its ICCID and top up its data volume if the remaining quota is low

### SIM Lifecycle Automation

Device manufacturers activate SIMs at the point of shipment, label them to match asset records, apply an IMEI lock to bind a SIM to its hardware, and deactivate SIMs when devices are decommissioned. Status and event history for each SIM are available by ICCID for auditing.

Example prompt: Activate a SIM identified by its ICCID, set a label matching the device serial number, and apply an IMEI lock

### Device SMS and Diagnostics

IoT platforms send SMS commands to remote devices, read the SMS a device has sent back, and cancel messages still buffered for delivery. Network event history and connectivity information help diagnose why a device has dropped off the network.

Example prompt: Submit an SMS to a device by its ICCID, then list the SMS sent and received by that SIM to confirm delivery

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/sims` | List SIMs |
| GET | `/v1/sims/{iccid}` | Get status information for a SIM |
| PUT | `/v1/sims/{iccid}` | Update a SIM (activate, deactivate, label, IMEI lock) |
| POST | `/v1/sims/topup` | Top up the data volume of SIMs |
| GET | `/v1/sims/{iccid}/quota/data` | Get a SIM's data quota |
| POST | `/v1/sims/{iccid}/sms` | Submit an SMS to a SIM |
| GET | `/v1/orders` | List orders |
| GET | `/v1/products` | List products |

## Key resources

- **SIMs** — Activate, configure, top up, and inspect SIM cards by ICCID
- **Orders** — Place and track connectivity orders
- **Products** — List the connectivity products available to your account
- **Support** — Open and track support service requests

## Why Jentic

- **Setup:** Wiring the 1NCE API by hand means running the OAuth2 client-credentials flow against its token endpoint, refreshing tokens, and tracking SIMs by ICCID yourself. Through Jentic you install once, import 1NCE from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** 1NCE identifies SIMs by ICCID in the URL path (`/v1/sims/{iccid}` and its sub-resources), so a rule can pin your agent to the operations for one SIM. You choose the operations it may call, so destructive ones like SIM deactivation or transfer are not included unless you add them.
- **Credential handling:** Your 1NCE OAuth2 credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'top up a SIM' or 'check SIM data quota', and Jentic returns the matching 1NCE operation with its input schema so the agent calls the right endpoint without reading the reference docs.

## Related APIs

- **Twilio Super SIM** — Global IoT SIM connectivity and fleet management from Twilio
- **Twilio Wireless** — Programmable wireless SIMs with usage and command APIs
- **Particle** — IoT device platform with cellular hardware, firmware, and cloud
- **Adafruit IO** — Cloud service for storing and visualizing IoT device data

## FAQ

### What authentication does the 1NCE API use?

The 1NCE API authenticates with OAuth2 using the client-credentials flow per its OpenAPI spec: your agent exchanges a client id and secret for a bearer token at the token endpoint, then sends that token on each request. Through Jentic the credential is stored encrypted by your own Jentic One instance and injected at call time, so it never enters the agent's prompt or logs.

### Can I top up a SIM's data volume with the 1NCE API?

Yes. One operation tops up the data volume for a batch of SIMs and another tops up a single SIM identified by its ICCID, so an agent can add data to a device that is about to run out. You can also read a SIM's remaining data quota first to decide whether a top-up is needed.

### Can I limit what my agent is allowed to do with 1NCE?

Yes. Write a rule that allows only the SIM read and top-up operations for one ICCID, so your agent can check quota and add data for that device and touch nothing else, and every call it makes is logged.

### What are the rate limits for the 1NCE API?

The OpenAPI spec does not specify rate limits. Check the 1NCE documentation at https://1nce.com for current limits before running an agent at high volume against the SIM and SMS endpoints.

### How do I top up a SIM through Jentic?

Search Jentic for the intent 'top up a SIM', which returns the top-up operation and its input schema; the agent then submits the ICCID and the data volume to add. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Is there a 1NCE MCP server?

You don't need an MCP server to give your agent the 1NCE API. Jentic connects it directly from the API Directory: import it, store your OAuth2 credential once, and your agent calls the SIM, quota, and SMS operations. Because operations are discovered on demand, no extra tool definitions are loaded into the agent's context.