Links

List Links

Returns a paginated list of all links (SIM activations) for your organization.

Query Parameters:

Parameter	Type	Default	Description
per_page	int	20	Items per page (min: 1, max: 100)
status	string	–	Filter by link status: active, suspended, inactive
search	string	–	Free-text search (matches ICCID and other fields)
page	int	1	Page number for pagination

Response:

Code
 
{
  "success": true,
  "data": {
    "data": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "My SIM",
        "iccid": "8901010000000000001",
        "status": "active",
        "created_at": "2025-01-10T08:30:00+00:00"
      }
    ],
    "meta": {
      "current_page": 1,
      "last_page": 5,
      "per_page": 20,
      "total": 95,
      "from": 1,
      "to": 20
    }
  }
}

Create Link

Create a new link (eSIM activation). The system fetches an available SIM from the OmaxTelecom Core network, creates an endpoint, and activates it with the specified plan.

This creates both a link and an initial activation record for the plan.

Body Parameters:

Parameter	Type	Required	Description
plan_id	uuid	Yes	Plan UUID to activate with (must exist in plans table)
name	string	No	Optional display name (max 255 chars)

Flow:

1. Checks wallet balance (must cover plan's retail price)
2. Fetches available eSIM ICCID from OmaxTelecom Core network (filtered by sponsor profile and eSIM product)
3. Deducts plan retail price from wallet
4. Creates OmaxTelecom Core network endpoint with the plan as addon
5. Creates link + activation + transaction records
6. On OmaxTelecom Core network failure: wallet amount is automatically refunded

Response (201 Created):

Code
 
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My new SIM",
    "iccid": "8932042000000000000",
    "msisdn": "+31612345678",
    "lpa_profile": "LPA:1$example.com$ACTIVATION_CODE",
    "activation_url": "https://example.smdp.com",
    "amount_charged": "4.50",
    "currency": "EUR",
    "created_at": "2025-06-01T12:00:00+00:00"
  },
  "message": "Link created."
}

Errors:

• 401 UNAUTHORIZED – Missing or invalid Authorization header
• 402 INSUFFICIENT_BALANCE – Wallet balance too low (details: required, available, currency)
• 422 VALIDATION_ERROR – plan_id is required / plan not found
• 500 CONFIG_ERROR – OmaxTelecom Core network default base plan is not configured
• 502 PROVISIONING_FAILED – OmaxTelecom Core network returned no endpoint ID (amount refunded)
• 502 PROVISIONING_ERROR – OmaxTelecom Core network API error (amount refunded)

Get Single Link

Returns detailed link information including live OmaxTelecom Core network data, eSIM activation URLs, all activations with per-plan usage, and coverage data.

Each activation has an id (activation UUID) which can be used in PUT /v1/links/{identifier}/plans to remove it.

Path Parameter:

Parameter	Type	Description
identifier	string	Link UUID or ICCID

Response:

Code
 
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My SIM",
    "iccid": "8932042000000000000",
    "status": "active",
    "created_at": "2025-01-10T08:30:00+00:00",
    "lpa_profile": "LPA:1$example.com$ACTIVATION_CODE",
    "apple_activation_url": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$example.com$ACTIVATION_CODE",
    "android_activation_url": "https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA:1$example.com$ACTIVATION_CODE",
    "msisdn": "+31612345678",
    "data_used_mb": 256.1234,
    "data_remaining_mb": 767.8766,
    "activations": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "plan_id": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "plan_name": "Europe 1GB - 7 Days",
        "status": "active",
        "activation_date": "2025-01-15T10:00:00+00:00",
        "data_used_mb": 256.1234,
        "data_remaining_mb": 767.8766,
        "expiry_date": "2025-01-22T10:00:00+00:00",
        "coverage_countries": ["HR", "DE", "FR", "IT", "ES"]
      }
    ],
    "coverage_data": [
      {
        "iso2": "HR",
        "name": "Croatia",
        "operators": [
          {
            "operator_id": 123,
            "operator_name": "A1 HR",
            "network_types": "2G, 3G, 4G"
          }
        ]
      }
    ]
  }
}

Notes:

• activations[].id is the activation UUID — pass this in remove[] to detach a plan
• data_used_mb / data_remaining_mb come from live OmaxTelecom Core network data (both total and per-activation)
• status reflects the live OmaxTelecom Core network endpoint status
• lpa_profile is the eSIM LPA activation string (fetched from OmaxTelecom Core network if not stored locally)
• apple_activation_url / android_activation_url are universal deep links for eSIM installation
• coverage_countries per activation shows ISO2 codes for that plan's coverage
• coverage_data is an aggregated list of all countries and operators across all active plans

Errors:

• 404 NOT_FOUND – Link not found

Reactivate Link

Reactivate a suspended link. The status change is synchronized with the OmaxTelecom Core network.

Body: { "status": "active" }

Remove Activation from Link

Remove (cancel) an activation from a link. Get the activation UUID from GET /v1/links/{id} → activations[].id.

Body: { "remove": ["activation-uuid"] }

Get Available Topup Plans for Link

Returns plans available for topping up a specific link. Plans are filtered by matching sponsor profile only plans compatible with the link's OmaxTelecom Core network sponsor profile are returned.

Each plan includes data amount, validity, pricing and coverage summary.

Path Parameter:

Parameter	Type	Description
identifier	string	Link UUID or ICCID

Response:

Code
 
{
  "success": true,
  "data": [
    {
      "id": 5,
      "name": "Europe Topup 1GB - 7 Days",
      "retail_price": "4.50",
      "currency": "EUR",
      "data_gb": 1.0,
      "validity_days": 7,
      "coverage": {
        "countries": ["HR", "DE", "FR", "IT", "ES"],
        "total_countries": 32,
        "total_operators": 85
      }
    }
  ]
}

Notes:

• Only plans with a matching OmaxTelecom Core network sponsor profile are returned
• Plans without a provider_plan_id are excluded when a sponsor profile is detected
• Use the plan id in PUT /v1/links/{identifier}/plans → add[] to apply the topup

Errors:

• 404 NOT_FOUND – Link not found

Get Link History

Returns a paginated list of all transactions related to a specific link. This includes:

• activation — initial link creation charge
• topup — plan topup charges
• refund — refunds for failed operations
• monthly_link_fee — monthly fees that include this link in charged_link_ids

Path Parameter:

Parameter	Type	Description
identifier	string	Link UUID or ICCID

Query Parameters:

Parameter	Type	Default	Description
per_page	int	15	Items per page (min: 1, max: 100)
page	int	1	Page number for pagination

Response:

Code
 
{
  "success": true,
  "data": {
    "data": [
      {
        "id": "tx-uuid",
        "type": "activation",
        "amount": "4.50",
        "currency": "EUR",
        "plan_name": "Europe 1GB - 7 Days",
        "price_per_link": null,
        "billing_period": null,
        "activation_id": "act-uuid",
        "charged_at": "2025-01-15T10:00:00+00:00",
        "created_at": "2025-01-15T10:00:00+00:00"
      },
      {
        "id": "tx-uuid-2",
        "type": "topup",
        "amount": "10.00",
        "currency": "EUR",
        "plan_name": "Europe 3GB - 30 Days",
        "price_per_link": null,
        "billing_period": null,
        "activation_id": "act-uuid-2",
        "charged_at": "2025-02-01T14:30:00+00:00",
        "created_at": "2025-02-01T14:30:00+00:00"
      },
      {
        "id": "tx-uuid-3",
        "type": "monthly_link_fee",
        "amount": "15.00",
        "currency": "EUR",
        "plan_name": null,
        "price_per_link": "0.5000",
        "billing_period": "2025-01",
        "activation_id": null,
        "charged_at": "2025-02-01T00:00:00+00:00",
        "created_at": "2025-02-01T00:05:00+00:00"
      }
    ],
    "meta": {
      "current_page": 1,
      "last_page": 2,
      "per_page": 15,
      "total": 18,
      "from": 1,
      "to": 15
    }
  }
}

Notes:

• Transactions are ordered by charged_at descending (newest first)
• Monthly link fee transactions appear if this link is in their charged_link_ids metadata
• plan_name is resolved from the activation's plan, or from transaction metadata

Errors:

• 404 NOT_FOUND – Link not found

Get Link Network Status (Live)

Force a live network status check from the OmaxTelecom Core network, bypassing the cache.

Same response format as the cached version but always returns cached: false.