Physical SIM API Reference¶

This document describes the REST API endpoints for managing physical SIM cards in the TelcoAPI platform.

Endpoints¶

List SIM Cards¶

GET /v1/sim/physical

Query Parameters:

Parameter	Type	Description
state	string	Filter by SIM state (e.g., ACTIVE, SUSPENDED)
vendor	string	Filter by SIM vendor
page	integer	Page number for pagination
per_page	integer	Number of items per page
sort	string	Sort field and direction (e.g., created_at:desc)

Response:

{
  "data": [
    {
      "iccid": "89441234567890123456",
      "imsi": "234150123456789",
      "msisdn": "447123456789",
      "state": "ACTIVE",
      "vendor": "GEMALTO",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:35:00Z"
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "per_page": 10
  }
}

Get SIM Card Details¶

GET /v1/sim/physical/{iccid}

Path Parameters:

Parameter	Type	Description
iccid	string	ICCID of the SIM card

Response:

{
  "iccid": "89441234567890123456",
  "imsi": "234150123456789",
  "msisdn": "447123456789",
  "state": "ACTIVE",
  "vendor": "GEMALTO",
  "pin1": "1234",
  "pin2": "5678",
  "puk1": "12345678",
  "puk2": "87654321",
  "ki": "A1B2C3D4E5F6...",
  "opc": "F6E5D4C3B2A1...",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:35:00Z"
}

Provision SIM Card¶

POST /v1/sim/physical

Request Body:

{
  "iccid": "89441234567890123456",
  "imsi": "234150123456789",
  "msisdn": "447123456789",
  "vendor": "GEMALTO",
  "pin1": "1234",
  "pin2": "5678",
  "puk1": "12345678",
  "puk2": "87654321",
  "ki": "A1B2C3D4E5F6...",
  "opc": "F6E5D4C3B2A1..."
}

Response:

{
  "iccid": "89441234567890123456",
  "state": "INVENTORY",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Update SIM State¶

PATCH /v1/sim/physical/{iccid}/state

Request Body:

{
  "state": "ACTIVE",
  "reason": "Customer activation request"
}

Response:

{
  "iccid": "89441234567890123456",
  "state": "ACTIVE",
  "updated_at": "2024-01-15T10:35:00Z"
}

Reset PIN¶

POST /v1/sim/physical/{iccid}/reset-pin

Request Body:

{
  "pin_type": "PIN1",
  "current_pin": "1234",
  "new_pin": "4321"
}

Response:

{
  "success": true,
  "updated_at": "2024-01-15T10:40:00Z"
}

Unblock PIN¶

POST /v1/sim/physical/{iccid}/unblock-pin

Request Body:

{
  "pin_type": "PIN1",
  "puk": "12345678",
  "new_pin": "4321"
}

Response:

{
  "success": true,
  "remaining_attempts": 10,
  "updated_at": "2024-01-15T10:45:00Z"
}

Delete SIM Card¶

DELETE /v1/sim/physical/{iccid}

Response:

{
  "success": true,
  "deleted_at": "2024-01-15T11:00:00Z"
}

Error Responses¶

Invalid ICCID Format¶

{
  "type": "https://api.telcoapi.com/errors/validation-error",
  "title": "Invalid ICCID Format",
  "status": 400,
  "detail": "ICCID must be a 19-20 digit number",
  "instance": "/sim/physical"
}

SIM Not Found¶

{
  "type": "https://api.telcoapi.com/errors/not-found",
  "title": "SIM Not Found",
  "status": 404,
  "detail": "No SIM card found with ICCID 89441234567890123456",
  "instance": "/sim/physical/89441234567890123456"
}

Invalid State Transition¶

{
  "type": "https://api.telcoapi.com/errors/invalid-state-transition",
  "title": "Invalid State Transition",
  "status": 400,
  "detail": "Cannot transition from BLOCKED to ACTIVE state",
  "instance": "/sim/physical/89441234567890123456/state"
}

Webhook Events¶

The following webhook events are available for physical SIM cards:

sim.physical.created: Triggered when a new SIM card is provisioned
sim.physical.state_changed: Triggered when a SIM card's state changes
sim.physical.pin_reset: Triggered when a PIN is reset
sim.physical.pin_blocked: Triggered when a PIN is blocked
sim.physical.deleted: Triggered when a SIM card is deleted

Example webhook payload:

{
  "event": "sim.physical.state_changed",
  "timestamp": "2024-01-15T10:35:00Z",
  "data": {
    "iccid": "89441234567890123456",
    "previous_state": "INVENTORY",
    "new_state": "ACTIVE",
    "reason": "Customer activation request"
  }
}