Migrate from 1NCE to Hologram - Hologram Documentation

This guide maps each 1NCE Management API operation to its Hologram equivalent. It covers authentication, endpoint paths, parameter names, identifier schemes, status values, and features that differ between the two platforms.

Core terminology differences

Clarification: Both Hologram and 1NCE APIs return SIM-level information, even for device endpoints. For purposes of this guide, we will use the term “SIM” in all cases, even for device endpoints.

One of the most important difference between 1NCE and Hologram is SIM structure. Both platforms have the concept of a SIM wrapped by a “device”, and the device effectively is a 1:1 with the SIM in API endpoints. However, 1NCE identifies the SIM by its ICCID and offers single-profile SIMs only. Hologram SIMs can have multiple installed profiles and are identified by the SIM ID, Device ID, or the EID (eUICCID). ICCIDs are profile-level identifiers and can change if profiles are added, removed, or fall back on a SIM. In the Hologram v1 API, profiles are represented by link objects in the links.cellular[] array. If you use Conductor or over-the-air eUICC updates, you may run into cases where the ICCID printed on a physical SIM card is no longer present on the SIM.

1NCE ID	Hologram equivalent	Notes
SIM / Device	SIM / Device	Hologram’s primary entity in the v1 API is a customer “device”, which wraps the SIM but is effectively a 1:1 with the SIM in API endpoints
ICCID	ICCID, the `sim` field inside `links.cellular[]`	Hologram SIMs are addressed by integer device IDs, not ICCIDs. ICCID is a profile-level value, and SIMs can have multiple installed profiles

Label	Name (`name`)	The human-readable name for a SIM/device
Status	Status and network state (`state`)	Different values; see SIM/device states below
Data quota	Data limit (`overagelimit`)	1NCE has a bucket that decrements; Hologram sets a cap in bytes
Top up	Not applicable	Hologram uses usage-based billing,
Account	Organization (`orgid`)	Hologram supports multiple orgs per account

Endpoint paths

All Hologram API endpoints in this guide are relative to the base URL https://dashboard.hologram.io/api/1. Full reference documentation is at docs.hologram.io/api/v1. An MCP reference of the Hologram API is available at https://docs.hologram.io/mcp. The 1NCE paths shown (e.g. /v1/sims) are relative to https://api.1nce.com/management-api; 1NCE OS paths (e.g. /v1/integrate/..., /v1/locate/...) live under the same base. These are provided for orientation — always confirm against 1NCE’s API reference, as 1NCE controls and may change them.

Authentication

1NCE
Hologram

1NCE uses OAuth 2.0 client credentials. You first exchange your credentials for a Bearer token, then pass that token on every subsequent request. The token request itself is authenticated with HTTP Basic — the base64 of client_id:client_secret — so it’s easy to omit that header and get a 401.

# Step 1: Get a token (Basic auth = base64(client_id:client_secret))
curl -X POST https://api.1nce.com/management-api/oauth/token \
  -H "Authorization: Basic BASE64_CLIENT_ID_AND_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "grant_type": "client_credentials" }'

# Step 2: Use the returned access_token
Authorization: Bearer YOUR_ACCESS_TOKEN

Tokens expire (the response includes expires_in, currently 3600 seconds). Monitor it and refresh proactively.

Hologram uses HTTP Basic Auth with a static API key — no token exchange, no expiry.

curl https://dashboard.hologram.io/api/1/users/me \
  -u apikey:YOUR_API_KEY

Your API key is available in the Hologram Dashboard under Settings → API. You can also base64-encode apikey:YOUR_API_KEY and pass it as an Authorization: Basic header.

Key difference: Hologram’s approach is simpler — one credential, no refresh logic. If you have code that handles token rotation for 1NCE, you can remove it entirely.

SIM states

1NCE and Hologram use different status and state terminology. Read a full breakdown of Hologram SIM statuses and states. The two platforms model this differently: 1NCE’s SIM status field has only two values (Enabled and Disabled); everything else (expiry, deletion) is a lifecycle outcome, not a status. Hologram exposes a richer set of statuses and states, and does not have the concept of a SIM “lifetime.” Once SIMs are activated they remain active until you choose to deactivate them.

1NCE	Hologram status and state	Notes
`Enabled` (status)	Ready `LIVE`	SIM is active and can pass data
`Disabled` (status)	Paused by user `PAUSED-USER`	Manually disabled. SIM is billed monthly but cannot use data
no equivalent	Paused by system `PAUSED-SYS`	Paused by Hologram (e.g., balance issue); cannot be resumed by the API
no equivalent	In testing `TEST-ACTIVATE`	SIM is configured with Test Mode and free data, not yet active
Expired / deleted SIM (lifecycle, irreversible)	Deactivated `DEAD`	Permanent, irreversible — SIM is off the network

1NCE’s status field returns only Enabled or Disabled. A 1NCE SIM does not become permanently “deleted” through a status change — deletion is what happens once a SIM’s activation period (10-year IoT Lifetime Flat) ends. You can extend a SIM’s lifetime before it expires with POST /v1/sims/{iccid}/extend.

Caution: Hologram’s Deactivated (DEAD) status is permanent and irreversible, but is an action you take manually. Do not deactivate SIMs unless you intend to retire them permanently. 1NCE SIMs have a set lifecycle with an expiration date that you can extend, but are automatically deactivated at the end of the lifecycle.

List all SIMs

1NCE
Hologram

1NCE identifies each SIM in the path by its ICCID.

GET /v1/sims?page=1&pageSize=100

Pagination uses page and pageSize query params (max pageSize is 100). Response headers X-Total-Count, X-Total-Pages, X-Count-Per-Page, and X-Current-Page describe the result set.Each SIM object returns fields including: iccid, imsi, msisdn, status, label, ip_address, quota_status, and activation_date. (Quota expiry is returned by the quota endpoint, not on the SIM object — see Get data usage / quota.)

GET /devices?orgid=YOUR_ORG_ID&limit=100

Pagination is cursor-based. Use limit and startafter (the lastid from the previous response). The response body includes a links.next URL for the next page.Each device object returns: id, name, orgid, imei, phonenumber, is_hyper, and a links.cellular[] array where each entry has sim (ICCID), imsi, msisdn, state, overagelimit, whencreated.Filtering: use states, sim, imsi, imei, tagid, or tagname query params.Hologram returns an integer id (the device ID), and identifies SIMs by the device ID and the SIM ID since Hologram SIMs can have multiple installed profiles, returned within the links object on a device object. To find a Hologram device by ICCID:

GET /devices?sim=8988280666000012345

Get a single SIM

1NCE
Hologram

GET /v1/sims/:iccid

Returns SIM detail including status, label, quota information, IP address, activation/expiry dates.

GET /devices/:deviceId

Returns device detail including all links.cellular[] profiles. The ICCID is at links.cellular[0].sim.To look up by ICCID instead of device ID:

GET /devices?sim=89882806660000123456

This returns the matching device(s) — use data[0].id as your device ID going forward.

Key difference: 1NCE’s SIM status, quota, and connectivity are available on the single-SIM endpoint. In Hologram, the device object includes state and link info. Data quota/usage requires a separate call to /usage/data/.

Check SIM status and connectivity

1NCE
Hologram

GET /v1/sims/:iccid/status
GET /v1/sims/:iccid/connectivity_info

Two separate endpoints: status for the administrative status, and connectivity_info for the current network attachment (network, IP, last seen).

GET /devices/:deviceId

Both administrative state and last-known session are in the device object:

links.cellular[0].state — administrative state (LIVE, PAUSED-USER, etc.)
The device object also includes imei, last session carrier, and the device’s last known state

For active session detail and approximate location, use:

GET /usage/data/?linkid=LINK_ID&limit=1

The linkid is links.cellular[0].id from the device object.

Pause (disable) or resume (enable) a SIM

1NCE
Hologram

# Disable (single)
PUT /v1/sims/:iccid
{ "status": "Disabled" }

# Enable (single)

PUT /v1/sims/:iccid
{ "status": "Enabled" }

# Bulk

POST /v1/sims
[ { "iccid": "...", "status": "Enabled" }, ... ]

POST /devices/batch/state
{
  "state": "pause",        # or "live" to resume
  "deviceids": [123, 456]
}

The state field accepts pause, live, or deactivate. This always operates as a batch — pass one or many device IDs. The response returns a jobid; use GET /devices/batch/state?orgid=YOUR_ORG_ID to check job status for large batches.

Key difference: 1NCE has per-SIM PUT endpoints and a bulk POST. Hologram uses a single bulk endpoint for all state changes. Always pass deviceids, even for a single device.

Activate SIMs

1NCE
Hologram

SIMs ship pre-associated with your account on the IoT Lifetime Flat plan. Activation is managed through the portal or the order flow — there is no “activate by ICCID” endpoint in the management API.

POST /links/cellular/bulkclaim
{
  "sims": ["8988280666000012345", "8988280666000012346"],
  "plan": YOUR_PLAN_ID,
  "zone": "global",
  "overage_limit": -1
}

Or activate a range:

{
  "simrange": "89330123456789012345-89330123456789012365",
  "plan": YOUR_PLAN_ID,
  "zone": "global"
}

Also accepts eidrange for eUICC SIMs. Maximum 2,500 SIMs per request. plan and zone are required for live activations.

Key difference: Hologram requires explicit activation via the API or Dashboard, and requires a data plan and zone. You can pre-stage SIMs in Test Mode (preflight) without activating them, which is the equivalent of 1NCE’s unactivated inventory.

Get data usage / quota

1NCE
Hologram

# Remaining quota (1NCE's flat-rate bucket model)
GET /v1/sims/:iccid/quota/data

Returns a volume field (remaining data in the lifetime quota, in MB), total_volume, and expiry_date.

1NCE reports quota volume in megabytes, while Hologram’s overagelimit and all usage figures are in bytes. Convert when you port quota logic — multiply 1NCE MB values by 1,048,576 to get the Hologram byte equivalent.

# Historical usage
GET /v1/sims/:iccid/usage

Hologram does not have a pre-paid quota bucket. Instead, you query actual session data:

# Recent data sessions (last 3 months)
GET /usage/data/?linkid=LINK_ID

# Daily rollup
GET /usage/data/daily?linkid=LINK_ID

# Monthly rollup
GET /usage/data/monthly

# Per-SIM totals by billing period
GET /usage/data/billing?linkid=LINK_ID

# Org-level aggregate
GET /usage/data/total?orgid=YOUR_ORG_ID

linkid is links.cellular[0].id from the device object.To see the current data limit (the cap, not remaining): it’s in links.cellular[0].overagelimit on the device object. -1 means unlimited.

Key difference: 1NCE’s quota model has a finite bucket that counts down. Hologram charges per-session with a configurable overage cap. There is no “remaining quota” concept — instead you check usage against the cap you set.

Set data limits

1NCE
Hologram

# Get account-wide limits
GET /v1/sims/limits

# Set account-wide limits
POST /v1/sims/limits

# Get the selectable limits for a service (e.g. data, sms)
GET /v1/sims/:service/limits

POST /devices/batch/usagelimit
{
  "deviceids": [123, 456],
  "overagelimit": 10485760,   # bytes; -1 for unlimited
  "smslimit": -1
}

Limits are set in bytes. -1 disables the limit. Updates apply to all profiles on the SIM.

Get SMS quota

1NCE
Hologram

GET /v1/sims/:iccid/quota/sms

Returns remaining SMS count from the lifetime flat allocation.

The SMS limit is on the device: links.cellular[0].smslimit in the device object.Outbound SMS usage history:

GET /usage/sms/?orgid=YOUR_ORG_ID

Send an SMS to a SIM (cloud → device)

1NCE
Hologram

POST /v1/sims/:iccid/sms
{
  "payload": "Hello device",
  "dcs": 0
}

The message text is payload. Encoding is controlled by dcs (Data Coding Scheme): 0 for 7-bit GSM (default), 8 for UCS-2. Optional fields include source_address, udh, and expiry_date. There is no payload_encoding field.

POST /sms/incoming
{
  "deviceid": 123456,
  "body": "Hello device"
}

Or send to multiple SIMs at once:

{
  "deviceids": [123456, 789012],
  "body": "Hello fleet"
}

You can also target by phone number using the phonenumber field.

Terminology difference: 1NCE calls the message a payload. Hologram calls it body. Both accept plain text; Hologram also accepts base64body for binary content.

Get SMS history (MO/MT messages)

1NCE
Hologram

GET /v1/sims/:iccid/sms           # list MT and MO messages
GET /v1/sims/:iccid/sms/:sms_id   # single message detail
DELETE /v1/sims/:iccid/sms/:sms_id # cancel pending SMS

Inbound SMS messages from devices are delivered as cloud messaging events. There is no dedicated SMS history endpoint; messages appear in the event stream. See cloud messaging.

# Cloud/data messages from devices
GET /csr/data/?orgid=YOUR_ORG_ID

Send a data / cloud message to a SIM

1NCE
Hologram

1NCE’s core SIM Management API does not support sending arbitrary data to devices. Device-directed action requests are available in 1NCE OS via:

POST /os/v1/devices/:iccid/actions/udp
POST /os/v1/devices/:iccid/actions/coap
POST /os/v1/devices/:iccid/actions/lwm2m

Hologram supports two-way data messaging at the connectivity layer without requiring a separate platform tier:

POST /devices/messages
{
  "deviceids": [123456],
  "base64data": "SGVsbG8gZGV2aWNlCg==",   # base64-encoded payload
  "port": 4010,
  "protocol": "UDP"
}

Use base64data for binary/base64-encoded content, or data for plain text — send one, not both. protocol accepts TCP or UDP, port must be 1–65535, and the maximum payload is 10 KB. Messages are delivered over the device’s active cellular session.

Key difference: Hologram’s cloud messaging is a first-class feature of the base connectivity API. 1NCE’s equivalent is part of the separate 1NCE OS add-on and is protocol-specific (CoAP, LwM2M, UDP).

Rename a SIM

1NCE
Hologram

PUT /v1/sims/:iccid
{ "label": "sensor-unit-42" }

To rename a single device, PUT the device and set name:

PUT /devices/123456
{
  "name": "sensor-unit-42"
}

To rename many devices at once, use POST /devices/names. This endpoint is prefix-based — prefix is required, and Hologram appends the last 5 digits of each device’s ICCID in parentheses (e.g. sensor-unit-(12345)) unless you pass "skipPostfix": true:

POST /devices/names
{
  "deviceids": [123456, 789012],
  "prefix": "sensor-unit-"
}

POST /devices/names does not accept a single fixed name; it always builds names from prefix. Use PUT /devices/{deviceId} when you need to set an exact, unique name.

Reset connectivity

1NCE
Hologram

POST /v1/sims/:iccid/reset_connectivity

Forces the SIM to drop its current network attachment and re-register.

Data top-up

1NCE
Hologram

# Single SIM
POST /v1/sims/:iccid/topup

# Multiple SIMs

POST /v1/sims/topup
[{ "iccid": "...", "volume": 500 }, ...]

# Auto top-up

POST /v1/sims/:iccid/topup/auto

Adds data volume to the lifetime flat quota.

No equivalent. Hologram does not use a prepaid quota model. Your SIMs draw from your account balance on a pay as you go basis for data usage at per MB rates. You can optionally set an overage limit to prevent your SIMs from exceeding a certain amount of data usage by setting it in the UI or using the overagelimit parameter in the API.

POST /devices/batch/usagelimit
{
  "deviceids": [123456],
  "overagelimit": 104857600   # 100 MB in bytes
}

Account balance is managed separately in the Dashboard or billed via invoice.

SIM transfer

1NCE
Hologram

POST /v1/sims/transfer

Transfer SIMs to another 1NCE account.

POST /devices/transfer
{
  "deviceids": [123456],
  "orgid": TARGET_ORG_ID
}

The orgid field is the target organization that will receive the devices. Transfers devices between organizations within Hologram; the target organization must exist in your account. All devices in a single request must share the same source org, and a maximum of 3,000 devices can be transferred per request.

Device location

1NCE
Hologram

Location is available through 1NCE OS (separate add-on):

GET /os/v1/devices/:iccid/positions
GET /os/v1/devices/positions/latest

Uses cell tower triangulation and resolution.

GET /devices/locations?orgid=YOUR_ORG_ID

Returns the most recent approximate location for each device based on cell tower data — no add-on required. Location is also embedded in usage records when getlocationinfo=true:

GET /usage/data/?linkid=LINK_ID&getlocationinfo=true

Pagination comparison

	1NCE	Hologram
Style	Page-based	Cursor-based
Page param	`page`	`startafter` (last record ID)
Size param	`pageSize` (max 100)	`limit` (max 5000)
Total count	`X-Total-Count` header	Not returned
Total pages	`X-Total-Pages` header	Not returned
Next page	Increment `page`	Use `links.next` URL or pass `lastid` as `startafter`

API feature comparison

Feature	Hologram	1NCE
List SIMs / devices	✅	✅
Get single SIM / device	✅	✅
SIM state (enable/disable/deactivate)	✅	✅
Bulk state changes	✅	✅
Activate SIMs by ICCID	✅	✅ (portal/order flow)
Activate by ICCID range	✅	—
Activate by EID range (eUICC)	✅	—
Set data / SMS usage limits	✅	✅
Data usage history (sessions)	✅	✅
Daily / monthly usage rollups	✅	✅
Per-billing-period usage	✅	—
Data top-up / quota refill	—	✅
Send SMS to device	✅	✅
Receive SMS / MO history	— (event stream)	✅
Send data / cloud message	✅	✅ (1NCE OS)
Connectivity reset	✅ (pause/resume)	✅
Get device location	✅ (cell tower, built-in)	✅ (1NCE OS)
Geofencing	—	✅ (1NCE OS)
Location update / network refresh	Coming soon	✅
Alerts / event notifications	✅	—
Webhook integration	✅	✅ (1NCE OS)
AWS IoT integration	—	✅ (1NCE OS)
Tags / device grouping	✅	—
Rename devices	✅	✅
Device transfer between accounts	✅	✅
Multi-profile / eUICC management	✅ (Hyper SIM, Outage Protection)	—
Outage Protection (auto failover)	✅	—
Secure device tunneling (SSH)	✅ (Spacebridge)	—
Order management via API	—	✅
Support tickets via API	—	✅
Organization / user management	✅	—
Billing / transaction data via API	✅	—
Async job / change-request tracking	✅	—
API key rotation	✅	— (OAuth client credentials)
Published OpenAPI spec	✅	✅
MCP server	✅ (documentation only, `llms.txt`)	—

​Core terminology differences

​Endpoint paths

​Authentication

​SIM states

​List all SIMs

​Get a single SIM

​Check SIM status and connectivity

​Pause (disable) or resume (enable) a SIM

​Activate SIMs

​Get data usage / quota

​Set data limits

​Get SMS quota

​Send an SMS to a SIM (cloud → device)

​Get SMS history (MO/MT messages)

​Send a data / cloud message to a SIM

​Rename a SIM

​Reset connectivity

​Data top-up

​SIM transfer

​Device location

​Pagination comparison

​API feature comparison

Core terminology differences

Endpoint paths

Authentication

SIM states

List all SIMs

Get a single SIM

Check SIM status and connectivity

Pause (disable) or resume (enable) a SIM

Activate SIMs

Get data usage / quota

Set data limits

Get SMS quota

Send an SMS to a SIM (cloud → device)

Get SMS history (MO/MT messages)

Send a data / cloud message to a SIM

Rename a SIM

Reset connectivity

Data top-up

SIM transfer

Device location

Pagination comparison

API feature comparison