Vela Mobile API Documentation

MW API DOC

Queries

Previous Next

Retrieve information about subscriber usage, network coverage (quick & detailed), and device compatibility.

Usage & Balance

Get current usage and balance details for a subscriber.

Endpoint: GET /sim/usage/{mdn}

Rate Limit: 60 requests/minute

Authentication: Bearer token required

Request Parameters

Parameter Location Type Required Description
mdn Path string Yes 10-digit Mobile Number

Response Examples

Success (200 OK):

{
  "mdn": "5550199888",
  "sim": "89014103211118500000",
  "status": "ACTIVE",
  "customer_id": "1001",
  "plan_name": "Vm39Travelnd",
  "effective_date": "2026-01-15 11:05:09",
  "balance_details": {
    "talk": 500,
    "text": 1000,
    "data": 2048
  },
  "subscriptions": [
    {
      "purchase_id": "1125899982205364",
      "plan_code": "24",
      "plan_name": "Vm39Travelnd",
      "balances": [
        {
          "uom": "EVENT",
          "balance": 500,
          "valid_from": "2026-01-15 11:05:09",
          "valid_to": "2026-02-14 11:05:09"
        },
        {
          "uom": "SECOND",
          "balance": 6000,
          "valid_from": "2026-01-15 11:05:09",
          "valid_to": "2026-02-14 11:05:09"
        }
      ]
    }
  ]
}

Common Errors (400 Bad Request):

{
  "status": "failure",
  "message": "MDN DOES NOT BELONG TO THIS VENDOR (909)",
  "errors": [
    "MDN DOES NOT BELONG TO THIS VENDOR (909)"
  ]
}

{
  "status": "failure",
  "message": "SUBSCRIBER WITH GIVEN RESOURCE NOT EXISTS. (918)",
  "errors": [
    "SUBSCRIBER WITH GIVEN RESOURCE NOT EXISTS. (918)"
  ]
}

Possible Error Codes

(918), (909), (915)

For full error details see Error & Response Codes.

Full Service Information

Retrieve the complete subscriber profile including service codes (SOCs), plan details, balance information, E911 address, and hotline status. Provides more detail than the balance-only usage query.

Endpoint: GET /sim/service/{mdn}

Rate Limit: 60 requests/minute

Authentication: Bearer token required

Request Parameters

Parameter Location Type Required Description
mdn Path string Yes 10-digit Mobile Number
sim Query string No SIM identifier (ICCID) for additional verification — alphanumeric, max 25 characters

Response Schema

Field Type Description
mdn string 10-digit Mobile Number
sim string SIM identifier (ICCID)
imei string Device IMEI
status string Subscriber status (e.g., ACTIVE, SUSPENDED)
plan_name string Current plan name
effective_date string Plan effective date
bill_cycle_day string Billing cycle day of month
service_codes array List of provisioned service codes (SOCs)
service_codes[].code string Service order code identifier
service_codes[].effective_date string Date the SOC was provisioned
balance_details object Aggregated balance summary
balance_details.talk number Remaining voice minutes
balance_details.text number Remaining text messages
balance_details.data number Remaining data (bytes)
subscriptions array Active subscription details with balances
e911_address object Registered E911 address (if WFC enabled)
hotline_status string Hotline/suspension status
hotline_number string Redirect number (if hotlined)
message string Human-readable status message

Response Examples

Success (200 OK):

{
  "mdn": "5550199888",
  "sim": "89014103211118500000",
  "imei": "350336269492124",
  "status": "ACTIVE",
  "plan_name": "Vm39Travelnd",
  "effective_date": "2026-01-15 11:05:09",
  "bill_cycle_day": "15",
  "service_codes": [
    {
      "code": "VOLTE",
      "effective_date": "2026-01-15"
    },
    {
      "code": "IMS",
      "effective_date": "2026-01-15"
    },
    {
      "code": "LTE",
      "effective_date": "2026-01-15"
    }
  ],
  "balance_details": {
    "talk": 500,
    "text": 1000,
    "data": 2048
  },
  "subscriptions": [
    {
      "purchase_id": "1125899982205364",
      "plan_code": "24",
      "plan_name": "Vm39Travelnd",
      "balances": [
        {
          "uom": "EVENT",
          "balance": 500,
          "valid_from": "2026-01-15 11:05:09",
          "valid_to": "2026-02-14 11:05:09"
        },
        {
          "uom": "SECOND",
          "balance": 6000,
          "valid_from": "2026-01-15 11:05:09",
          "valid_to": "2026-02-14 11:05:09"
        }
      ]
    }
  ],
  "e911_address": {
    "address1": "222 XYZ St",
    "city": "Seattle",
    "state": "WA",
    "zip_code": "98104"
  },
  "hotline_status": null,
  "hotline_number": null,
  "message": "Success"
}

Common Errors (400 Bad Request):

{
  "status": "failure",
  "message": "SUBSCRIBER WITH GIVEN RESOURCE NOT EXISTS. (918)"
}

{
  "status": "failure",
  "message": "MDN DOES NOT BELONG TO THIS VENDOR (909)"
}

Possible Error Codes

(918), (909), (915)

For full error details see Error & Response Codes.

T-Mobile Usage Query

Query raw usage data directly from T-Mobile for a subscriber. Useful for investigating usage discrepancies that the OCS balance query does not explain.

Endpoint: GET /sim/usage/tmo/{mdn}

Rate Limit: 60 requests/minute

Authentication: Bearer token required

Request Parameters

Parameter Location Type Required Description
mdn Path string Yes 10-digit Mobile Number

Response Schema

Field Type Description
mdn string 10-digit Mobile Number
status string Response status (success or failure)
usage_records array List of raw T-Mobile usage records
message string Human-readable status message

Response Examples

Success (200 OK):

{
  "mdn": "5550199888",
  "status": "success",
  "usage_records": [
    {
      "type": "VOICE",
      "duration": 120,
      "timestamp": "2026-03-15 10:30:00",
      "destination": "5550198765"
    },
    {
      "type": "DATA",
      "bytes_used": 52428800,
      "timestamp": "2026-03-15 11:00:00"
    },
    {
      "type": "SMS",
      "count": 1,
      "timestamp": "2026-03-15 12:15:00",
      "destination": "5550197654"
    }
  ],
  "message": "Success"
}

Common Errors (400 Bad Request):

{
  "status": "failure",
  "message": "SUBSCRIBER WITH GIVEN RESOURCE NOT EXISTS. (918)"
}

{
  "status": "failure",
  "message": "MDN DOES NOT BELONG TO THIS VENDOR (909)"
}

Possible Error Codes

(918), (909), (915)

For full error details see Error & Response Codes.

Coverage Check

Check network coverage for a specific location.

Endpoint: GET /sim/coverage/{zip_code}

Rate Limit: 60 requests/minute

Authentication: Bearer token required

Request Parameters

Parameter Location Type Required Description
zip_code Path string Yes 5-digit US Zip Code (e.g. 90210)

Response Examples

Covered (200 OK):

{
  "zip_code": "90210",
  "covered": true,
  "status": "success",
  "areas": [
    {
      "city": "BEVERLY HILLS",
      "state": "CA",
      "zip_code": "90210",
      "quality": "SPW,BEVERLY HILLS,CA 90210"
    }
  ],
  "message": "Success"
}

Not Covered (200 OK):

{
  "zip_code": "00000",
  "covered": false,
  "status": "failure",
  "areas": [],
  "message": "Invalid Zipcode"
}

Possible Error Codes

(510), GENS-0289

For full error details see Error & Response Codes.

Quick Coverage Check

Simple check if a zip code has coverage (Activation Eligible).

Endpoint: GET /sim/coverage/quick/{zip_code}

Rate Limit: 60 requests/minute

Authentication: Bearer token required

Request Parameters

Parameter Location Type Required Description
zip_code Path string Yes 5-digit Zip Code

Response Examples

Covered (200 OK):

{
  "zip_code": "90210",
  "covered": true,
  "status": "success",
  "message": "Activation Eligible: TRUE"
}

Not Covered (200 OK):

{
  "zip_code": "47896",
  "covered": false,
  "status": "success",
  "message": "Activation Eligible: False"
}

Possible Error Codes

(510), GENS-0289

For full error details see Error & Response Codes.

Device Compatibility Check

Check if a device (IMEI) is compatible with the network.

Endpoint: GET /sim/device/{imei}

Rate Limit: 60 requests/minute

Authentication: Bearer token required

Request Parameters

Parameter Location Type Required Description
imei Path string Yes 15-digit Device IMEI

Response Examples

Compatible (200 OK):

{
  "imei": "350336269492124",
  "compatible": true,
  "status": "success",
  "status_code": "SUCCESS",
  "technology": "5G",
  "sim_type": "NANO",
  "sim_size": "NANO",
  "message": "VOICE DEVICE FULLY COMPATIBLE",
  "model": "SM-G991U",
  "manufacturer": "SAMSUNG",
  "marketing_name": "GALAXY S21 5G ENTERPRISE EDITION",
  "os_name": "ANDROID",
  "esim_capable": true,
  "volte_capable": true,
  "wifi_calling_capable": true,
  "network_approved": true
}

Not Compatible (200 OK):

{
  "imei": "123456789012345",
  "compatible": false,
  "status": "failure",
  "status_code": "FAILURE",
  "technology": null,
  "sim_type": null,
  "sim_size": null,
  "message": "DEVICE NOT FOUND",
  "model": null,
  "manufacturer": null,
  "marketing_name": null,
  "os_name": null,
  "esim_capable": false,
  "volte_capable": false,
  "wifi_calling_capable": false,
  "network_approved": false
}

Possible Error Codes

(506)

For full error details see Error & Response Codes.

Query Network Status

Query the Home Location Register (HLR) for network status.

Endpoint: GET /sim/network/{mdn}

Rate Limit: 60 requests/minute

Authentication: Bearer token required

Request Parameters

Parameter Location Type Required Description
mdn Path string Yes 10-digit Mobile Number

Response Examples

Success (200 OK):

{
  "mdn": "5550199888",
  "status": "success",
  "sim": "8901260812345678901",
  "imei": "1234567890760222",
  "imsi": "310260856401305",
  "sim_status": "INUSE",
  "service_codes": [
    "CAMEL",
    "CLW",
    "ISP",
    "3WY",
    "NOROAM",
    "IMS",
    "HOLD",
    "CLIR",
    "VOLTE",
    "SMSO",
    "CLIP",
    "LTE",
    "VM",
    "MVNO"
  ],
  "message": "SUCCESS"
}

Common Errors (400 Bad Request):

{
  "status": "failure",
  "mdn": "5550199888",
  "message": "SUBSCRIBER WITH GIVEN RESOURCE NOT EXISTS. (918)"
}

{
  "status": "failure",
  "mdn": "5550199888",
  "message": "MDN does not belong to this vendor (909)"
}

Possible Error Codes

(918), (909), (915)

For full error details see Error & Response Codes.

eSIM Profile

Retrieve the eSIM activation profile for a SIM, including the activation code and QR code details needed for eSIM provisioning.

Endpoint: GET /sim/esim/{sim}

Rate Limit: 60 requests/minute

Authentication: Bearer token required

Request Parameters

Parameter Location Type Required Description
sim Path string Yes SIM identifier (ICCID) — alphanumeric, max 25 characters

Response Schema

Field Type Description
sim string SIM identifier
status string Response status (success or failure)
activation_code string eSIM activation code for QR provisioning
matching_id string eSIM matching identifier
profile_state string Current state of the eSIM profile
profile_type string Type of eSIM profile
esim_brand string eSIM brand (e.g., PWGQR)
last_modified string Timestamp of last profile modification
message string Human-readable status message

Response Examples

Success (200 OK):

{
  "sim": "89014103211118512345",
  "status": "success",
  "activation_code": "LPA:1$smdp.example.com$ABCDEF1234567890",
  "matching_id": "M-1234-ABCD-5678",
  "profile_state": "AVAILABLE",
  "profile_type": "CONSUMER",
  "esim_brand": "PWGQR",
  "last_modified": "2026-03-15 14:30:00",
  "message": "Success"
}

Common Errors (400 Bad Request):

{
  "status": "failure",
  "sim": "89014103211118512345",
  "message": "Invalid ESN. (506)"
}

{
  "status": "failure",
  "sim": "89014103211118512345",
  "message": "eSIM Profile already completed and mapped. (8011)"
}

{
  "status": "failure",
  "sim": "89014103211118512345",
  "message": "eSIM Not Available for MVNO (8010)"
}

Possible Error Codes

(506), (8011), (8010), (918)

For full error details see Error & Response Codes.

Query SIM Details

Retrieve detailed information about a SIM card including activation eligibility, WFC eligibility, and PUK codes.

Endpoint: GET /sim/details/{sim}

Rate Limit: 60 requests/minute

Authentication: Bearer token required

Request Parameters

Parameter Location Type Required Description
sim Path string Yes SIM identifier (ICCID) — alphanumeric, max 25 characters

Response Examples

Success (200 OK):

{
  "sim": "8901240467112150588",
  "status": "success",
  "activation_eligible": true,
  "wfc_eligible": true,
  "puk1": "28912956",
  "puk2": "65087119",
  "create_date": "2024-04-04T02:19:15Z",
  "expiration_date": "2027-04-04T00:00:00.000-07:00",
  "iccid_status": "AVAILABLE",
  "message": "SUCCESS"
}

Invalid SIM (400 Bad Request):

{
  "sim": "8901240461215045",
  "status": "failure",
  "activation_eligible": false,
  "wfc_eligible": false,
  "puk1": null,
  "puk2": null,
  "create_date": null,
  "expiration_date": null,
  "iccid_status": null,
  "message": "Invalid ESN. (506)"
}

{
  "sim": "89014103211118500000",
  "status": "failure",
  "activation_eligible": false,
  "wfc_eligible": false,
  "puk1": null,
  "puk2": null,
  "create_date": null,
  "expiration_date": null,
  "iccid_status": null,
  "message": "ESN does not belong to this MVNO (910)"
}

Possible Error Codes

(506), (910), (918)

For full error details see Error & Response Codes.

Common HTTP Errors (All Endpoints on This Page)

HTTP Code Meaning
400 Bad request / upstream carrier operation failed
401 Not authenticated (missing or invalid Bearer token)
403 Forbidden (insufficient permissions)
422 Validation error (invalid MDN format, IMEI format, ZIP format)
429 Rate limit exceeded
500 Internal server error

Full error reference: Error & Response Codes

Features Extended Operations