API Docs

simsonic Developer API

Full reference for the simsonic Developer API. All endpoints require dual authentication.

Authentication

Every request requires dual authentication — both factors must be present.

Factor 1 — Bearer Token

Your personal Developer Bearer token, generated from the Developer page. This is separate from your login password.

Copy

Authorization: Bearer simbearer_<prefix>_<secret>

Factor 2 — API Key Header

Your customer-group API key, obtained from the Developer page. Either header name is accepted.

Copy

X-Customer-API-Key: simdev_<prefix>_<secret>
# or
X-simsonic-API-Key: simdev_<prefix>_<secret>

Scope

API keys are scoped to a customer group. Responses include SIMs belonging to that customer and all of its sub-customers. Access never flows upward — a sub-customer's key cannot see its parent's data.

Rate Limiting

Limits are enforced per user and customer group. When exceeded, the API returns HTTP 429 with a Retry-After header.

Limit	Value
Burst	10 requests per 10s
Per minute	60 requests
Per hour	1500 requests
Min poll interval	5s between list requests

Rate-limit status is returned in response headers on every request:

Copy

X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 58
X-RateLimit-Limit-Hour: 1500
X-RateLimit-Remaining-Hour: 1498
X-RateLimit-Limit-Burst: 10
X-RateLimit-Remaining-Burst: 9

List SIMs

GEThttps://management.simsonic.com/developer/api/sims/

Returns a paginated list of all SIMs within your customer group scope.

Query Parameters

Parameter	Type	Description
pageoptional	integer	Page number. Defaults to 1.
page_sizeoptional	integer	Results per page. Default 25, max 100.
statusoptional	string	Filter by SIM status. One of: `active`, `inactive`, `suspended`, `cancelled`, `stock`, `dispatched`, `trial`.
customeroptional	string	Filter to a specific sub-customer by exact account name. Returns only SIMs directly owned by that customer. Returns 404 if not found within your scope.
updated_afteroptional	ISO-8601	Return only SIMs updated after this timestamp. Max lookback: 31 days. Example: `2026-03-01T00:00:00Z`.

Example Request

Copy

curl -H "Authorization: Bearer simbearer_<prefix>_<secret>" \
  -H "X-Customer-API-Key: simdev_<prefix>_<secret>" \
  "https://management.simsonic.com/developer/api/sims/?page=1&page_size=25"

Filter by Sub-Customer

Copy

curl -H "Authorization: Bearer simbearer_<prefix>_<secret>" \
  -H "X-Customer-API-Key: simdev_<prefix>_<secret>" \
  "https://management.simsonic.com/developer/api/sims/?customer=Sub-Customer+Name"

Example Response

Copy

{
  "count": 142,
  "page": 1,
  "page_size": 25,
  "total_pages": 6,
  "results": [
    {
      "iccid": "89444611503500000001",
      "msisdn": "883190603000001",
      "status": "active",
      "connection_status": "active",
      "customer_name": "My Customer",
      "group": null,
      "tariff_name": "AAA-933",
      "usage": {
        "data_used_mb": "12.30",
        "data_overage_mb": "0.00"
      },
      "cost": {
        "currency": "GBP",
        "base_cost": "£0.06",
        "overage_cost": "£0.00",
        "total_cost": "£0.06"
      },
      "data_bundle": null,
      "updated_at": "2026-03-30T10:15:00+00:00"
    }
  ]
}

Note: group is only populated when the SIM belongs to a sub-customer. It is null for SIMs directly owned by your customer group.

Get SIM

GEThttps://management.simsonic.com/developer/api/sims/<sim_id>/

Returns a single SIM by its internal database ID. The SIM must be within your customer group scope.

Path Parameters

Parameter	Type	Description
sim_idrequired	integer	Internal SIM ID.

Example Request

Copy

curl -H "Authorization: Bearer simbearer_<prefix>_<secret>" \
  -H "X-Customer-API-Key: simdev_<prefix>_<secret>" \
  "https://management.simsonic.com/developer/api/sims/123/"

Example Response

Copy

{
  "iccid": "89444611503500000001",
  "msisdn": "883190603000001",
  "status": "active",
  "connection_status": "active",
  "customer_name": "My Customer",
  "group": null,
  "tariff_name": "AAA-933",
  "usage": { "data_used_mb": "12.30", "data_overage_mb": "0.00" },
  "cost": { "currency": "GBP", "base_cost": "£0.06", "overage_cost": "£0.00", "total_cost": "£0.06" },
  "data_bundle": null,
  "updated_at": "2026-03-30T10:15:00+00:00"
}

Send SMS

POSThttps://management.simsonic.com/developer/api/sims/<iccid>/sms/

Send a Mobile Terminated (MT) SMS to a SIM within your customer group scope. The SIM is identified by ICCID; its MSISDN is looked up automatically. The message is delivered via the Wireless Logic SMS network.

Path Parameters

Parameter	Type	Description
iccidrequired	string	ICCID of the target SIM (up to 20 digits). Must be within your scope.

Request Body — JSON, Content-Type: application/json

Field	Type	Description
messagerequired	string	SMS message body. Max 160 characters.
message_idoptional	string	Your correlation ID for this message (max 48 chars). If omitted, one is generated for you. Must be globally unique.
callback_urloptional	string (URL)	HTTPS endpoint to receive a delivery receipt POST when the message is delivered or expires. See Delivery Receipts below.

Example Request

Copy

curl -H "Authorization: Bearer simbearer_<prefix>_<secret>" \
  -H "X-Customer-API-Key: simdev_<prefix>_<secret>" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"message": "Hello from simsonic", "callback_url": "https://your-server.example/sms-receipt"}' \
  "https://management.simsonic.com/developer/api/sims/89444611503500000001/sms/"

Example Response

Copy

{
  "message_id": "sms_a3f1b2c4d5e6f708",
  "status": "sent",
  "iccid": "89444611503500000001",
  "msisdn": "883190603000001"
}

Returns HTTP 202 Accepted. The message has been submitted to the network; status will be sent.

Delivery Receipts

If you provide a callback_url, simsonic will POST the following JSON payload to that URL when a delivery receipt is received from the network:

Copy

{
  "message_id": "sms_a3f1b2c4d5e6f708",
  "iccid": "89444611503500000001",
  "msisdn": "883190603000001",
  "status": "delivered",
  "received_at": "2026-03-30T14:22:05+00:00"
}

Possible status values: delivered, expired, failed. Your endpoint should return any 2xx response; failed forwards are logged but not retried.

SIM Object Reference

Field	Type	Description
iccid	string	Unique SIM identifier (up to 20 digits).
msisdn	string	Mobile number assigned to the SIM.
status	string	SIM lifecycle status: active, inactive, suspended, cancelled, stock, dispatched, trial.
connection_status	string	Current network connection: active or inactive.
customer_name	string	Account name of the customer that owns this SIM.
group	string \| null	Populated with the sub-customer name when the SIM belongs to a sub-customer of the API key's customer group. null for root-level SIMs.
tariff_name	string \| null	Customer-facing tariff name assigned to this SIM.
usage.data_used_mb	string	Month-to-date data used in MB.
usage.data_overage_mb	string	Month-to-date overage in MB beyond the included allowance.
cost.currency	string	Always GBP.
cost.base_cost	string	Monthly base/line rental cost formatted as GBP (e.g. £0.06).
cost.overage_cost	string	Current month overage cost formatted as GBP.
cost.total_cost	string	Total cost (base + overage) formatted as GBP.
data_bundle	object \| null	Present when SIM is on a data bundle tariff. See below.
updated_at	ISO-8601	Timestamp of last sync from SIMPro.

data_bundle Object

Present only when data_bundle is not null.

Field	Type	Description
is_data_bundle	boolean	Always true.
bundle_data_allowance_mb	string	Total shared pool allowance in MB.
bundle_monthly_cost	string	Monthly cost for the shared bundle.
per_sim_access_fee	string	Per-SIM access fee on top of the bundle cost.
pool_used_mb	string	Total MB used across all SIMs in the pool this month.
pool_total_mb	string	Total pool allowance in MB.

Errors

Every error response from the API — including invalid paths, wrong methods, authentication failures, and rate limits — returns JSON. HTML is never returned for any /developer/api/ path.

All error bodies contain detail (human-readable message) and code (machine-readable identifier). Rate limit errors additionally include retry_after_seconds.

HTTP	Code	Meaning
400	invalid_status_filter	The status query param is not a valid SIM status.
400	invalid_updated_after	The updated_after value is not a valid ISO-8601 datetime.
400	updated_after_range_exceeded	The updated_after value is older than 31 days.
400	invalid_json	Request body is not valid JSON (SMS endpoint).
400	invalid_callback_url	callback_url must be HTTPS and point to a publicly reachable host.
400	message_required	No message field in SMS request body.
400	message_too_long	SMS message exceeds 160 characters.
400	message_id_too_long	Provided message_id exceeds 48 characters.
401	bearer_token_required	No Bearer token provided in Authorization header.
401	invalid_bearer_token	Bearer token is invalid or has been revoked.
401	user_inactive	The user account associated with the Bearer token is inactive.
401	api_key_required	No X-Customer-API-Key header provided.
401	invalid_api_key	API key is invalid or has been revoked.
403	developer_access_required	User does not have the developer role.
403	tenant_scope_mismatch	API key belongs to a different customer group than the authenticated user.
404	not_found	The endpoint path does not exist, or the requested SIM is not within your scope.
404	customer_not_found	The customer filter name does not match any customer in your scope.
405	method_not_allowed	HTTP method is not supported by this endpoint. Verify you are using the correct method (GET or POST) as documented.
409	duplicate_message_id	The provided message_id has already been used.
422	no_msisdn	The SIM does not have a MSISDN assigned — SMS cannot be sent.
429	rate_limited_burst	Burst limit exceeded. Check Retry-After header.
429	rate_limited_minute	Per-minute limit exceeded.
429	rate_limited_hour	Per-hour limit exceeded.
429	rate_limited_poll_interval	Minimum poll interval not respected.
502	sms_provider_error	SMS network provider returned an error. Try again.
502	sms_provider_unreachable	SMS network provider is unreachable. Try again.
503	sms_not_configured	SMS service is not enabled on this instance.