Developer Docs

SimGuyz API Guide

Professional integration docs for TopUp, MobileX, LinkUp, T-Mobile, Travel eSIM, Shipping, authentication, request payloads, and response JSON.

Sandbox Base URL

https://www.simguyz.com/api/v1

Production Base URL

https://www.simguyz.com/api/v1

Auth Format

Authorization: Bearer sg_test_...

Charge Safety

Use Idempotency-Key on all write endpoints.

Authentication

Send your API token in the Authorization header. Use Idempotency-Key on all charge endpoints.

Authorization: Bearer sg_test_xxxxx
Idempotency-Key: your-unique-request-key

Test and Production

Recommended flow: integrate with sg_test_... first, verify responses, then move to sg_live_... after production is enabled.

Use sg_test_... for sandbox.
Use sg_live_... for production.
Sandbox supports safe testing for topups, activations, eSIM, and labels where available.
Production uses your live wallet and real provider connectivity.

Integration Flow

Step 1

Open API Tokens

Use the assigned token visible in your portal.

Step 2

Load Catalogs

Read client SKU values from the catalog endpoints.

Step 3

Send Request

Submit topup, activation, eSIM, or shipping payload.

Step 4

Track Status

Use transaction lookup and job status endpoints where needed.

Endpoints

Identifier Map

Product	Field To Send	Example	Get It From
TopUp	`sku`	`YOUR_TOPUP_SKU`	`GET /api/v1/catalog/topups`
LinkUp Activation	`sku`	`YOUR_LINKUP_SKU`	`GET /api/v1/catalog/activations`
MobileX Activation	`sku`	`YOUR_MOBILEX_SKU`	`GET /api/v1/catalog/activations`
Travel eSIM	`plan_id`	`123`	`GET /api/v1/catalog/esim`
T-Mobile Activation	`plan_id`	`TMO_STD_1`	`GET /api/v1/catalog/activations`
Shipping Label	Request body only	`from_address`, `to_address`, `parcel`	Direct request body

Available Endpoints

GET

/api/v1/wallet

Read API wallet balance and billing mode.

GET

/api/v1/transactions/{id}

Read saved transaction status and response.

GET

/api/v1/catalog/topups

Load visible topup SKU values.

POST

/api/v1/topups

Submit topup request.

GET

/api/v1/catalog/activations

Load LinkUp, MobileX, and T-Mobile SKU values.

POST

/api/v1/activations/mobilex

Submit MobileX physical SIM or eSIM activation.

GET

/api/v1/activations/mobilex/jobs/{id}

Track MobileX async job status.

POST

/api/v1/activations/linkup

Submit LinkUp physical or eSIM activation.

POST

/api/v1/activations/tmobile

Submit T-Mobile activation request.

GET

/api/v1/catalog/esim

Load Travel eSIM plans.

POST

/api/v1/esim/orders

Create Travel eSIM order.

POST

/api/v1/shipping/labels

Create label and tracking response.

Request and Response JSON

Download Postman

Wallet

Request

curl "https://www.simguyz.com/api/v1/wallet" \
  -H "Authorization: Bearer sg_test_xxxxx"

Response JSON

{
  "request_id": "req_7f2b9ab1",
  "status": "success",
  "environment": "test",
  "client_id": 12,
  "client_name": "WEST COAST WIRELESS",
  "billing_mode": "prepaid",
  "balance": "10000.00",
  "currency": "USD"
}

Transaction Lookup

Request

curl "https://www.simguyz.com/api/v1/transactions/145" \
  -H "Authorization: Bearer sg_test_xxxxx"

Response JSON

{
  "request_id": "req_34be8d90",
  "status": "success",
  "transaction": {
    "id": 145,
    "environment": "test",
    "product_type": "topup",
    "product_key": "100039",
    "provider": "surgepays",
    "status": "success",
    "sell_price": "8.40",
    "provider_cost": "7.20",
    "response": {
      "sku": "YOUR_TOPUP_SKU",
      "account_number": "5551234567",
      "amount": "10.00"
    }
  }
}

Topup

Request

{
  "sku": "YOUR_TOPUP_SKU",
  "account_number": "5551234567",
  "amount": "10.00",
  "external_id": "topup_1001"
}

Success Response JSON

{
  "request_id": "req_8413a912",
  "status": "success",
  "transaction_id": "145",
  "product_type": "topup",
  "provider": "surgepays",
  "amount_charged": "8.40",
  "environment": "test",
  "data": {
    "provider_status": "approved",
    "provider_transaction_id": "test_145",
    "sku": "YOUR_TOPUP_SKU",
    "account_number": "5551234567",
    "amount": "10.00",
    "balance_after": "9991.60"
  }
}

Failed Response JSON

{
  "request_id": "req_8413a912",
  "status": "failed",
  "transaction_id": "145",
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Wallet balance is too low."
  },
  "environment": "live"
}

MobileX Activation

MobileX is asynchronous. The submit endpoint returns an accepted job, not the final activation result. Any new portal built on this API must wait for the final job response before showing activation success to the user. Final activation details such as phone_number and eSIM qr_code appear on the job status endpoint after processing completes. Physical SIM activation needs SimNo, AccountPin, IMEI, and ZipCode. If SimType is esim, do not send SimNo.

Request

{
  "activation_type": "domestic",
  "sku": "YOUR_MOBILEX_SKU",
  "SimType": "physical",
  "SimNo": "1234567890123456789",
  "AccountPin": "123456",
  "IMEI": "123456789012345",
  "ZipCode": "90001",
  "external_id": "mx_1001"
}

Accepted Response JSON

{
  "request_id": "req_1f4c3b20",
  "status": "success",
  "transaction_id": "212",
  "product_type": "activation",
  "product_key": "104191",
  "provider": "mobilex",
  "amount_charged": "9.00",
  "environment": "live",
  "data": {
    "job_id": "9012",
    "sku": "YOUR_MOBILEX_SKU",
    "product_id": "104191"
  }
}

Do not treat the accepted submit response as completed activation. Your portal should keep the row or modal in a processing state, poll GET /api/v1/activations/mobilex/jobs/{job_id}, and only show success after the final job response is ready.

Physical SIM Job Status JSON

{
  "request_id": "req_1f4c3b20",
  "status": "success",
  "environment": "live",
  "job": {
    "success": true,
    "job_id": 9012,
    "activation_type": "domestic",
    "transaction_id": "MX-77881",
    "phone_number": "2135559821",
    "sim_number": "1234567890123456789",
    "submitted": {
      "Product": "104191",
      "SimType": "physical",
      "SimNo": "1234567890123456789",
      "IMEI": "123456789012345",
      "ZipCode": "90001"
    }
  }
}

Validation Error JSON

{
  "request_id": "req_1f4c3b20",
  "status": "failed",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Fix the highlighted fields."
  },
  "validation_errors": [
    "SIM Number is required for physical SIM activations."
  ],
  "environment": "test"
}

MobileX eSIM Activation

For eSIM, the submit response is still accepted/queued first. Your portal must wait for the job status response before showing the assigned phone_number, activation_code, and qr_code.

Request

{
  "activation_type": "domestic",
  "sku": "YOUR_MOBILEX_ESIM_SKU",
  "SimType": "esim",
  "AccountPin": "123456",
  "IMEI": "123456789012345",
  "ZipCode": "90001",
  "external_id": "mx_esim_1001"
}

Accepted Response JSON

{
  "request_id": "req_2ce44bd1",
  "status": "success",
  "transaction_id": "213",
  "product_type": "activation",
  "provider": "mobilex",
  "amount_charged": "9.00",
  "environment": "live",
  "data": {
    "job_id": "9013",
    "sku": "YOUR_MOBILEX_ESIM_SKU",
    "product_id": "104191"
  }
}

eSIM Job Status JSON

{
  "request_id": "req_2ce44bd1",
  "status": "success",
  "environment": "live",
  "job": {
    "success": true,
    "job_id": 9013,
    "activation_type": "domestic",
    "transaction_id": "MX-77882",
    "phone_number": "2135551122",
    "activation_code": "LPA:1$mobilex$code",
    "qr_code": "base64-or-url-value",
    "submitted": {
      "Product": "104191",
      "SimType": "esim",
      "IMEI": "123456789012345",
      "ZipCode": "90001"
    }
  }
}

LinkUp Activation

Physical activation needs sim, area_code, and zip. For eSIM, send esim, imei, email, area_code, and zip.

Request

{
  "sku": "YOUR_LINKUP_SKU",
  "sim": "1234567890123456789",
  "area_code": "213",
  "zip": "90001",
  "imei": "123456789012345",
  "external_id": "linkup_1001"
}

Success Response JSON

{
  "request_id": "req_7021c8de",
  "status": "success",
  "transaction_id": "244",
  "product_type": "activation",
  "product_key": "8016",
  "provider": "linkup",
  "amount_charged": "12.50",
  "environment": "live",
  "data": {
    "provider_status": "APPROVED",
    "provider_transaction_id": "LKP993821",
    "phone_number": "2135559821",
    "sku": "YOUR_LINKUP_SKU",
    "balance_after": "756.39"
  }
}

Validation Error JSON

{
  "request_id": "req_7021c8de",
  "status": "failed",
  "transaction_id": "244",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "For LinkUp physical activation, sim is required."
  },
  "environment": "test"
}

LinkUp eSIM Activation

Request

{
  "sku": "YOUR_LINKUP_ESIM_SKU",
  "esim": "2",
  "area_code": "213",
  "zip": "90001",
  "imei": "123456789012345",
  "email": "customer@example.com",
  "external_id": "linkup_esim_1001"
}

Success Response JSON

{
  "request_id": "req_31bd88f0",
  "status": "success",
  "transaction_id": "245",
  "product_type": "activation",
  "provider": "linkup",
  "amount_charged": "14.00",
  "environment": "live",
  "data": {
    "provider_status": "APPROVED",
    "provider_transaction_id": "LKE992191",
    "phone_number": "2135551122",
    "qr_code": "base64-or-url-value",
    "sku": "YOUR_LINKUP_ESIM_SKU"
  }
}

Travel eSIM

Request

{
  "plan_id": "123",
  "user_id": "dealer@example.com",
  "external_id": "esim_1001"
}

Success Response JSON

{
  "request_id": "req_0aa9e811",
  "status": "success",
  "transaction_id": "302",
  "product_type": "esim",
  "product_key": "yesim:123",
  "provider": "yesim",
  "amount_charged": "18.50",
  "environment": "live",
  "data": {
    "plan_id": "123",
    "iccid": "8901000000000000000",
    "qr_code": "LPA:1$example$code",
    "balance_after": "723.89"
  }
}

T-Mobile Activation

Request

{
  "plan_id": "TMO_STD_1",
  "sim": "1234567890123456789",
  "pin": "264626",
  "zip_code": "90001",
  "external_id": "tmobile_1001"
}

Accepted / Processing Response JSON

{
  "request_id": "req_8bf0ac44",
  "status": "success",
  "transaction_id": "415",
  "product_type": "activation",
  "product_key": "tmobile:TMO_STD_1",
  "provider": "tmobile",
  "amount_charged": "11.00",
  "environment": "live",
  "data": {
    "job_id": "tm_5042",
    "plan_id": "TMO_STD_1",
    "sku": "YOUR_TMO_SKU"
  }
}

Shipping Label

Request

{
  "from_address": {
    "name": "Sender Name",
    "street1": "123 Main St",
    "city": "Los Angeles",
    "state": "CA",
    "zip": "90001",
    "country": "US"
  },
  "to_address": {
    "name": "Receiver Name",
    "street1": "456 Oak St",
    "city": "Houston",
    "state": "TX",
    "zip": "77001",
    "country": "US"
  },
  "parcel": {
    "length": 8,
    "width": 6,
    "height": 4,
    "weight": 16
  }
}

Success Response JSON

{
  "request_id": "req_21be11d2",
  "status": "success",
  "transaction_id": "510",
  "product_type": "shipping",
  "product_key": "label",
  "provider": "easypost",
  "amount_charged": "4.50",
  "environment": "live",
  "data": {
    "label_id": "shp_123456",
    "tracking_number": "1Z999AA10123456784",
    "label_url": "https://label.example/123.pdf",
    "balance_after": "719.39"
  }
}

Common Error Codes

Code	Meaning
`AUTH_MISSING`	Bearer token was not sent.
`AUTH_INVALID`	Token is invalid.
`SCOPE_DENIED`	Token does not include required scope.
`IDEMPOTENCY_REQUIRED`	Charge endpoint needs `Idempotency-Key`.
`IDEMPOTENCY_CONFLICT`	Same key reused with different payload.
`INSUFFICIENT_BALANCE`	Wallet balance is too low.
`VALIDATION_ERROR`	Required request fields are missing or invalid.
`UPSTREAM_DECLINED`	Provider rejected the request.
`UPSTREAM_ERROR`	Provider connection failed or bad response.
`LIVE_BRIDGE_DISABLED`	Async live bridge is not enabled for that flow yet.

Webhook Format

Use this payload shape for async transaction updates and webhook deliveries.

Webhook Payload

{
  "event": "transaction.success",
  "environment": "test",
  "transaction_id": "123",
  "request_id": "req_xxxxx",
  "product_type": "topup",
  "provider": "linkup",
  "status": "success",
  "data": {}
}

Rules and Notes

Full token value is shown only once when created or replaced.
Always save and reuse your own unique external_id and Idempotency-Key.
Use test token first, then move to production after approval.
Live MobileX and live T-Mobile remain gated until callback-to-wallet reconciliation is fully enabled.