Skip to main content

API Documentation

Automate data vending, airtime VTU and more with a simple REST API. One secret key, one base URL.

Base URL

https://simhosting.ogdams.ng/api/v1

All endpoints below are relative to this base URL.

Authentication

Send your secret key as a Bearer token in the Authorization header:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx

Get your key from Dashboard → API Key →

Network IDs

ID Network
1MTNMTN
2AirtelAirtel
3GloGlo
4T2MobileT2Mobile (formerly 9mobile)

Network 4 is now branded T2Mobile (formerly 9mobile). The API may still return "9mobile" for this network.

Endpoints

Tap any endpoint to see its request parameters, a sample request and a sample response.

Method Endpoint Description
GET/get/balancesWallet & stock balances
GET/get/networks/idNetwork IDs
GET/get/data/plansData plans (v1 – v4)
POST/vend/dataVend data bundle
POST/vend/airtimeVend airtime
POST/sns/airtimeShare & sell airtime
POST/custom/ussd/codeRun a custom USSD code
POST/data/purchaseSmePlug-compatible data
POST/airtime/purchaseSmePlug-compatible airtime
POST/data (no /v1)Msorg-compatible data
POST/topup (no /v1)Msorg-compatible airtime

Wallet & Lookup

GET /get/balances

Fetch your wallet and stock balances.

No request body.

Request

curl -X GET \
  '{{ config('app.url') }}/api/v1/get/balances' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx'

Response

{
  "status": true,
  "code": 200,
  "data": {
    "msg": {
      "mainBalance": "25000.00",
      "vtuMtn": "0.00",
      "smeMtn": "0.00",
      "dgMtn": "0.00"
    },
    "ref": null
  }
}
GET /get/networks/id

Fetch the network IDs used across the API.

No request body.

Request

curl -X GET \
  '{{ config('app.url') }}/api/v1/get/networks/id' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx'

Response

{
  "status": true,
  "code": 200,
  "data": {
    "msg": { "1": "MTN", "2": "Airtel", "3": "Glo", "4": "9mobile" },
    "ref": null
  }
}
GET /get/data/plans

Fetch all available data plans with their planId, price and validity. Also available at /v2, /v3 and /v4 (different grouping / extra fields).

No request body.

Request

curl -X GET \
  '{{ config('app.url') }}/api/v1/get/data/plans' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx'

Response

{
  "status": true,
  "code": 200,
  "data": {
    "msg": [
      { "networkId": 1, "planId": 101, "name": "MTN SME 1GB", "price": "500.00", "validity": "30 Days" }
    ],
    "ref": null
  }
}

Vending

POST /vend/data

Vend a data bundle to a phone number.

Field Type Required Description
networkId integer Required 1, 2, 3 or 4
planId integer Required Plan ID from /get/data/plans
phoneNumber string Required Recipient phone number
reference string Optional Your unique reference (max 40 chars)

Request

curl -X POST \
  '{{ config('app.url') }}/api/v1/vend/data' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"networkId": 1, "planId": 101, "phoneNumber": "08012345678", "reference": "ref-12345"}'

Response

{
  "status": true,
  "code": 202,
  "data": {
    "msg": "Transaction recorded. Expect response in 5 secs",
    "ref": "SX8K2J4NQ9"
  }
}
POST /vend/airtime

Vend airtime (VTU, MoMo, SNS or Awoof4u) to a phone number.

Field Type Required Description
networkId integer Required 1, 2, 3 or 4
amount integer Required Amount in Naira (minimum 50)
phoneNumber string Required Recipient phone number
type string Optional vtu, momo, sns or awuf4u (default: vtu)
reference string Optional Your unique reference (max 40 chars)

Request

curl -X POST \
  '{{ config('app.url') }}/api/v1/vend/airtime' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"networkId": 1, "amount": 500, "phoneNumber": "08012345678", "type": "vtu", "reference": "ref-12345"}'

Response

{
  "status": true,
  "code": 202,
  "data": {
    "msg": "Transaction recorded. Expect response in 5 secs",
    "ref": "SX8K2J4NQ9"
  }
}
POST /sns/airtime

Share & sell (SNS) airtime on MTN, Airtel or Glo.

Field Type Required Description
networkId integer Required 1 (MTN), 2 (Airtel) or 3 (Glo)
amount integer Required Amount in Naira
phoneNumber string Required Recipient phone number
nTimes integer Optional Repeat count (default: 1)

Request

curl -X POST \
  '{{ config('app.url') }}/api/v1/sns/airtime' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"networkId": 1, "amount": 500, "phoneNumber": "08012345678"}'

Response

{
  "status": true,
  "code": 200,
  "data": {
    "msg": "Transaction recorded. Expect response in 5 secs",
    "ref": null
  }
}
POST /custom/ussd/code

Run a custom USSD code on your SIM.

Field Type Required Description
networkId integer Required 1, 2, 3 or 4
ussd string Required USSD code (must start with * and end with #)
reference string Optional Your unique reference (max 40 chars)

Request

curl -X POST \
  '{{ config('app.url') }}/api/v1/custom/ussd/code' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"networkId": 1, "ussd": "*131*08012345678#", "reference": "ref-12345"}'

Response

{
  "status": true,
  "code": 202,
  "data": {
    "msg": "Transaction recorded. Expect response in 5 secs",
    "ref": "SX8K2J4NQ9"
  }
}

SmePlug-Compatible Endpoints

POST /data/purchase

SmePlug-style data purchase (mounted at /api/v1/data/purchase). Drop-in for SmePlug clients.

Field Type Required Description
network_id integer Required SmePlug network ID
plan_id integer Required Plan ID
phone string Required Recipient phone number
customer_reference string Optional Your reference

Request

curl -X POST \
  '{{ config('app.url') }}/api/v1/data/purchase' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"network_id": 1, "plan_id": 101, "phone": "08012345678", "customer_reference": "ref-12345"}'

Response

{
  "status": true,
  "data": {
    "reference": "SX8K2J4NQ9",
    "msg": "Transaction recorded. Expect response in 5 secs"
  }
}
POST /airtime/purchase

SmePlug-style airtime purchase (mounted at /api/v1/airtime/purchase).

Field Type Required Description
network_id integer Required SmePlug network ID
amount integer Required Amount in Naira
phone string Required Recipient phone number
customer_reference string Optional Your reference

Request

curl -X POST \
  '{{ config('app.url') }}/api/v1/airtime/purchase' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"network_id": 1, "amount": 500, "phone": "08012345678", "customer_reference": "ref-12345"}'

Response

{
  "status": true,
  "data": {
    "reference": "SX8K2J4NQ9",
    "msg": "Transaction recorded. Expect response in 5 secs"
  }
}

Msorg-Compatible Endpoints

POST /data

Msorg-style data purchase (mounted at /api/data, outside /v1). Drop-in for Msorg clients.

Field Type Required Description
network integer Required Msorg network ID
plan integer Required Plan ID
mobile_number string Required Recipient phone number

Header may use "Token sk_live_..." — the platform accepts it.

Request

curl -X POST \
  '{{ config('app.url') }}/api/data' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"network": 1, "plan": 101, "mobile_number": "08012345678"}'

Response

{
  "ident": "SX8K2J4NQ9",
  "network": 1,
  "mobile_number": "08012345678",
  "Status": "successful",
  "api_response": "Transaction recorded. Expect response in 5 secs",
  "plan_network": "MTN",
  "create_date": "2026-08-16T12:00:00.000000"
}
POST /topup

Msorg-style airtime purchase (mounted at /api/topup).

Field Type Required Description
network integer Required Msorg network ID
amount integer Required Amount in Naira
mobile_number string Required Recipient phone number
airtime_type string Optional e.g. vtu

Header may use "Token sk_live_..." — the platform accepts it.

Request

curl -X POST \
  '{{ config('app.url') }}/api/topup' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"network": 1, "amount": 500, "mobile_number": "08012345678"}'

Response

{
  "ident": "SX8K2J4NQ9",
  "network": 1,
  "mobile_number": "08012345678",
  "plan": 101,
  "Status": "successful",
  "api_response": "Transaction recorded. Expect response in 5 secs",
  "plan_network": "MTN",
  "create_date": "2026-08-16T12:00:00.000000"
}

Response Format & Codes

Native endpoints return a consistent envelope: {"status": true|false, "code": <int>, "data": {"msg": "…", "ref": "…"}}

Code Meaning
200Successful
201Queued — received by the platform
202Processing — in progress
424Failed — provider returned an error
401Invalid or missing API key
404Transaction not found

Msorg-compatible endpoints (/api/data & /api/topup) return a different flat shape (see their examples).

Webhooks (Optional)

Get notified when a transaction succeeds or fails. Set your webhook URL in your Dashboard → Webhook URL →

Events are sent as POST requests with an ogdams-simhosting-signature header — an HMAC-SHA512 hash of the raw request body signed with your secret key.

Related Resources

Free API Integration SIM Hosting Guide View Pricing