Mobilexy - eSIM - Developer - Api Documentation

Introduction

Welcome to the Mobilexy - eSIM API documentation.

This API allows you to integrate eSIM purchasing and management capabilities directly into your application. You can retrieve coverage information, view plans, check your balance, and purchase eSIMs programmatically.

All responses are returned in JSON format. The API accepts both GET and POST requests depending on the endpoint.

Authentication

Authenticating your API requests.

Most endpoints require authentication using your API Key. You can find your API Key in your dashboard explicitly. Include the api_key parameter in your request body or query string for authenticated endpoints.

List Countries

Retrieve a list of all supported countries.

Endpoint: https://mobilexy.com/api/coverage/countries

Method: GET

Response Parameters

Name	Type	Description
countries	array	List of country objects
countries[].name	string	Country name
countries[].slug	string	Country identifier slug
countries[].image	string	Country flag image URL
countries[].converted_price	string	Starting price for plans

Response


{
    "remark": "countries",
    "status": "success",
    "message": ["Countries List"],
    "data": {
        "countries": [
            {
                "name": "Afghanistan",
                "slug": "afghanistan",
                "image": null,
                "converted_price": "8.12000000"
            },
            {
                "name": "Aland Islands",
                "slug": "aland-islands",
                "image": null,
                "converted_price": "6.14000000"
            }
        ]
    }
}

List Regions

Retrieve a list of all supported regions.

Endpoint: https://mobilexy.com/api/coverage/regions

Method: GET

Response Parameters

Name	Type	Description
regions	array	List of region objects
regions[].name	string	Region name
regions[].slug	string	Region identifier slug
regions[].plan_count	integer	Number of available plans

Response

{
    "remark": "regions",
    "status": "success",
    "message": ["Regions List"],
    "data": {
        "regions": [
            {
                "name": "Africa (AF-29)",
                "slug": "africa-af-29",
                "image": null,
                "plan_count": 3
            },
            {
                "name": "Asia (AS-12)",
                "slug": "asia-as-12",
                "image": null,
                "plan_count": 10
            }
        ]
    }
}

Country Plans

Get plans for a specific country.

Endpoint: https://mobilexy.com/api/country-plans/{slug}

Method: GET

Replace {slug} with the country slug (e.g., afghanistan).

Response Parameters

Name	Type	Description
plans	array	List of plan objects
plans[].id	integer	Plan ID
plans[].name	string	Plan name
plans[].period	integer	Validity period in days
plans[].data_volume	integer	Data amount in bytes (-1 for unlimited)
plans[].converted_price	string	Price of the plan

Response

{
    "remark": "country_plan",
    "status": "success",
    "message": ["Afghanistan eSIM Plans"],
    "data": {
        "plans": [
            {
                "id": 855,
                "slug": "AF_0.5_Daily",
                "name": "Afghanistan 500MB/Day",
                "period": 1,
                "package_type": "DATA",
                "data_volume": -1,
                "voice_quantity": "0.00",
                "sms_quantity": 0,
                "fup_policy_text": "500MB high-speed/day, 512 Kbps after limit, resets daily",
                "phone_number": 0,
                "operator_name": "Etisalat",
                "operator_slug": null,
                "network_speed": "3G",
                "area_coverage": "local",
                "status": 1,
                "converted_price": "8.12000000",
                "currency": null
                "packageCode": "CKH226"
            },
        ],
        "flag": "url_to_flag_image",
        "flagCode": "US"
    }
}

Region Plans

Get plans for a specific region.

Endpoint: https://mobilexy.com/api/region-plans/{slug}

Method: GET

Replace {slug} with the region slug (e.g., europe).

Response Parameters

Name	Type	Description
plans	array	List of plan objects
plans[].countries	array	List of countries included in the region
plans[].countries[].name	string	Country name

Response

{
    "remark": "region_plan",
    "status": "success",
    "message": ["Asia (AS-12) eSIM Plans"],
    "data": {
        "plans": [
            {
                "id": 855,
                "slug": "AS-12_0.5_Daily",
                "name": "Asia (12 areas) 500MB/Day",
                "period": 1,
                "package_type": "DATA",
                "data_volume": -1,
                "voice_quantity": "0.00",
                "sms_quantity": 0,
                "fup_policy_text": "500MB high-speed/day, 128 Kbps after limit, resets daily",
                "operator_name": "Metfone, China Unicom, csl, Telkomsel, KDDI/au, CTM, CelcomDigi, Maxis, SingTel, SKTelecom, LG U+, Chunghwa, DTAC, TrueMove H, MobiFone, Viettel Mobile, Vietnamobile",
                "operator_slug": null,
                "network_speed": "3G/4G",
                "area_coverage": "continental",
                "status": 1,
                "converted_price": "7.28000000",
                "currency": null,
                "packageCode": "CKH226"
                "countries": [
                    {
                        "name": "Hong Kong (China)",
                        "slug": "hong-kong-china",
                        "image": null
                    },
                    {
                        "name": "Macao (China)",
                        "slug": "macao-china",
                        "image": null
                    },
                ]
            }
        ],
        "flag": "url_to_image"
    }
}

Global Plans

Get global eSIM plans.

Endpoint: https://mobilexy.com/api/global-plans

Method: GET

Response Parameters

Name	Type	Description
plans	array	List of global plan objects
plans[].countries	array	List of supported countries

Response

{
    "remark": "global_plan",
    "status": "success",
    "message": ["Global eSIM Plans"],
    "data": {
       "plans": [
            {
                "id": 855,
                "slug": "AS-12_0.5_Daily",
                "name": "Asia (12 areas) 500MB/Day",
                "period": 1,
                "package_type": "DATA",
                "data_volume": -1,
                "voice_quantity": "0.00",
                "sms_quantity": 0,
                "fup_policy_text": "500MB high-speed/day, 128 Kbps after limit, resets daily",
                "operator_name": "Metfone, China Unicom, csl, Telkomsel, KDDI/au, CTM, CelcomDigi, Maxis, SingTel, SKTelecom, LG U+, Chunghwa, DTAC, TrueMove H, MobiFone, Viettel Mobile, Vietnamobile",
                "operator_slug": null,
                "network_speed": "3G/4G",
                "area_coverage": "continental",
                "status": 1,
                "converted_price": "7.28000000",
                "currency": null,
                "packageCode": "CKH226"
                "countries": [
                    {
                        "name": "Hong Kong (China)",
                        "slug": "hong-kong-china",
                        "image": null
                    },
                    {
                        "name": "Macao (China)",
                        "slug": "macao-china",
                        "image": null
                    },
                ]
            }
        ],
        "flag": "url_to_globe_image"
    }
}

Check Balance

Check your account balance.

Endpoint: https://mobilexy.com/api/balance

Method: POST

Parameters

Name	Type	Description
api_key	string	Required Your API Key

Response Parameters

Name	Type	Description
balance	float	Current account balance

Request Example (PHP)

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://mobilexy.com/api/balance',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => array(
    'api_key' => 'YOUR_API_KEY'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>

Response

{
    "remark": "balance",
    "status": "success",
    "message": ["Account balance"],
    "data": {
        "balance": 100.00
    }
}

Plan Details

Get details of a specific plan.

Endpoint: https://mobilexy.com/api/plan/{id}

Method: GET

Replace {id} with the plan ID.

Response Parameters

Name	Type	Description
plan	object	Plan details object
plan.name	string	Plan name
plan.voice_quantity	integer	Voice quantity in minutes
plan.sms_quantity	integer	SMS quantity. -1 for unlimited

Response

{
    "remark": "plan_details",
    "status": "success",
    "message": ["Plan Details"],
    "data": {
         "plan": {
            "id": 811,
            "slug": "AS-12_3_30",
            "name": "Asia (12 areas) 3GB 30Days",
            "period": 30,
            "package_type": "DATA",
            "data_volume": 3221225472,
            "voice_quantity": "0.00",
            "sms_quantity": 0,
            "fup_policy_text": "",
            "operator_name": "Metfone, China Unicom, csl, Telkomsel, KDDI/au, CTM, CelcomDigi, Maxis, SingTel, SKTelecom, LG U+, Chunghwa, DTAC, TrueMove H, MobiFone, Viettel Mobile, Vietnamobile",
            "operator_slug": null,
            "network_speed": "3G/4G",
            "area_coverage": "continental"
            "packageCode": "CKH226"
        }
    }
}

Purchase Plan

Purchase an eSIM plan.

Endpoint: https://mobilexy.com/api/plan/purchase

Method: POST

Request Parameters

Name	Type	Description
api_key	string	Required Your API Key
plan_id	integer	Required ID of the plan to purchase

Response Parameters

Name	Type	Description
order	object	Order details
order.order_number	string	Unique order number
esim	object	eSIM details
esim.qr_code	string	LPA string for eSIM activation

Request Example (PHP)

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://mobilexy.com/api/plan/purchase',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => array(
    'api_key' => 'YOUR_API_KEY',
    'plan_id' => '10'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Response

{
    "remark": "order_completed",
    "status": "success",
    "message": ["Order completed successfully"],
    "data": {
        "order": {
            "order_number": "GW7DUVMKGO",
            "total_amount": "6.20000000",
            "status": 0
        },
        "esim": {
            "serial_number": 2147483647,
            "iccid": null,
            "phone_number": "0840358292",
            "qr_code": "LPA:1$ais.prod.ondemandconnectivity.com$SEW7JEBMFGPRVSPD",
            "qr_code_image": null,
            "expiry_date": "2025-08-05",
            "info": null
        }
    }
}

Manage Profile - Top Up

Top up the data service of an existing installed eSIM with a new plan.

Endpoint: https://mobilexy.com/api/profile/topup

Method: POST

Request Parameters

Name	Type	Description
api_key	string	Required Your API Key
esimTranNo	string	Required Single eSIM transaction number
packageCode	string	Required Top up package code (provider package code)

Response Parameters

Name	Type	Description
transactionId	string	Transaction ID
iccid	string	ICCID of the topped-up eSIM
expiredTime	long	New package expiry (ISO timestamp)
totalVolume	long	New total data balance in bytes
totalDuration	integer	New validity period in days
orderUsage	long	Total package usage in bytes

Request Example (PHP)

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://mobilexy.com/api/profile/topup',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => array(
    'api_key' => 'YOUR_API_KEY',
    'esimTranNo' => '26021613280014',
    'packageCode' => 'PFRQ8FIBC'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Response

{
    "remark": "topup_completed",
    "status": "success",
    "message": {
        "success": [
            "Top up completed successfully"
        ]
    },
    "data": {
        "success": true,
        "errorCode": null,
        "errorMsg": null,
        "obj": {
            "transactionId": "MBL-RGNRTU9DAK_1771248518",
            "iccid": "8910300000056693431",
            "expiredTime": "2026-03-30T07:37:12+0000",
            "totalVolume": 6442450944,
            "totalDuration": 42,
            "orderUsage": 0,
            "topUpEsimTranNo": "26021613280014"
        }
    }
}

Usage Check

Retrieve the latest data usage snapshot (in bytes) for up to 10 eSIMs by their esimTranNo. Usage data is refreshed every 2–3 hours by the carrier and is not real-time.

Endpoint: https://mobilexy.com/api/profile/usage-check

Method: POST

Request Parameters

Name	Type	Description
api_key	string	Required Your API Key
iccid	string	ICCID that resolves to an eSIM owned by the account
esimTranNo	string	Single eSIM transaction number. Use when checking one profile
esimTranNos	array	Up to 10 esimTranNo values to query together.

Response Parameters

Name	Type	Description
success	string	true: succeeded, false: failed
obj.usageList	object	One entry per requested eSIM with usage data
dataUsage	long	Current data usage in bytes
totalData	long	Plan allowance in bytes
lastUpdateTime	string	Timestamp of the latest usage update

Request Example (PHP)

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://mobilexy.com/api/profile/usage-check',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => array(
    'api_key' => 'YOUR_API_KEY',
    'iccid' => '8948010010002120847'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Response

{
    "success": true,
    "errorCode": "0",
    "errorMsg": null,
    "obj": {
        "usageList": [
            {
                "esimTranNo": "26021607100025",
                "dataUsage": 0,
                "totalData": 1073741824,
                "lastUpdateTime": "2026-02-16T07:10:58+0000"
            }
        ]
    }
}
}

Virtual Numbers API

Use these endpoints to search, purchase and manage virtual numbers through your API account.

Virtual number endpoints use the same API key authentication as the eSIM endpoints. Pass api_key in the query string or request body. Bearer token authentication is also supported where available.

Prices are returned in USD. Purchasing a virtual number through the API uses the partner wallet balance directly. The customer must have enough balance before calling the purchase endpoint.

Available numbers are cached for a short time because Roamlinx offer tokens expire. If an offer token expires, request the available numbers endpoint again and use the new offerToken.

Virtual Number Countries

Retrieve enabled countries for virtual numbers. Use with_price=1 to return only countries that currently have a cached starting price.

Endpoint: https://mobilexy.com/api/virtual-numbers/countries

Method: GET

Request Parameters

Name	Required	Type	Description
api_key	Yes	string	Your API key
with_price	No	boolean	Set to 1 to return only countries with cached minimum price

Response Parameters

Name	Type	Description
countries	array	List of enabled virtual number country objects
countries[].country_code	string	ISO country code
countries[].country_name	string	Country name
countries[].min_retail_price	decimal	Minimum current retail price in USD when available
countries[].cached_numbers_count	integer	Number of currently cached available offers
countries[].types	array	Available number types, when provided by Roamlinx

Request Example

curl "https://mobilexy.com/api/virtual-numbers/countries?api_key=YOUR_API_KEY&with_price=1"

Response

{
    "remark": "virtual_number_countries",
    "status": "success",
    "message": ["Virtual number countries"],
    "data": {
        "countries": [
            {
                "country_code": "AR",
                "country_name": "Argentina",
                "min_retail_price": "8.33000000",
                "cached_numbers_count": 10,
                "types": ["local"]
            }
        ]
    }
}

Available Virtual Numbers

Search available virtual numbers. The returned offerToken is required to purchase the number and expires after a short time.

Endpoint: https://mobilexy.com/api/virtual-numbers/available

Method: GET

Request Parameters

Name	Required	Type	Description
api_key	Yes	string	Your API key
country	No	string	ISO country code, for example AR
type	No	string	Number type, for example local, mobile, tollfree, national
features	No	string	Comma separated features when supported, for example voice_in,sms_in
numberPrefix	No	string	Optional number prefix filter

Request Example

curl "https://mobilexy.com/api/virtual-numbers/available?api_key=YOUR_API_KEY&country=AR&type=local"

Response

{
    "remark": "virtual_numbers_available",
    "status": "success",
    "message": ["Available virtual numbers"],
    "data": {
        "success": true,
        "obj": {
            "items": [
                {
                    "offerToken": "OFFER_TOKEN_HERE",
                    "number": "542494401315",
                    "country": "AR",
                    "countryName": "Argentina",
                    "type": "local",
                    "features": ["voice_in", "voice_out"],
                    "setupPrice": "0.00",
                    "monthlyPrice": "8.33",
                    "currency": "USD",
                    "offerExpiresInSec": 600
                }
            ]
        }
    }
}

Purchase Virtual Number

Purchase a virtual number with a valid offerToken. The amount is deducted from the API user balance.

Endpoint: https://mobilexy.com/api/virtual-numbers/order

Method: POST

Request Parameters

Name	Required	Type	Description
api_key	Yes	string	Your API key
offerToken	Yes	string	Offer token returned by the available numbers endpoint
number	No	string	Number shown to the customer; used for local order display
country	No	string	ISO country code
type	No	string	Number type
setupPrice	No	decimal	Provider setup price from the available response
monthlyPrice	No	decimal	Provider monthly price from the available response

Request Example

curl -X POST "https://mobilexy.com/api/virtual-numbers/order" \
  -d "api_key=YOUR_API_KEY" \
  -d "offerToken=OFFER_TOKEN_HERE" \
  -d "number=542494401315" \
  -d "country=AR" \
  -d "type=local" \
  -d "setupPrice=0.00" \
  -d "monthlyPrice=8.33"

Response

{
    "remark": "virtual_number_ordered",
    "status": "success",
    "message": ["Virtual number ordered successfully"],
    "data": {
        "order": {
            "order_number": "ABCD12345678",
            "transaction_id": "VN-1-ABCD12345678",
            "number": "542494401315",
            "country": "AR",
            "status": "active",
            "retail_price": "8.33000000",
            "virtual_number": {
                "id": 15,
                "roamlinx_number_id": "rlx_number_id",
                "number": "542494401315",
                "status": "active"
            }
        }
    }
}

List Purchased Virtual Numbers

Retrieve purchased virtual numbers for the authenticated API user.

Endpoint: https://mobilexy.com/api/virtual-numbers/list

Method: GET

Request Parameters

Name	Required	Type	Description
api_key	Yes	string	Your API key
status	No	string	Filter by status, for example active, pending_activation, pending_termination, blocked_no_funds
per_page	No	integer	Pagination size

Request Example

curl "https://mobilexy.com/api/virtual-numbers/list?api_key=YOUR_API_KEY&status=active"

Virtual Number Details

Get details for one purchased virtual number. The identifier can be the local ID or the Roamlinx number ID.

Endpoint: https://mobilexy.com/api/virtual-numbers/{id}

Method: GET

Request Parameters

Name	Required	Type	Description
id	Yes	integer/string	Local virtual number ID or Roamlinx number ID in the URL
api_key	Yes	string	Your API key

Request Example

curl "https://mobilexy.com/api/virtual-numbers/15?api_key=YOUR_API_KEY"

Cancel Virtual Number

Cancel a virtual number. The number stays active until its expiration date when Roamlinx returns pending termination.

Endpoint: https://mobilexy.com/api/virtual-numbers/{id}/cancel

Method: POST

Request Parameters

Name	Required	Type	Description
id	Yes	integer/string	Local virtual number ID or Roamlinx number ID in the URL
api_key	Yes	string	Your API key

Request Example

curl -X POST "https://mobilexy.com/api/virtual-numbers/15/cancel" -d "api_key=YOUR_API_KEY"

Virtual Number SMS Messages

Retrieve inbound SMS messages received by a purchased virtual number.

Endpoint: https://mobilexy.com/api/virtual-numbers/{id}/sms

Method: GET

Request Parameters

Name	Required	Type	Description
id	Yes	integer/string	Local virtual number ID or Roamlinx number ID in the URL
api_key	Yes	string	Your API key
per_page	No	integer	Pagination size

Request Example

curl "https://mobilexy.com/api/virtual-numbers/15/sms?api_key=YOUR_API_KEY"

Virtual Number Charges

Retrieve SMS charge records for a purchased virtual number when SMS charge billing is enabled.

Endpoint: https://mobilexy.com/api/virtual-numbers/{id}/charges

Method: GET

Request Parameters

Name	Required	Type	Description
id	Yes	integer/string	Local virtual number ID or Roamlinx number ID in the URL
api_key	Yes	string	Your API key
per_page	No	integer	Pagination size

Request Example

curl "https://mobilexy.com/api/virtual-numbers/15/charges?api_key=YOUR_API_KEY"

Reactivate Blocked Virtual Number

Reactivate a locally blocked virtual number after the user balance is refilled. This does not restore a number that was already cancelled or terminated by Roamlinx.

Endpoint: https://mobilexy.com/api/virtual-numbers/{id}/reactivate

Method: POST

Request Parameters

Name	Required	Type	Description
id	Yes	integer/string	Local virtual number ID or Roamlinx number ID in the URL
api_key	Yes	string	Your API key

Request Example

curl -X POST "https://mobilexy.com/api/virtual-numbers/15/reactivate" -d "api_key=YOUR_API_KEY"