Request & Response Structure
The IoT.live API uses a consistent JSON request and response model across most API operations.
Requests are submitted using:
- HTTPS POST
- JSON-formatted request bodies
- Shared authentication fields
- Structured operation-specific payloads
Responses follow a standardised response structure containing:
- Request status
- Correlation identifiers
- Response timestamps
- API service version information
[IMAGE PLACEHOLDER: Request and response structure]
Standard request model
Most API requests consist of:
- Authentication fields
- Operation-specific parameters
- Optional filtering or pagination values
The authentication fields are inherited from the shared RequestAbstract object.
Basic structure:
Standard response model
Most API responses inherit from the shared ResponseAbstract object.
Basic response structure:
Additional response fields are typically appended depending on the API operation being executed.
Correlation IDs (corrId)
The corrId field is an optional client-defined correlation identifier.
It is:
- Submitted in the request
- Echoed back in the response
- Useful for request tracing and logging
Example:
Use meaningful correlation IDs to simplify operational troubleshooting and API logging.
Response timestamps
The responseTime field contains:
- UTC timestamp
- Milliseconds since Unix/POSIX epoch
- API server response time
Example:
This value can be used for:
- Auditing
- Logging
- Latency analysis
- Event sequencing
API result handling
The result field indicates the operational outcome of the request.
Common values include:
Result | Description |
|---|---|
Success | Request completed successfully |
Failed | Request failed during processing |
Partially_Successful | Mixed success and failure within async operations |
Pending | Request is still processing |
Rejected | Request rejected, often due to rate limitations |
Not_Allowed | User or account lacks required permissions |
Skipped | Request items were skipped |
Authentication_Failed | Invalid credentials |
User_Locked | User account locked |
Error messages
When an operation fails, additional details may be included inside responseMsg.
Example:
API integrations should always validate the result field instead of assuming HTTP success means the operation succeeded.
Request pagination
Many inventory and reporting APIs support pagination.
Typical pagination fields include:
Field | Description |
|---|---|
page | Zero-based page number |
pageSize | Number of records per page |
Example:
Pagination is commonly used with:
- Inventory APIs
- Usage APIs
- Audit APIs
- Export operations
Filtering structures
Many APIs support filtering using:
- Connection identifiers
- Account information
- Status values
- Tags
- Date ranges
- Provider attributes
Example filtering operations include:
- Retrieve active connections
- Search by ICCID
- Filter by rate plan
- Filter by operational state
[IMAGE PLACEHOLDER: Filtering and pagination example]
Synchronous responses
Synchronous APIs:
- Execute immediately
- Return results directly
- Typically support smaller operations
Example use cases:
- Retrieve connection details
- List inventory
- Retrieve usage records
Synchronous workflows are generally simpler to integrate.
Asynchronous responses
Asynchronous APIs:
- Queue larger operations
- Execute in the background
- Return campaign or operation references
Common async operations include:
- Bulk updates
- Large exports
- Campaign processing
- Bulk tagging
Example async response behaviour:
[IMAGE PLACEHOLDER: Async workflow lifecycle]
JSON formatting requirements
The API expects:
- Valid JSON formatting
- UTF-8 encoding
- Proper escaping of special characters
Required HTTP header:
Multipart upload APIs
Some APIs support multipart upload workflows for:
- Batch operational updates
- CSV imports
- Large operational datasets
These APIs are documented separately under:
- Batch APIs
- Import workflows
- Campaign operations
Best practices
Recommended integration practices include:
- Validate all API results
- Log correlation IDs
- Handle async workflows properly
- Retry transient failures safely
- Paginate large inventory requests
- Validate request formatting before submission
Large operational requests should be carefully validated before execution against production subscriptions.