Vela Mobile API Documentation

MW API DOC

Lifecycle

Previous Next

Manage the lifecycle of a SIM card including suspension, disconnection, reconnection, device swapping, balance adjustments, and line management.

Suspend & Restore Service

Suspend Service (Hotline)

Places an MDN on "hotline" status, suspending service.

Endpoint: POST /sim/suspend/

Rate Limit: 20 requests/minute

Authentication: Bearer token required

Request Body

Field Type Required Description
mdn string Yes 10-digit Mobile Number
service string No Specific service to suspend (VOICE/SMS/DATA). If empty, suspends all.
hotline_number string No Number to redirect calls to (if supported)
hotline_chargeable boolean No Whether the hotline status is billable (true/false)
reason string No Optional suspension reason for internal tracking
transaction_id string No Unique Transaction ID (auto-generated with SUSPEND_ prefix if not provided)

Request Example

{
  "mdn": "5550199888",
  "service": "DATA",
  "hotline_number": "5551234567",
  "hotline_chargeable": true,
  "reason": "Lost Device",
  "transaction_id": "SUSPEND_TX123"
}

Response Examples

Success (200 OK):

{
  "status": "success",
  "mdn": "5550199888",
  "transaction_id": "SUSPEND_1C68F4E4797B",
  "message": "Success"
}

Common Errors (400 Bad Request):

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

{
  "status": "failure",
  "mdn": "5550199888",
  "transaction_id": "SUSPEND_B15C731E74B2",
  "message": "SUBSCRIBER STATE NOT IN NEW OR ACTIVE STATE. (935)"
}

Idempotency Error (409 Conflict):

{
  "status": "failure",
  "message": "Transaction ID already exists",
  "code": "HTTP_409"
}

Possible Error Codes

(918), (935), (909), (915), GENS-0183, GENS-0185

For full error details see Error & Response Codes.

Restore Service (Remove Hotline)

Remove "Hotline" status to restore service.

Endpoint: POST /sim/restore/

Rate Limit: 20 requests/minute

Authentication: Bearer token required

Request Body

Field Type Required Description
mdn string Yes 10-digit Mobile Number
service string No Specific service to restore (VOICE/SMS/DATA). If empty, restores all.
transaction_id string No Unique Transaction ID (auto-generated with RESTORE_ prefix if not provided)

Request Example

{
  "mdn": "5550199888",
  "service": "",
  "transaction_id": "RESTORE_TX123"
}

Response Examples

Success (200 OK):

{
  "status": "success",
  "mdn": "5550199888",
  "transaction_id": "RESTORE_1C68F4E4797B",
  "message": "Success"
}

Common Errors (400 Bad Request):

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

{
  "status": "failure",
  "mdn": "5550199888",
  "transaction_id": "RESTORE_B15C731E74B2",
  "message": "MSISDN is not suspended (GENS-0033)"
}

Idempotency Error (409 Conflict):

{
  "status": "failure",
  "message": "Transaction ID already exists",
  "code": "HTTP_409"
}

Possible Error Codes

(918), (909), (915), GENS-0033, GENS-0185

For full error details see Error & Response Codes.

Disconnect & Reconnect

Disconnect Service

Permanently disconnect a subscriber. This action cannot be undone.

Endpoint: POST /sim/disconnect/

Rate Limit: 10 requests/minute

Authentication: Bearer token required

Request Body

Field Type Required Description
mdn string Yes 10-digit Mobile Number
sim string Yes ICCID for verification (alphanumeric, max 25 chars)
acknowledge_final bool Yes Must be true to confirm permanent disconnection
transaction_id string No Unique Transaction ID (auto-generated with DISCONNECT_ prefix if not provided)

Request Example

{
  "mdn": "5550199888",
  "sim": "89014103211118500000",
  "acknowledge_final": true,
  "transaction_id": "DISCONNECT_TX123"
}

Response Examples

Success (200 OK):

{
  "status": "success",
  "mdn": "5550199888",
  "sim": "89014103211118500000",
  "transaction_id": "DISCONNECT_CBB2AA8551CB",
  "message": "Success"
}

Common Errors (400 Bad Request):

{
  "status": "failure",
  "message": "Must acknowledge final disconnection.",
  "code": "HTTP_400"
}

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

{
  "status": "failure",
  "mdn": "5550199888",
  "sim": "89014103211118500000",
  "transaction_id": "DISCONNECT_B15C731E74B2",
  "message": "ESN/MDN is Inactive (915)"
}

Idempotency Error (409 Conflict):

{
  "status": "failure",
  "message": "Transaction ID already exists",
  "code": "HTTP_409"
}

Possible Error Codes

(918), (915), (909), GENS-0065, GENS-0185

For full error details see Error & Response Codes.

Reconnect Service

Reactivates a disconnected SIM (within ~30 days of disconnection).

Endpoint: POST /sim/reconnect/

Rate Limit: 20 requests/minute

Authentication: Bearer token required

Request Body

Field Type Required Description
mdn string Yes 10-digit Mobile Number
sim string Yes ESN or ICCID (alphanumeric, max 25 chars)
plan_id string Yes Plan Code to reactivate with (must be in user's authorized plans)
zip_code string Yes Service ZIP Code (5 digits)
billing_code string No Optional Billing Code (default: BC123)
address1 string No E911 Address Line 1 (Required for WFC)
address2 string No E911 Address Line 2
city string No E911 City (Required for WFC)
state string No E911 State — 2-letter code (Required for WFC)
transaction_id string No Unique Transaction ID (auto-generated with RECONNECT_ prefix if not provided)

Request Example

{
  "mdn": "5550199888",
  "sim": "89014103211118500000",
  "plan_id": "2037",
  "zip_code": "98104",
  "address1": "222 XYZ St",
  "city": "Seattle",
  "state": "WA",
  "transaction_id": "RECONNECT_TX123"
}

Response Examples

Success (200 OK):

{
  "status": "success",
  "mdn": "5550199888",
  "sim": "89014103211118500000",
  "transaction_id": "RECONNECT_1C68F4E4797B",
  "message": "Success"
}

Success with WFC Warning (200 OK):

{
  "status": "success",
  "mdn": "5550199888",
  "sim": "89014103211118500000",
  "transaction_id": "RECONNECT_1C68F4E4797B",
  "message": "Success",
  "warning": "Reconnect Completed Successfully: Failed To Add WFC due to Invalid E911 Address. Please Retry With AddWFC API",
  "wfc_status": false
}

Common Errors (400 Bad Request):

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

{
  "status": "failure",
  "mdn": "5550199888",
  "sim": "89014103211118500000",
  "transaction_id": "RECONNECT_B15C731E74B2",
  "message": "MSISDN is ineligible for reactivation (GENS-0147)"
}

Authorization Error (403 Forbidden):

{
  "status": "failure",
  "message": "Plan ID '2037' is not authorized for user XXX.",
  "code": "HTTP_403"
}

Idempotency Error (409 Conflict):

{
  "status": "failure",
  "message": "Transaction ID already exists",
  "code": "HTTP_409"
}

Possible Error Codes

(918), (915), (909), (906), (910), GENS-0006, GENS-0090, GENS-0147, GENS-0289

For full error details see Error & Response Codes.

Swap SIM

Move an existing MDN to a new SIM card (e.g., device change, lost/stolen SIM).

Endpoint: POST /sim/swap/

Rate Limit: 30 requests/minute

Authentication: Bearer token required

Request Body

Field Type Required Description
mdn string Yes 10-digit Mobile Number
new_sim string Yes New ICCID to activate (alphanumeric, max 25 chars)
old_sim string Yes Current (old) ICCID to deactivate (alphanumeric, max 25 chars)
transaction_id string No Unique Transaction ID (auto-generated with SWAP_ prefix if not provided)

Request Example

{
  "mdn": "5550199888",
  "new_sim": "89014103211118512345",
  "old_sim": "89014103211118500000",
  "transaction_id": "SWAP_TX123"
}

Response Examples

Success (200 OK):

{
  "status": "success",
  "mdn": "5550199888",
  "sim": "89014103211118512345",
  "transaction_id": "SWAP_416DA9294B56",
  "message": "Success"
}

Common Errors (400 Bad Request):

{
  "status": "failure",
  "mdn": "5550199888",
  "sim": "89014103211118512345",
  "transaction_id": "SWAP_DA2647245C12",
  "message": "ESN does not belong to this MVNO (910)"
}

{
  "status": "failure",
  "mdn": "5550199888",
  "sim": "8901240467145154136",
  "transaction_id": "SWAP_4D2DAA0B3C88",
  "message": "ESN/MDN is Inactive (915)"
}

{
  "status": "failure",
  "mdn": "5550199888",
  "sim": "8901240467145154136",
  "transaction_id": "SWAP_41C2B61D142F",
  "message": "INVALID SIM (GENS-0006)"
}

Idempotency Error (409 Conflict):

{
  "status": "failure",
  "message": "Transaction ID already exists",
  "code": "HTTP_409"
}

Possible Error Codes

(910), (915), (918), (909), (506), GENS-0006, GENS-0018, GENS-0012, GENS-0197

For full error details see Error & Response Codes.

Swap MDN

Change the phone number associated with a SIM. Assigns a new MDN from the carrier's number pool.

Endpoint: POST /sim/mdn/swap/

Rate Limit: 20 requests/minute

Authentication: Bearer token required

Request Body

Field Type Required Description
mdn string Yes Current 10-digit Mobile Number
sim string Yes ICCID (alphanumeric, max 25 chars)
zip_code string Yes Zip code for the new number assignment (5 digits)
imei string No Device IMEI (optional, max 15 digits)
transaction_id string No Unique Transaction ID (auto-generated with SWAP_MDN_ prefix if not provided)

Request Example

{
  "mdn": "5550199888",
  "sim": "89014103211118500000",
  "zip_code": "10001",
  "imei": "350336269492124",
  "transaction_id": "SWAP_MDN_TX123"
}

Response Examples

Success (200 OK):

{
  "status": "success",
  "mdn": "5550199888",
  "new_mdn": "5550199999",
  "sim": "89014103211118500000",
  "transaction_id": "SWAP_MDN_CA040EB53477",
  "message": "Success"
}

Common Errors (400 Bad Request):

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

{
  "status": "failure",
  "mdn": "5550199888",
  "transaction_id": "SWAP_MDN_B15C731E74B2",
  "message": "ESN/MDN is Inactive (915)"
}

Idempotency Error (409 Conflict):

{
  "status": "failure",
  "message": "Transaction ID already exists",
  "code": "HTTP_409"
}

Possible Error Codes

(918), (915), (909), (910), GENS-0011, GENS-0289

For full error details see Error & Response Codes.

Balance Adjustment

Manually adjust a subscriber's balance. Use the single adjustment endpoint for one subscription, or the multiple adjustment endpoint for bulk corrections across several subscriptions.

Superuser Only

Balance adjustment endpoints require superuser privileges. Non-superuser requests will receive HTTP 403 Forbidden.

Adjust Single Balance

Add or deduct balance from a single subscription.

Endpoint: POST /sim/balance/adjust/

Rate Limit: 20 requests/minute

Authentication: Bearer token required (superuser)

Request Body

Field Type Required Description
mdn string Yes 10-digit Mobile Number
subscription_id string Yes Subscription/purchase ID to adjust
uom string No Unit of measure: SECOND (voice), EVENT (SMS), or BYTE (data)
amount integer No Positive to add, negative to deduct
expiry_date string No Expiry date for the adjustment in YYYY-MM-DD format
transaction_id string No Unique Transaction ID (auto-generated with ADJ_BAL_ prefix if not provided)

Request Example

{
  "mdn": "5550199888",
  "subscription_id": "1125899982205364",
  "uom": "EVENT",
  "amount": 500,
  "expiry_date": "2026-04-15",
  "transaction_id": "ADJ_BAL_TX123"
}

Response Examples

Success (200 OK):

{
  "status": "success",
  "mdn": "5550199888",
  "transaction_id": "ADJ_BAL_1C68F4E4797B",
  "message": "Success"
}

Common Errors (400 Bad Request):

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

{
  "status": "failure",
  "mdn": "5550199888",
  "transaction_id": "ADJ_BAL_B15C731E74B2",
  "message": "Invalid SUBSCRIPTIONID. (919)"
}

Authorization Error (403 Forbidden):

{
  "detail": "The user doesn't have enough privileges"
}

Idempotency Error (409 Conflict):

{
  "status": "failure",
  "message": "Transaction ID already exists",
  "code": "HTTP_409"
}

Validation Error (422 Unprocessable Entity):

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body", "uom"],
      "msg": "Value error, UOM must be one of: SECOND, EVENT, BYTE"
    }
  ]
}

Possible Error Codes

(918), (919), (920), (909), (915)

For full error details see Error & Response Codes.

Adjust Multiple Balances

Adjust balances across multiple subscriptions in a single request.

Endpoint: POST /sim/balance/adjust-multiple/

Rate Limit: 20 requests/minute

Authentication: Bearer token required (superuser)

Request Body

Field Type Required Description
mdn string Yes 10-digit Mobile Number
adjustments array Yes List of balance adjustments
adjustments[].subscription_id string Yes Subscription/purchase ID
adjustments[].uom string Yes Unit of measure: SECOND, EVENT, or BYTE
adjustments[].amount integer Yes Positive to add, negative to deduct
transaction_id string No Unique Transaction ID (auto-generated with ADJ_MULTI_BAL_ prefix if not provided)

Request Example

{
  "mdn": "5550199888",
  "adjustments": [
    {
      "subscription_id": "1125899982205364",
      "uom": "EVENT",
      "amount": 500
    },
    {
      "subscription_id": "1125899982205365",
      "uom": "SECOND",
      "amount": 3000
    },
    {
      "subscription_id": "1125899982205366",
      "uom": "BYTE",
      "amount": 1073741824
    }
  ],
  "transaction_id": "ADJ_MULTI_BAL_TX123"
}

Response Examples

Success (200 OK):

{
  "status": "success",
  "mdn": "5550199888",
  "transaction_id": "ADJ_MULTI_BAL_1C68F4E4797B",
  "message": "Success"
}

Common Errors (400 Bad Request):

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

{
  "status": "failure",
  "mdn": "5550199888",
  "transaction_id": "ADJ_MULTI_BAL_B15C731E74B2",
  "message": "Invalid SUBSCRIPTIONID. (919)"
}

Authorization Error (403 Forbidden):

{
  "detail": "The user doesn't have enough privileges"
}

Idempotency Error (409 Conflict):

{
  "status": "failure",
  "message": "Transaction ID already exists",
  "code": "HTTP_409"
}

Possible Error Codes

(918), (919), (920), (909), (915)

For full error details see Error & Response Codes.

Line Management

Manage shared/family plan line associations by adding or removing child lines from a parent account.

Add Child Line

Add a child line to a parent account for shared/family plan configurations.

Endpoint: POST /sim/line/add/

Rate Limit: 20 requests/minute

Authentication: Bearer token required

Request Body

Field Type Required Description
parent_mdn string Yes 10-digit parent (primary) Mobile Number
parent_sim string Yes Parent SIM identifier (ICCID) — alphanumeric, max 25 characters
child_mdn string Yes 10-digit child Mobile Number to add
child_sim string No Child SIM identifier (ICCID) — alphanumeric, max 25 characters
transaction_id string No Unique Transaction ID (auto-generated with ADD_LINE_ prefix if not provided)

Request Example

{
  "parent_mdn": "5550199888",
  "parent_sim": "89014103211118500000",
  "child_mdn": "5550198765",
  "child_sim": "89014103211118500001",
  "transaction_id": "ADD_LINE_TX123"
}

Response Examples

Success (200 OK):

{
  "status": "success",
  "mdn": "5550199888",
  "transaction_id": "ADD_LINE_1C68F4E4797B",
  "message": "Success"
}

Common Errors (400 Bad Request):

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

{
  "status": "failure",
  "mdn": "5550199888",
  "transaction_id": "ADD_LINE_B15C731E74B2",
  "message": "ESN/MDN is Inactive (915)"
}

Idempotency Error (409 Conflict):

{
  "status": "failure",
  "message": "Transaction ID already exists",
  "code": "HTTP_409"
}

Possible Error Codes

(918), (915), (909), (910)

For full error details see Error & Response Codes.

Remove Child Line

Remove a child line from a parent account.

Endpoint: POST /sim/line/remove/

Rate Limit: 20 requests/minute

Authentication: Bearer token required

Request Body

Field Type Required Description
parent_mdn string Yes 10-digit parent (primary) Mobile Number
parent_sim string Yes Parent SIM identifier (ICCID) — alphanumeric, max 25 characters
child_mdn string Yes 10-digit child Mobile Number to remove
child_sim string No Child SIM identifier (ICCID) — alphanumeric, max 25 characters
transaction_id string No Unique Transaction ID (auto-generated with REM_LINE_ prefix if not provided)

Request Example

{
  "parent_mdn": "5550199888",
  "parent_sim": "89014103211118500000",
  "child_mdn": "5550198765",
  "transaction_id": "REM_LINE_TX123"
}

Response Examples

Success (200 OK):

{
  "status": "success",
  "mdn": "5550199888",
  "transaction_id": "REM_LINE_1C68F4E4797B",
  "message": "Success"
}

Common Errors (400 Bad Request):

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

{
  "status": "failure",
  "mdn": "5550199888",
  "transaction_id": "REM_LINE_B15C731E74B2",
  "message": "ESN/MDN is Inactive (915)"
}

Idempotency Error (409 Conflict):

{
  "status": "failure",
  "message": "Transaction ID already exists",
  "code": "HTTP_409"
}

Possible Error Codes

(918), (915), (909), (910)

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 or superuser-only endpoint)
409 Conflict (duplicate transaction_id)
422 Validation error (invalid state code, ZIP format, MDN format)
429 Rate limit exceeded
500 Internal server error

Full error reference: Error & Response Codes

Plans Features