{
  "openapi": "3.0.3",
  "info": {
    "title": "Uzobestgsm API",
    "version": "2026-11-12",
    "description": "Buy data, airtime, cable TV, electricity, exam pins, recharge pins, internet and bulk SMS from your own website or app. Every request carries the header Authorization: Token <your API key>. VTU websites that connect with a website address and an API key: enter ours, nothing else is needed."
  },
  "servers": [
    {
      "url": "https://uzobestgsm.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "Token": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "The word Token, a space, then your API key: Token 1a2b3c..."
      }
    }
  },
  "security": [
    {
      "Token": []
    }
  ],
  "tags": [
    {
      "name": "Account"
    },
    {
      "name": "Data"
    },
    {
      "name": "Airtime"
    },
    {
      "name": "Cable TV"
    },
    {
      "name": "Electricity"
    },
    {
      "name": "Exam pins"
    },
    {
      "name": "Recharge pins"
    },
    {
      "name": "Internet"
    },
    {
      "name": "Bulk SMS"
    }
  ],
  "paths": {
    "/api/user/": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "Your balance (user.Account_Balance)",
        "operationId": "balance",
        "responses": {
          "200": {
            "description": "Account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "user": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer",
                          "example": 1001
                        },
                        "username": {
                          "type": "string",
                          "example": "adastores"
                        },
                        "email": {
                          "type": "string",
                          "example": "ada@example.com"
                        },
                        "user_type": {
                          "type": "string",
                          "example": "API"
                        },
                        "Account_Balance": {
                          "type": "number",
                          "example": 25400.5
                        },
                        "wallet_balance": {
                          "type": "string",
                          "example": "25401"
                        },
                        "has_pin": {
                          "type": "boolean",
                          "example": true
                        }
                      }
                    },
                    "notification": {
                      "type": "object",
                      "properties": {
                        "message": {
                          "type": "string",
                          "example": ""
                        }
                      }
                    },
                    "Dataplans": {
                      "type": "object",
                      "properties": {
                        "MTN_PLAN": {
                          "type": "object",
                          "properties": {
                            "ALL": {
                              "type": "array",
                              "items": {
                                "type": "string",
                                "example": "..."
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/plans/": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "Plan IDs and your prices",
        "operationId": "plans",
        "description": "Everything you can buy now with YOUR price; send \"id\" or \"named_id\" as the field in \"send_as\". Refreshed every minute.",
        "parameters": [
          {
            "name": "product",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "data, airtime, cable, electricity, exam, recharge, internet or networks (empty = everything)"
          },
          {
            "name": "network",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional: a network or company, e.g. MTN or DStv"
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional, data only: e.g. SME, GIFTING"
          }
        ],
        "responses": {
          "200": {
            "description": "The list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer",
                      "example": 1
                    },
                    "plans": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "product": {
                            "type": "string",
                            "example": "data"
                          },
                          "network": {
                            "type": "string",
                            "example": "MTN"
                          },
                          "type": {
                            "type": "string",
                            "example": "SME"
                          },
                          "name": {
                            "type": "string",
                            "example": "1GB"
                          },
                          "detail": {
                            "type": "string",
                            "example": "30 Days"
                          },
                          "price": {
                            "type": "number",
                            "example": 280.0
                          },
                          "id": {
                            "type": "string",
                            "example": "7"
                          },
                          "named_id": {
                            "type": "string",
                            "example": "MTN_SME_1GB_30DAYS"
                          },
                          "send_as": {
                            "type": "string",
                            "example": "plan"
                          },
                          "off": {
                            "type": "boolean",
                            "example": false
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Refused, nothing charged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Wrong or missing API key"
          }
        }
      }
    },
    "/api/data/": {
      "post": {
        "tags": [
          "Data"
        ],
        "summary": "Buy data",
        "operationId": "buy_data",
        "description": "Buy a data plan for a phone number. Choose the plan ID from the Data plans list below.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "network",
                  "mobile_number",
                  "plan"
                ],
                "properties": {
                  "network": {
                    "type": "integer",
                    "description": "Network ID (Networks list).",
                    "example": 1
                  },
                  "mobile_number": {
                    "type": "string",
                    "description": "11 digits, e.g. 08031234567.",
                    "example": "08031234567"
                  },
                  "plan": {
                    "type": "integer or string",
                    "description": "Plan ID (Data plans list): the number (e.g. 7) or the named plan ID (e.g. MTN_SME_1GB_30DAYS). Both work; use either.",
                    "example": 7
                  },
                  "Ported_number": {
                    "type": "boolean",
                    "description": "true if the number moved from another network. Default false (we check that the number belongs to the network).",
                    "example": true
                  },
                  "customer_ref": {
                    "type": "string",
                    "description": "Your own unique reference. Sending the same one again returns the first order instead of buying again.",
                    "example": "MYREF0001"
                  }
                }
              },
              "example": {
                "network": 1,
                "mobile_number": "08031234567",
                "plan": 7,
                "Ported_number": true,
                "customer_ref": "MYREF0001"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Order placed (read Status)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer",
                      "example": 21067883
                    },
                    "ident": {
                      "type": "string",
                      "example": "Data8935fa7f7-2a0"
                    },
                    "customer_ref": {
                      "type": "string",
                      "example": "MYREF0001"
                    },
                    "network": {
                      "type": "integer",
                      "example": 1
                    },
                    "mobile_number": {
                      "type": "string",
                      "example": "08031234567"
                    },
                    "plan": {
                      "type": "integer",
                      "example": 7
                    },
                    "plan_code": {
                      "type": "string",
                      "example": "MTN_SME_1GB_30DAYS"
                    },
                    "plan_name": {
                      "type": "string",
                      "example": "1.0GB"
                    },
                    "plan_network": {
                      "type": "string",
                      "example": "MTN"
                    },
                    "plan_type": {
                      "type": "string",
                      "example": "SME"
                    },
                    "duration": {
                      "type": "string",
                      "example": "30 days"
                    },
                    "data_type": {
                      "type": "string",
                      "example": "SME"
                    },
                    "plan_amount": {
                      "type": "string",
                      "example": "280.0"
                    },
                    "balance_before": {
                      "type": "string",
                      "example": "5000.0"
                    },
                    "balance_after": {
                      "type": "string",
                      "example": "4720.0"
                    },
                    "Status": {
                      "type": "string",
                      "example": "successful"
                    },
                    "api_response": {
                      "type": "string",
                      "example": "Dear Customer, You have successfully shared 1GB Data to 2348031234567."
                    },
                    "create_date": {
                      "type": "string",
                      "example": "2026-11-03T10:15:02.123456+01:00"
                    },
                    "Ported_number": {
                      "type": "boolean",
                      "example": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Refused, nothing charged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Wrong or missing API key"
          },
          "429": {
            "description": "Too many requests (Retry-After)"
          }
        }
      },
      "get": {
        "tags": [
          "Data"
        ],
        "summary": "Check data orders",
        "operationId": "check_data",
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Exact ident, customer_ref, order id or number. Without it: your newest orders, 15 a page (?page=2 ...)."
          }
        ],
        "responses": {
          "200": {
            "description": "A list (with search) or a page {count, next, previous, results}"
          }
        }
      }
    },
    "/api/topup/": {
      "post": {
        "tags": [
          "Airtime"
        ],
        "summary": "Buy airtime",
        "operationId": "buy_airtime",
        "description": "Send airtime to a phone number. You pay the percent of the amount shown in the Airtime list (e.g. pay 98% means \u20a698 for \u20a6100 airtime).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "network",
                  "amount",
                  "mobile_number",
                  "airtime_type"
                ],
                "properties": {
                  "network": {
                    "type": "integer",
                    "description": "Network ID (Networks list).",
                    "example": 1
                  },
                  "amount": {
                    "type": "number",
                    "description": "Airtime value in naira, 50 or more.",
                    "example": 100
                  },
                  "mobile_number": {
                    "type": "string",
                    "description": "11 digits, e.g. 08031234567.",
                    "example": "08031234567"
                  },
                  "airtime_type": {
                    "type": "string",
                    "description": "VTU (also \"awuf4U\" or \"Share and Sell\" where the Airtime list shows them).",
                    "example": "VTU"
                  },
                  "Ported_number": {
                    "type": "boolean",
                    "description": "true if the number moved from another network. Default false.",
                    "example": true
                  }
                }
              },
              "example": {
                "network": 1,
                "amount": 100,
                "mobile_number": "08031234567",
                "airtime_type": "VTU",
                "Ported_number": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Order placed (read Status)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer",
                      "example": 3520011
                    },
                    "ident": {
                      "type": "string",
                      "example": "Airtime0e1f2a3b4c5"
                    },
                    "network": {
                      "type": "integer",
                      "example": 1
                    },
                    "mobile_number": {
                      "type": "string",
                      "example": "08031234567"
                    },
                    "airtime_type": {
                      "type": "string",
                      "example": "VTU"
                    },
                    "amount": {
                      "type": "string",
                      "example": "100"
                    },
                    "paid_amount": {
                      "type": "string",
                      "example": "98.0"
                    },
                    "plan_amount": {
                      "type": "string",
                      "example": "98.0"
                    },
                    "plan_network": {
                      "type": "string",
                      "example": "MTN"
                    },
                    "balance_before": {
                      "type": "string",
                      "example": "5000.0"
                    },
                    "balance_after": {
                      "type": "string",
                      "example": "4902.0"
                    },
                    "Status": {
                      "type": "string",
                      "example": "successful"
                    },
                    "create_date": {
                      "type": "string",
                      "example": "2026-11-03T10:16:40.000000+01:00"
                    },
                    "Ported_number": {
                      "type": "boolean",
                      "example": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Refused, nothing charged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Wrong or missing API key"
          },
          "429": {
            "description": "Too many requests (Retry-After)"
          }
        }
      },
      "get": {
        "tags": [
          "Airtime"
        ],
        "summary": "Check airtime orders",
        "operationId": "check_airtime",
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Exact ident, customer_ref, order id or number. Without it: your newest orders, 15 a page (?page=2 ...)."
          }
        ],
        "responses": {
          "200": {
            "description": "A list (with search) or a page {count, next, previous, results}"
          }
        }
      }
    },
    "/api/cablesub/": {
      "post": {
        "tags": [
          "Cable TV"
        ],
        "summary": "Buy cable tv",
        "operationId": "buy_cable",
        "description": "Pay a DStv, GOtv or StarTimes package. Check the smartcard first to see the owner's name.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "cablename",
                  "cableplan",
                  "smart_card_number"
                ],
                "properties": {
                  "cablename": {
                    "type": "integer",
                    "description": "Cable company ID (Cable list).",
                    "example": 1
                  },
                  "cableplan": {
                    "type": "integer",
                    "description": "Package ID (Cable list).",
                    "example": 12
                  },
                  "smart_card_number": {
                    "type": "string",
                    "description": "Smartcard / IUC number (digits).",
                    "example": "7012345678"
                  }
                }
              },
              "example": {
                "cablename": 1,
                "cableplan": 12,
                "smart_card_number": "7012345678"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Order placed (read Status)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer",
                      "example": 99120
                    },
                    "ident": {
                      "type": "string",
                      "example": "Cable1a2b3c4d5e6"
                    },
                    "cablename": {
                      "type": "integer",
                      "example": 1
                    },
                    "cableplan": {
                      "type": "integer",
                      "example": 12
                    },
                    "package": {
                      "type": "string",
                      "example": "DStv Compact"
                    },
                    "plan_amount": {
                      "type": "string",
                      "example": "19000"
                    },
                    "paid_amount": {
                      "type": "string",
                      "example": "19000.0"
                    },
                    "balance_before": {
                      "type": "string",
                      "example": "50000.0"
                    },
                    "balance_after": {
                      "type": "string",
                      "example": "31000.0"
                    },
                    "smart_card_number": {
                      "type": "string",
                      "example": "7012345678"
                    },
                    "customer_name": {
                      "type": "string",
                      "example": "ADA OKAFOR"
                    },
                    "Status": {
                      "type": "string",
                      "example": "successful"
                    },
                    "api_response": {
                      "type": "string",
                      "example": "Your order was successful."
                    },
                    "create_date": {
                      "type": "string",
                      "example": "2026-11-03T10:20:00.000000+01:00"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Refused, nothing charged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Wrong or missing API key"
          },
          "429": {
            "description": "Too many requests (Retry-After)"
          }
        }
      },
      "get": {
        "tags": [
          "Cable TV"
        ],
        "summary": "Check cable tv orders",
        "operationId": "check_cable",
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Exact ident, customer_ref, order id or number. Without it: your newest orders, 15 a page (?page=2 ...)."
          }
        ],
        "responses": {
          "200": {
            "description": "A list (with search) or a page {count, next, previous, results}"
          }
        }
      }
    },
    "/api/validateiuc/": {
      "get": {
        "tags": [
          "Cable TV"
        ],
        "summary": "Check the smartcard before buying",
        "operationId": "lookup_cable",
        "parameters": [
          {
            "name": "smart_card_number",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Smartcard / IUC number."
          },
          {
            "name": "cablename",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Cable company name, e.g. GOTV, DSTV or STARTIME (its ID from the Cable list also works)."
          }
        ],
        "responses": {
          "200": {
            "description": "invalid: false = found; name = the owner",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "invalid": {
                      "type": "boolean",
                      "example": false
                    },
                    "name": {
                      "type": "string",
                      "example": "ADA OKAFOR"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/billpayment/": {
      "post": {
        "tags": [
          "Electricity"
        ],
        "summary": "Buy electricity",
        "operationId": "buy_electricity",
        "description": "Buy a prepaid token or pay a postpaid bill. Check the meter first to see the owner's name. The token is in the reply (\"token\") when the order is successful.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "disco_name",
                  "amount",
                  "meter_number",
                  "MeterType",
                  "Customer_Phone"
                ],
                "properties": {
                  "disco_name": {
                    "type": "integer",
                    "description": "Electricity company ID (Electricity list).",
                    "example": 3
                  },
                  "amount": {
                    "type": "number",
                    "description": "Amount in naira (the Electricity list shows the minimum).",
                    "example": 2000
                  },
                  "meter_number": {
                    "type": "string",
                    "description": "Meter number (digits).",
                    "example": "45012345678"
                  },
                  "MeterType": {
                    "type": "string",
                    "description": "Prepaid or Postpaid (1 or 2 also work).",
                    "example": "Prepaid"
                  },
                  "Customer_Phone": {
                    "type": "string",
                    "description": "The customer's phone number, 11 digits.",
                    "example": "08031234567"
                  }
                }
              },
              "example": {
                "disco_name": 3,
                "amount": 2000,
                "meter_number": "45012345678",
                "MeterType": "Prepaid",
                "Customer_Phone": "08031234567"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Order placed (read Status)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer",
                      "example": 41200
                    },
                    "ident": {
                      "type": "string",
                      "example": "Bill9f8e7d6c5b4a"
                    },
                    "disco_name": {
                      "type": "integer",
                      "example": 3
                    },
                    "package": {
                      "type": "string",
                      "example": "Ikeja Electric"
                    },
                    "amount": {
                      "type": "string",
                      "example": "2000"
                    },
                    "paid_amount": {
                      "type": "string",
                      "example": "2000.0"
                    },
                    "meter_number": {
                      "type": "string",
                      "example": "45012345678"
                    },
                    "MeterType": {
                      "type": "string",
                      "example": "Prepaid"
                    },
                    "Customer_Phone": {
                      "type": "string",
                      "example": "08031234567"
                    },
                    "token": {
                      "type": "string",
                      "example": "1234-5678-9012-3456-7890"
                    },
                    "units": {
                      "type": "string",
                      "example": "28.5"
                    },
                    "customer_name": {
                      "type": "string",
                      "example": "ADA OKAFOR"
                    },
                    "customer_address": {
                      "type": "string",
                      "example": "12 MARKET ROAD"
                    },
                    "balance_before": {
                      "type": "string",
                      "example": "50000.0"
                    },
                    "balance_after": {
                      "type": "string",
                      "example": "48000.0"
                    },
                    "Status": {
                      "type": "string",
                      "example": "successful"
                    },
                    "api_response": {
                      "type": "string",
                      "example": "Token: 1234-5678-9012-3456-7890"
                    },
                    "create_date": {
                      "type": "string",
                      "example": "2026-11-03T10:25:00.000000+01:00"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Refused, nothing charged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Wrong or missing API key"
          },
          "429": {
            "description": "Too many requests (Retry-After)"
          }
        }
      },
      "get": {
        "tags": [
          "Electricity"
        ],
        "summary": "Check electricity orders",
        "operationId": "check_electricity",
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Exact ident, customer_ref, order id or number. Without it: your newest orders, 15 a page (?page=2 ...)."
          }
        ],
        "responses": {
          "200": {
            "description": "A list (with search) or a page {count, next, previous, results}"
          }
        }
      }
    },
    "/api/validatemeter/": {
      "get": {
        "tags": [
          "Electricity"
        ],
        "summary": "Check the meter before buying",
        "operationId": "lookup_electricity",
        "parameters": [
          {
            "name": "meternumber",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Meter number."
          },
          {
            "name": "disconame",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Electricity company ID or name (Electricity list)."
          },
          {
            "name": "mtype",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Prepaid or Postpaid (1 or 2 also work)."
          }
        ],
        "responses": {
          "200": {
            "description": "invalid: false = found; name = the owner",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "invalid": {
                      "type": "boolean",
                      "example": false
                    },
                    "name": {
                      "type": "string",
                      "example": "ADA OKAFOR"
                    },
                    "address": {
                      "type": "string",
                      "example": "12 MARKET ROAD, ENUGU"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/epin/": {
      "post": {
        "tags": [
          "Exam pins"
        ],
        "summary": "Buy exam pins",
        "operationId": "buy_exam",
        "description": "Buy WAEC, NECO or NABTEB result checker pins. The pins are in the reply (\"pins\") when the order is successful.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "exam_name",
                  "quantity"
                ],
                "properties": {
                  "exam_name": {
                    "type": "string",
                    "description": "WAEC, NECO or NABTEB (Exam list).",
                    "example": "WAEC"
                  },
                  "quantity": {
                    "type": "integer",
                    "description": "How many pins (the Exam list shows the most per order).",
                    "example": 1
                  }
                }
              },
              "example": {
                "exam_name": "WAEC",
                "quantity": 1
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Order placed (read Status)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer",
                      "example": 8801
                    },
                    "exam_name": {
                      "type": "string",
                      "example": "WAEC"
                    },
                    "quantity": {
                      "type": "integer",
                      "example": 1
                    },
                    "pins": {
                      "type": "string",
                      "example": "Serial No:WRN123456789 Pin:123456789012"
                    },
                    "amount": {
                      "type": "number",
                      "example": 3400.0
                    },
                    "previous_balance": {
                      "type": "string",
                      "example": "5000.0"
                    },
                    "after_balance": {
                      "type": "string",
                      "example": "1600.0"
                    },
                    "Status": {
                      "type": "string",
                      "example": "successful"
                    },
                    "create_date": {
                      "type": "string",
                      "example": "2026-11-03T10:30:00.000000+01:00"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Refused, nothing charged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Wrong or missing API key"
          },
          "429": {
            "description": "Too many requests (Retry-After)"
          }
        }
      },
      "get": {
        "tags": [
          "Exam pins"
        ],
        "summary": "Check exam pins orders",
        "operationId": "check_exam",
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Exact ident, customer_ref, order id or number. Without it: your newest orders, 15 a page (?page=2 ...)."
          }
        ],
        "responses": {
          "200": {
            "description": "A list (with search) or a page {count, next, previous, results}"
          }
        }
      }
    },
    "/api/rechargepin/": {
      "post": {
        "tags": [
          "Recharge pins"
        ],
        "summary": "Buy recharge pins",
        "operationId": "buy_recharge",
        "description": "Buy printable recharge card pins. Choose the card ID from the Recharge pins list (it shows the cards left).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "network",
                  "network_amount",
                  "quantity",
                  "name_on_card"
                ],
                "properties": {
                  "network": {
                    "type": "integer",
                    "description": "Network ID (Recharge pins list).",
                    "example": 1
                  },
                  "network_amount": {
                    "type": "integer",
                    "description": "Card ID (Recharge pins list), not the naira value.",
                    "example": 4
                  },
                  "quantity": {
                    "type": "integer",
                    "description": "How many cards (the Recharge pins list shows the most per order).",
                    "example": 2
                  },
                  "name_on_card": {
                    "type": "string",
                    "description": "Your business name, printed on the cards.",
                    "example": "ADA STORES"
                  }
                }
              },
              "example": {
                "network": 1,
                "network_amount": 4,
                "quantity": 2,
                "name_on_card": "ADA STORES"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Order placed (read Status)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer",
                      "example": 5120
                    },
                    "network": {
                      "type": "integer",
                      "example": 1
                    },
                    "network_name": {
                      "type": "string",
                      "example": "MTN"
                    },
                    "network_amount": {
                      "type": "integer",
                      "example": 4
                    },
                    "card_amount": {
                      "type": "string",
                      "example": "100"
                    },
                    "quantity": {
                      "type": "integer",
                      "example": 2
                    },
                    "name_on_card": {
                      "type": "string",
                      "example": "ADA STORES"
                    },
                    "data_pin": {
                      "type": "string",
                      "example": "[...the pins...]"
                    },
                    "amount": {
                      "type": "number",
                      "example": 196.0
                    },
                    "previous_balance": {
                      "type": "string",
                      "example": "5000.0"
                    },
                    "after_balance": {
                      "type": "string",
                      "example": "4804.0"
                    },
                    "Status": {
                      "type": "string",
                      "example": "successful"
                    },
                    "create_date": {
                      "type": "string",
                      "example": "2026-11-03T10:35:00.000000+01:00"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Refused, nothing charged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Wrong or missing API key"
          },
          "429": {
            "description": "Too many requests (Retry-After)"
          }
        }
      },
      "get": {
        "tags": [
          "Recharge pins"
        ],
        "summary": "Check recharge pins orders",
        "operationId": "check_recharge",
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Exact ident, customer_ref, order id or number. Without it: your newest orders, 15 a page (?page=2 ...)."
          }
        ],
        "responses": {
          "200": {
            "description": "A list (with search) or a page {count, next, previous, results}"
          }
        }
      }
    },
    "/api/internet/": {
      "post": {
        "tags": [
          "Internet"
        ],
        "summary": "Buy internet",
        "operationId": "buy_internet",
        "description": "Renew an internet plan (MTN Fibre X, Smile and others in the Internet list). Check the account first to see the owner's name, then buy with the account number or the phone number the company asks for.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "plan",
                  "smart_number"
                ],
                "properties": {
                  "plan": {
                    "type": "integer",
                    "description": "Internet plan ID (Internet list).",
                    "example": 15
                  },
                  "smart_number": {
                    "type": "string",
                    "description": "The account number (or phone number, where the Internet list says so).",
                    "example": "1402000123"
                  },
                  "customer_name": {
                    "type": "string",
                    "description": "Optional, for your own records."
                  }
                }
              },
              "example": {
                "plan": 15,
                "smart_number": "1402000123"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Order placed (read Status)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer",
                      "example": 701
                    },
                    "ident": {
                      "type": "string",
                      "example": "Net5d4c3b2a1f0e"
                    },
                    "Status": {
                      "type": "string",
                      "example": "successful"
                    },
                    "api_response": {
                      "type": "string",
                      "example": "Your internet plan is active."
                    },
                    "pins": {
                      "type": "string",
                      "example": ""
                    },
                    "plan": {
                      "type": "string",
                      "example": "Smile 10GB 30 days"
                    },
                    "smart_number": {
                      "type": "string",
                      "example": "1402000123"
                    },
                    "paid_amount": {
                      "type": "number",
                      "example": 4950.0
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Refused, nothing charged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Wrong or missing API key"
          },
          "429": {
            "description": "Too many requests (Retry-After)"
          }
        }
      },
      "get": {
        "tags": [
          "Internet"
        ],
        "summary": "Check internet orders",
        "operationId": "check_internet",
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Exact ident, customer_ref, order id or number. Without it: your newest orders, 15 a page (?page=2 ...)."
          }
        ],
        "responses": {
          "200": {
            "description": "A list (with search) or a page {count, next, previous, results}"
          }
        }
      }
    },
    "/api/validateinternet/": {
      "get": {
        "tags": [
          "Internet"
        ],
        "summary": "Check the account before buying",
        "operationId": "lookup_internet",
        "parameters": [
          {
            "name": "provider",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Internet company ID or name from the Internet list, e.g. MTN Fibre X or Smile. Send this or plan."
          },
          {
            "name": "plan",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Or the internet plan ID (or named ID) you are about to buy; the company is taken from it."
          },
          {
            "name": "number",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The account number (a Smile customer's email also works)."
          }
        ],
        "responses": {
          "200": {
            "description": "invalid: false = found; name = the owner",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "invalid": {
                      "type": "boolean",
                      "example": false
                    },
                    "name": {
                      "type": "string",
                      "example": "ADA OKAFOR"
                    },
                    "account": {
                      "type": "string",
                      "example": "1402000123"
                    },
                    "error": {
                      "type": "string",
                      "example": ""
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/sendsms/": {
      "post": {
        "tags": [
          "Bulk SMS"
        ],
        "summary": "Buy bulk sms",
        "operationId": "buy_sms",
        "description": "Send one text message to many numbers. The price is per number, per page of 160 characters.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "sender",
                  "recipient",
                  "message"
                ],
                "properties": {
                  "sender": {
                    "type": "string",
                    "description": "Sender name shown on the phones: up to 11 letters and numbers (or up to 16 digits).",
                    "example": "ADASTORES"
                  },
                  "recipient": {
                    "type": "string",
                    "description": "Phone numbers separated by commas, e.g. 08031234567,08051234567.",
                    "example": "08031234567,08051234567"
                  },
                  "message": {
                    "type": "string",
                    "description": "The text. No emojis.",
                    "example": "Our shop opens at 8am tomorrow."
                  }
                }
              },
              "example": {
                "sender": "ADASTORES",
                "recipient": "08031234567,08051234567",
                "message": "Our shop opens at 8am tomorrow."
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Order placed (read Status)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer",
                      "example": 9910
                    },
                    "ident": {
                      "type": "string",
                      "example": "Sms0a1b2c3d4e5f"
                    },
                    "Status": {
                      "type": "string",
                      "example": "processing"
                    },
                    "message": {
                      "type": "string",
                      "example": "Your message is being sent."
                    },
                    "error": {
                      "type": "string",
                      "example": "Your message is being sent."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Refused, nothing charged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Wrong or missing API key"
          },
          "429": {
            "description": "Too many requests (Retry-After)"
          }
        }
      },
      "get": {
        "tags": [
          "Bulk SMS"
        ],
        "summary": "Check bulk sms orders",
        "operationId": "check_sms",
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Exact ident, customer_ref, order id or number. Without it: your newest orders, 15 a page (?page=2 ...)."
          }
        ],
        "responses": {
          "200": {
            "description": "A list (with search) or a page {count, next, previous, results}"
          }
        }
      }
    }
  },
  "x-webhook": {
    "method": "POST",
    "body": {
      "product": "data",
      "id": 21067883,
      "ident": "Data8935fa7f7-2a0",
      "customer_ref": "MYREF0001",
      "Status": "successful",
      "transaction_status": "successful",
      "network": "MTN",
      "mobile_number": "08031234567",
      "plan": 7,
      "purchased_plan": "1.0GB",
      "data_type": "SME",
      "plan_amount": "280.0",
      "previous_balance": "5000.0",
      "after_balance": "4720.0",
      "api_response": "Dear Customer, You have successfully shared 1GB Data to 2348031234567.",
      "transaction_date": "03, Nov 2026",
      "create_date": "2026-11-03T10:15:02.123456+01:00"
    },
    "signature_header": "X-Uzobest-Signature",
    "signature": "HMAC-SHA512 of the raw body, key = your API key, hex"
  }
}