Working with Connections
The Connection APIs provide access to the core subscription inventory managed within the IoT.live platform.
These APIs allow integrations to:
- Retrieve SIM inventory
- Search and filter subscriptions
- Retrieve connection details
- Export operational datasets
- Retrieve inventory statistics
The Connection APIs form the foundation for most IoT.live integrations.
[IMAGE PLACEHOLDER: Connection inventory architecture]
Connection inventory overview
The platform aggregates connection data across multiple providers and connectivity platforms into a unified inventory model.
Typical connection records may include:
- ICCID
- IMSI
- MSISDN
- Provider information
- Rate plans
- Operational status
- Usage summaries
- Customer tags
- Device attributes
The primary inventory API is:
listConnections
listConnections API
The listConnections API retrieves paginated connection inventory records.
Typical use cases include:
- Synchronising inventory into external systems
- Building operational dashboards
- Reporting workflows
- Searching subscriptions
- Filtering device groups
[IMAGE PLACEHOLDER: listConnections workflow]
Example listConnections request
Pagination
The API supports paginated inventory retrieval.
Common pagination fields:
Field | Description |
|---|---|
page | Zero-based page number |
pageSize | Number of records returned |
Example:
Large integrations should paginate inventory requests instead of requesting extremely large result sets.
Searching connections
The platform supports flexible searching using:
- ICCID
- IMSI
- MSISDN
- Provider identifiers
- Customer tags
- Operational attributes
The API documentation references an omniSearch field for broad inventory searching.
Typical search scenarios include:
- Find a specific SIM
- Retrieve all suspended subscriptions
- Search by customer tag
- Filter by provider
- Search by rate plan
[IMAGE PLACEHOLDER: Connection search examples]
Example omniSearch request
getConnectionDetails API
The getConnectionDetails API retrieves detailed information for an individual connection.
This may include:
- Subscription identifiers
- Current operational state
- Provider information
- Usage details
- Assigned rate plans
- Customer associations
- Tags and attributes
[IMAGE PLACEHOLDER: Connection details example]
Example getConnectionDetails request
Connection statistics APIs
The platform also supports inventory statistics and summary APIs.
Example APIs include:
- listConnectionStats
- exportConnectionStats
Typical use cases include:
- Operational dashboards
- Inventory summaries
- Status reporting
- Usage trend analysis
Statistics may include:
- Active connections
- Suspended connections
- Provider distribution
- Rate plan counts
- Usage summaries
Exporting inventory
Large inventory datasets can be exported using:
- exportConnections
- exportConnectionStats
The platform supports:
- Synchronous exports
- Asynchronous exports
- Downloadable report generation
[IMAGE PLACEHOLDER: Inventory export workflow]
Large exports may continue processing asynchronously after the initial API response is returned.
Common connection identifiers
The platform commonly uses the following identifiers:
Identifier | Description |
|---|---|
ICCID | SIM card identifier |
IMSI | Subscriber identity |
MSISDN | Mobile number |
MDN | Mobile directory number |
ESN | Electronic serial number |
MEID | Mobile equipment identifier |
Different providers may support different identifier types.
Connection object structure
The API documentation defines a standard Connection Object returned from inventory APIs.
Connection objects may contain:
- Subscription identifiers
- Provider information
- Usage details
- Billing attributes
- Tags and metadata
- Operational state information
[IMAGE PLACEHOLDER: Connection object example]
Best practices
Recommended practices when working with connection inventory include:
- Paginate large requests
- Use correlation IDs for tracing
- Avoid excessive polling
- Export large datasets asynchronously
- Use filtering wherever possible
- Cache inventory safely where appropriate
Connection inventory data may contain sensitive customer and subscription information and should be handled securely.