{"openapi":"3.1.0","info":{"title":"Flexy API","version":"3.0.0","description":"Mobile and Idoom internet top-ups for Algeria. Authenticate with the X-Access-Token header."},"servers":[{"url":"https://api.flexyliktelecom.com","description":"API"}],"tags":[{"name":"Core","description":"Health and key validation"},{"name":"Account","description":"Balance and transactions"},{"name":"Mobile top-up","description":"Mobilis, Djezzy and Ooredoo credit, bills and offers"},{"name":"Internet top-up","description":"Idoom ADSL and 4G LTE cards"}],"components":{"securitySchemes":{"AccessToken":{"type":"apiKey","in":"header","name":"X-Access-Token","description":"Your API key. Sandbox keys start with flx_test_, production keys with flx_live_."}},"schemas":{"PingResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/PingData"},"meta":{"$ref":"#/components/schemas/Meta"},"requestId":{"type":"string","example":"req_8fK2mQx7Lp0aZ3nV1cWb","examples":["req_8fK2mQx7Lp0aZ3nV1cWb"]}},"required":["success","data","meta","requestId"]},"PingData":{"type":"object","properties":{"api":{"type":"string","enum":["ok","error"]},"operators":{"type":"object","properties":{"mobilis":{"type":"string","enum":["up","down"]},"djezzy":{"type":"string","enum":["up","down"]},"ooredoo":{"type":"string","enum":["up","down"]}},"required":["mobilis","djezzy","ooredoo"]},"internet":{"type":"object","properties":{"ADSL":{"type":"string","enum":["up","down"]},"4G":{"type":"string","enum":["up","down"]}},"required":["ADSL","4G"]}},"required":["api","operators","internet"]},"Meta":{"type":"object","properties":{"timestamp":{"type":"string","example":"2026-11-15T10:30:00.000Z","examples":["2026-11-15T10:30:00.000Z"]}},"required":["timestamp"]},"Error":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string","example":"ERR_VALIDATION","examples":["ERR_VALIDATION"]},"message":{"type":"string","example":"amount must be a whole number between 100 and 50000 for PREPAID_DJEZZY","examples":["amount must be a whole number between 100 and 50000 for PREPAID_DJEZZY"]},"details":{}},"required":["code","message"]},"requestId":{"type":"string","example":"req_8fK2mQx7Lp0aZ3nV1cWb","examples":["req_8fK2mQx7Lp0aZ3nV1cWb"]}},"required":["success","error","requestId"]},"ValidateResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/ValidateData"},"meta":{"$ref":"#/components/schemas/Meta"},"requestId":{"type":"string","example":"req_8fK2mQx7Lp0aZ3nV1cWb","examples":["req_8fK2mQx7Lp0aZ3nV1cWb"]}},"required":["success","data","meta","requestId"]},"ValidateData":{"type":"object","properties":{"username":{"type":"string","example":"my-shop","examples":["my-shop"]},"apiKey":{"type":"object","properties":{"keyId":{"type":"string","example":"key_3f9a1c2b7d4e5f6a7b","examples":["key_3f9a1c2b7d4e5f6a7b"]},"name":{"type":"string","example":"Production server","examples":["Production server"]},"key":{"type":"string","description":"Masked key.","example":"flx_live_Ab3d••••••••w9Qz","examples":["flx_live_Ab3d••••••••w9Qz"]},"isEnabled":{"type":"boolean"},"type":{"type":"string","enum":["SANDBOX","PRODUCTION"]},"scope":{"type":"string","enum":["READ-WRITE","READ-ONLY"]},"allowedips":{"type":"array","items":{"type":"string"},"description":"Allowed IPs. Empty means all IPs are allowed.","example":[]}},"required":["keyId","name","key","isEnabled","type","scope","allowedips"]}},"required":["username","apiKey"]},"BalanceResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/BalanceData"},"meta":{"$ref":"#/components/schemas/Meta"},"requestId":{"type":"string","example":"req_8fK2mQx7Lp0aZ3nV1cWb","examples":["req_8fK2mQx7Lp0aZ3nV1cWb"]}},"required":["success","data","meta","requestId"]},"BalanceData":{"type":"object","properties":{"balance":{"type":"number","description":"Available balance in DZD.","example":15230.5,"examples":[15230.5]},"currency":{"type":"string","enum":["DZD"]}},"required":["balance","currency"]},"TransactionsResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/TransactionsData"},"meta":{"$ref":"#/components/schemas/Meta"},"requestId":{"type":"string","example":"req_8fK2mQx7Lp0aZ3nV1cWb","examples":["req_8fK2mQx7Lp0aZ3nV1cWb"]}},"required":["success","data","meta","requestId"]},"TransactionsData":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["items","pagination"]},"Transaction":{"type":"object","properties":{"_id":{"type":"string","example":"TX00012345","examples":["TX00012345"]},"type":{"type":"string","enum":["DEPOSIT","REFUND","ADJUSTMENT","GAIN_CONVERSION","SEND","RECEIVE","DEBT_PAYMENT"],"example":"DEPOSIT","examples":["DEPOSIT"]},"operation":{"type":"string","enum":["increment","decrement"]},"amount":{"type":"number","example":5000,"examples":[5000]},"oldBalance":{"type":["number","null"],"example":10230.5,"examples":[10230.5]},"newBalance":{"type":["number","null"],"example":15230.5,"examples":[15230.5]},"note":{"type":"string"},"time":{"type":["string","null"],"example":"2026-11-14T09:12:44.000Z","examples":["2026-11-14T09:12:44.000Z"]}},"required":["_id","type","operation","amount","oldBalance","newBalance","time"]},"Pagination":{"type":"object","properties":{"page":{"type":"integer","example":1,"examples":[1]},"pageSize":{"type":"integer","example":20,"examples":[20]},"totalPages":{"type":"integer","example":3,"examples":[3]},"totalResults":{"type":"integer","example":47,"examples":[47]}},"required":["page","pageSize","totalPages","totalResults"]},"PlansResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/PlansData"},"meta":{"$ref":"#/components/schemas/Meta"},"requestId":{"type":"string","example":"req_8fK2mQx7Lp0aZ3nV1cWb","examples":["req_8fK2mQx7Lp0aZ3nV1cWb"]}},"required":["success","data","meta","requestId"]},"PlansData":{"type":"object","properties":{"dynamicPlans":{"type":"array","items":{"$ref":"#/components/schemas/DynamicPlan"}},"fixedPlans":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}},"description":"Reserved for fixed-amount plans. Currently empty."},"offerPlans":{"type":"array","items":{"$ref":"#/components/schemas/OfferPlan"}}},"required":["dynamicPlans","fixedPlans","offerPlans"]},"DynamicPlan":{"type":"object","properties":{"code":{"type":"string","example":"PREPAID_DJEZZY","examples":["PREPAID_DJEZZY"]},"name":{"type":"string","example":"Djezzy prepaid credit","examples":["Djezzy prepaid credit"]},"operator":{"type":"string","enum":["Mobilis","Djezzy","Ooredoo"]},"type":{"type":"string","enum":["topup","bill","international"]},"isEnabled":{"type":"boolean"},"min_amount":{"type":"integer","example":100,"examples":[100]},"max_amount":{"type":"integer","example":50000,"examples":[50000]}},"required":["code","name","operator","type","isEnabled","min_amount","max_amount"]},"OfferPlan":{"type":"object","properties":{"code":{"type":"string","example":"OFFER_MOBILIS","examples":["OFFER_MOBILIS"]},"name":{"type":"string","example":"Mobilis offers and packages","examples":["Mobilis offers and packages"]},"operator":{"type":"string","enum":["Mobilis","Djezzy","Ooredoo"]},"type":{"type":"string","enum":["offer"]},"isEnabled":{"type":"boolean"},"requires":{"type":"string","enum":["offer_id"]}},"required":["code","name","operator","type","isEnabled","requires"]},"OffersResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/OffersData"},"meta":{"$ref":"#/components/schemas/Meta"},"requestId":{"type":"string","example":"req_8fK2mQx7Lp0aZ3nV1cWb","examples":["req_8fK2mQx7Lp0aZ3nV1cWb"]}},"required":["success","data","meta","requestId"]},"OffersData":{"type":"object","properties":{"MSSIDN":{"type":"string","example":"0600000009","examples":["0600000009"]},"operator":{"type":"string","enum":["Mobilis","Djezzy","Ooredoo"]},"plan_code":{"type":"string","example":"OFFER_MOBILIS","examples":["OFFER_MOBILIS"]},"expires_at":{"type":"string","example":"2026-11-15T11:00:00.000Z","examples":["2026-11-15T11:00:00.000Z"]},"offers":{"type":"array","items":{"$ref":"#/components/schemas/Offer"}}},"required":["MSSIDN","operator","plan_code","expires_at","offers"]},"Offer":{"type":"object","properties":{"offer_id":{"type":"string","description":"Opaque, signed offer id. Send it with plan_code OFFER_<OPERATOR>. Expires after 30 minutes.","example":"eyJ2IjoxLC4uLn0.q8Zr…","examples":["eyJ2IjoxLC4uLn0.q8Zr…"]},"name":{"type":"string","example":"Mix 500","examples":["Mix 500"]},"amount":{"type":["number","null"],"description":"Offer price in DZD, when known.","example":500,"examples":[500]},"debt_amount":{"type":"number","description":"Djezzy Tranquilo debt on this line, paid together with the offer. 0 when there is none.","example":0,"examples":[0]},"total_amount":{"type":["number","null"],"description":"What your balance pays: amount + debt_amount.","example":500,"examples":[500]},"category":{"type":"string","enum":["regular","internet","control"]}},"required":["offer_id","name","amount","debt_amount","total_amount","category"]},"MobileSendResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/SendData"},"meta":{"$ref":"#/components/schemas/Meta"},"requestId":{"type":"string","example":"req_8fK2mQx7Lp0aZ3nV1cWb","examples":["req_8fK2mQx7Lp0aZ3nV1cWb"]}},"required":["success","data","meta","requestId"]},"SendData":{"type":"object","properties":{"topupId":{"type":"string","description":"Top-up id, for check-id.","example":"F00012345","examples":["F00012345"]},"topupRef":{"type":"string","description":"Your ref, or the generated one.","example":"order-10293","examples":["order-10293"]}},"required":["topupId","topupRef"]},"MobileSendBody":{"type":"object","properties":{"plan_code":{"type":"string","enum":["PREPAID_MOBILIS","PREPAID_DJEZZY","PREPAID_OOREDOO","FACTURE_MOBILIS","FACTURE_DJEZZY","FACTURE_OOREDOO","OFFER_MOBILIS","OFFER_DJEZZY","OFFER_OOREDOO","INTERNATIONAL_MOBILIS"],"description":"Plan code from GET /v3/mobile/plans.","example":"PREPAID_DJEZZY","examples":["PREPAID_DJEZZY"]},"MSSIDN":{"type":"string","pattern":"^0[1567]\\d{8}$","description":"Algerian mobile number with leading 0, no spaces, no +213. 05 Ooredoo, 06 Mobilis, 07 Djezzy, 01 Ooredoo Enterprise (OOREDOO plans only).","example":"0600000009","examples":["0600000009"]},"amount":{"type":"integer","exclusiveMinimum":0,"description":"Amount in DZD. Required for PREPAID_*, FACTURE_* and INTERNATIONAL_MOBILIS; ignored for OFFER_*.","example":500,"examples":[500]},"offer_id":{"type":"string","maxLength":4096,"description":"Required for OFFER_* plans: an offer_id from GET /v3/mobile/offers."},"ref":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,64}$","description":"Your unique reference for this top-up (1-64 chars). Sending the same ref twice is refused with DUPLICATED_REF, so it is safe to retry with the same ref. Auto-generated when omitted.","example":"order-10293","examples":["order-10293"]},"on_debt":{"type":"string","enum":["WAIT","CANCEL"],"description":"What to do if the operator reports an unpaid line debt (SABBAQLI). WAIT (default): the top-up becomes DEBT_PENDING until you call resolve-debt. CANCEL: it is cancelled at once and ends REFUNDED.","example":"WAIT","examples":["WAIT"]}},"required":["plan_code","MSSIDN"],"example":{"plan_code":"PREPAID_DJEZZY","MSSIDN":"0700000009","amount":500,"ref":"order-10293"}},"ResolveDebtResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/MobileTopup"},"meta":{"$ref":"#/components/schemas/Meta"},"requestId":{"type":"string","example":"req_8fK2mQx7Lp0aZ3nV1cWb","examples":["req_8fK2mQx7Lp0aZ3nV1cWb"]}},"required":["success","data","meta","requestId"]},"MobileTopup":{"type":"object","properties":{"_id":{"type":["string","null"],"example":"F00012345","examples":["F00012345"]},"ref":{"type":["string","null"],"example":"order-10293","examples":["order-10293"]},"status":{"type":"string","enum":["PENDING","HANDLING","DEBT_PENDING","COMPLETED","REFUNDED","UNKNOWN_ERROR"]},"plan_code":{"type":["string","null"],"example":"PREPAID_DJEZZY","examples":["PREPAID_DJEZZY"]},"MSSIDN":{"type":"string","example":"0700000009","examples":["0700000009"]},"topup_amount":{"type":"number","example":500,"examples":[500]},"balance_amount":{"type":"number","description":"Amount taken from your balance (0 unless charged).","example":500,"examples":[500]},"offer_name":{"type":"string"},"debt_amount":{"type":["number","null"],"description":"Only when DEBT_PENDING: the line's unpaid debt in DZD (null if the operator did not say).","example":100,"examples":[100]},"debt_message":{"type":"string","description":"Only when DEBT_PENDING: the operator's message."},"debt_options":{"type":"array","items":{"$ref":"#/components/schemas/DebtOption"},"description":"Only when DEBT_PENDING: the choices for resolve-debt and what each costs."},"debt_expires_at":{"type":"string","description":"Only when DEBT_PENDING: after this time the top-up is cancelled (REFUNDED)."},"refund_message":{"type":"string","description":"Why the top-up failed. Only when REFUNDED."},"suggested_offers":{"type":"array","items":{"type":"object","properties":{"typename":{"type":"string"},"plan_code":{"type":"string"},"amount":{"type":"number"}},"required":["typename","plan_code","amount"]},"description":"Alternative plans to try (sandbox only for now)."},"created_at":{"type":["string","null"],"example":"2026-11-15T10:30:00.000Z","examples":["2026-11-15T10:30:00.000Z"]}},"required":["_id","ref","status","plan_code","created_at"]},"DebtOption":{"type":"object","properties":{"choice":{"type":"string","enum":["PAY_ALL","PAY_OPERATION_ONLY","PAY_DEBT_ONLY","CANCEL"]},"amount":{"type":["number","null"],"description":"What your balance pays for this choice (null if unknown).","example":600,"examples":[600]},"available":{"type":"boolean"}},"required":["choice","amount","available"]},"ResolveDebtBody":{"type":"object","properties":{"ref":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,64}$","description":"The ref of the DEBT_PENDING top-up. Send this or topupId.","example":"order-10293","examples":["order-10293"]},"topupId":{"type":"string","minLength":1,"maxLength":64,"description":"The topupId of the DEBT_PENDING top-up."},"choice":{"type":"string","enum":["PAY_ALL","PAY_OPERATION_ONLY","PAY_DEBT_ONLY","CANCEL"],"description":"PAY_ALL: the top-up plus the debt. PAY_OPERATION_ONLY: the top-up only. PAY_DEBT_ONLY: pay the debt only (a top-up equal to the debt). CANCEL: cancel, nothing is charged.","example":"PAY_ALL","examples":["PAY_ALL"]}},"required":["choice"],"example":{"ref":"order-10293","choice":"PAY_ALL"}},"MobileTopupResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/MobileTopup"},"meta":{"$ref":"#/components/schemas/Meta"},"requestId":{"type":"string","example":"req_8fK2mQx7Lp0aZ3nV1cWb","examples":["req_8fK2mQx7Lp0aZ3nV1cWb"]}},"required":["success","data","meta","requestId"]},"MobileTopupByRefResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/MobileTopup"},"meta":{"$ref":"#/components/schemas/Meta"},"requestId":{"type":"string","example":"req_8fK2mQx7Lp0aZ3nV1cWb","examples":["req_8fK2mQx7Lp0aZ3nV1cWb"]}},"required":["success","data","meta","requestId"]},"MobileListResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/MobileListData"},"meta":{"$ref":"#/components/schemas/Meta"},"requestId":{"type":"string","example":"req_8fK2mQx7Lp0aZ3nV1cWb","examples":["req_8fK2mQx7Lp0aZ3nV1cWb"]}},"required":["success","data","meta","requestId"]},"MobileListData":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MobileTopup"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["items","pagination"]},"ProductsResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/ProductsData"},"meta":{"$ref":"#/components/schemas/Meta"},"requestId":{"type":"string","example":"req_8fK2mQx7Lp0aZ3nV1cWb","examples":["req_8fK2mQx7Lp0aZ3nV1cWb"]}},"required":["success","data","meta","requestId"]},"ProductsData":{"type":"object","properties":{"type":{"type":"string","enum":["ADSL","4G"],"example":"ADSL","examples":["ADSL"]},"products":{"type":"array","items":{"$ref":"#/components/schemas/InternetProduct"}}},"required":["type","products"]},"InternetProduct":{"type":"object","properties":{"value":{"type":"integer","description":"Card value in DZD. Send it as `value`.","example":1000,"examples":[1000]},"cost":{"type":"number","description":"Amount taken from your balance.","example":1000,"examples":[1000]},"name":{"type":"string","example":"Carte 1000 DA / 40 GO (1 mois)","examples":["Carte 1000 DA / 40 GO (1 mois)"]},"available":{"type":"boolean","description":"In stock right now."}},"required":["value","cost","name","available"]},"CheckNumberResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/CheckNumberData"},"meta":{"$ref":"#/components/schemas/Meta"},"requestId":{"type":"string","example":"req_8fK2mQx7Lp0aZ3nV1cWb","examples":["req_8fK2mQx7Lp0aZ3nV1cWb"]}},"required":["success","data","meta","requestId"]},"CheckNumberData":{"type":"object","properties":{"number":{"type":"string","example":"030000009","examples":["030000009"]},"type":{"type":"string","enum":["ADSL","4GLTE"]},"ncli":{"type":["string","null"],"description":"Masked client number.","example":"11022*****","examples":["11022*****"]},"offre":{"type":"string","description":"Current offer, when known.","example":"FTTH 100M","examples":["FTTH 100M"]}},"required":["number","type"]},"InternetSendResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/SendData"},"meta":{"$ref":"#/components/schemas/Meta"},"requestId":{"type":"string","example":"req_8fK2mQx7Lp0aZ3nV1cWb","examples":["req_8fK2mQx7Lp0aZ3nV1cWb"]}},"required":["success","data","meta","requestId"]},"InternetSendBody":{"type":"object","properties":{"type":{"type":"string","enum":["ADSL","4G"],"example":"ADSL","examples":["ADSL"]},"number":{"type":"string","pattern":"^(0[1-9]\\d{7}|2134\\d{8})$","description":"ADSL: fixed line like 030000009. 4G: 2134XXXXXXXX (no +).","example":"030000009","examples":["030000009"]},"value":{"type":"integer","exclusiveMinimum":0,"description":"Card value from GET /v3/internet/products.","example":1000,"examples":[1000]},"ref":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,64}$","description":"Your unique reference for this top-up (1-64 chars). Sending the same ref twice is refused with DUPLICATED_REF, so it is safe to retry with the same ref. Auto-generated when omitted.","example":"order-10293","examples":["order-10293"]}},"required":["type","number","value"],"example":{"type":"ADSL","number":"030000009","value":1000,"ref":"order-10294"}},"InternetTopupResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/InternetTopup"},"meta":{"$ref":"#/components/schemas/Meta"},"requestId":{"type":"string","example":"req_8fK2mQx7Lp0aZ3nV1cWb","examples":["req_8fK2mQx7Lp0aZ3nV1cWb"]}},"required":["success","data","meta","requestId"]},"InternetTopup":{"type":"object","properties":{"_id":{"type":["string","null"],"example":"T00045678","examples":["T00045678"]},"ref":{"type":["string","null"],"example":"order-10294","examples":["order-10294"]},"status":{"type":"string","enum":["HANDLING","COMPLETED","REFUNDED","MANUAL_REDEEM","UNKNOWN_ERROR"]},"type":{"type":["string","null"],"enum":["ADSL","4G",null]},"number":{"type":"string","example":"030000009","examples":["030000009"]},"topup_amount":{"type":"number","example":1000,"examples":[1000]},"balance_amount":{"type":"number","example":1000,"examples":[1000]},"card_name":{"type":"string"},"card_code":{"type":"string","description":"Only for MANUAL_REDEEM: the card to redeem by hand."},"serial_number":{"type":"string","description":"Only for MANUAL_REDEEM."},"num_trans":{"type":"string","description":"Transaction number, when COMPLETED."},"refund_message":{"type":"string"},"manual_message":{"type":"string"},"created_at":{"type":["string","null"],"example":"2026-11-15T10:31:00.000Z","examples":["2026-11-15T10:31:00.000Z"]}},"required":["_id","ref","status","type","created_at"]},"InternetTopupByRefResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/InternetTopup"},"meta":{"$ref":"#/components/schemas/Meta"},"requestId":{"type":"string","example":"req_8fK2mQx7Lp0aZ3nV1cWb","examples":["req_8fK2mQx7Lp0aZ3nV1cWb"]}},"required":["success","data","meta","requestId"]},"InternetListResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/InternetListData"},"meta":{"$ref":"#/components/schemas/Meta"},"requestId":{"type":"string","example":"req_8fK2mQx7Lp0aZ3nV1cWb","examples":["req_8fK2mQx7Lp0aZ3nV1cWb"]}},"required":["success","data","meta","requestId"]},"InternetListData":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/InternetTopup"}},"topups":{"type":"array","items":{"$ref":"#/components/schemas/InternetTopup"},"description":"Same as items. Kept for clients migrating from other v3 APIs."},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["items","topups","pagination"]}},"parameters":{}},"paths":{"/v3/ping":{"get":{"tags":["Core"],"summary":"Health check","description":"Checks that the API and the operators are reachable. No API key needed. Poll every 30-60 seconds at most.","responses":{"200":{"description":"API and operator status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PingResponse"}}}},"503":{"description":"Temporarily unavailable (ERR_SERVICE, AUTH_UNAVAILABLE, SERVICE_UNAVAILABLE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/validate":{"get":{"tags":["Core"],"summary":"Validate API key","description":"Returns the account and key details for the key you send. Use `apiKey.type` to know if you are in SANDBOX or PRODUCTION.","security":[{"AccessToken":[]}],"responses":{"200":{"description":"Key details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateResponse"}}}},"400":{"description":"Invalid request (ERR_VALIDATION, ERR_PHONE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key (MISSING_ACCESS_TOKEN, INVALID_ACCESS_TOKEN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed (IP_BLOCKED, IP_NOT_ALLOWED, API_DISABLED, ACCOUNT_DISABLED, READ_ONLY_KEY, INSUFFICIENT_BALANCE, DUPLICATED_REF, ERR_STOCK)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (RATE_LIMIT_EXCEEDED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable (ERR_SERVICE, AUTH_UNAVAILABLE, SERVICE_UNAVAILABLE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/account/balance":{"get":{"tags":["Account"],"summary":"Get balance","description":"Your available balance in DZD. Sandbox keys always see 100000.","security":[{"AccessToken":[]}],"responses":{"200":{"description":"Current balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceResponse"}}}},"400":{"description":"Invalid request (ERR_VALIDATION, ERR_PHONE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key (MISSING_ACCESS_TOKEN, INVALID_ACCESS_TOKEN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed (IP_BLOCKED, IP_NOT_ALLOWED, API_DISABLED, ACCOUNT_DISABLED, READ_ONLY_KEY, INSUFFICIENT_BALANCE, DUPLICATED_REF, ERR_STOCK)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (RATE_LIMIT_EXCEEDED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable (ERR_SERVICE, AUTH_UNAVAILABLE, SERVICE_UNAVAILABLE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/account/transactions":{"get":{"tags":["Account"],"summary":"List balance transactions","description":"Deposits, refunds, adjustments and transfers on your balance, newest first. Top-ups are listed in /mobile/list and /internet/list.","security":[{"AccessToken":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number, starting at 1.","example":1,"examples":[1]},"required":false,"description":"Page number, starting at 1.","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Items per page (1-100).","example":20,"examples":[20]},"required":false,"description":"Items per page (1-100).","name":"pageSize","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Start of the date range (ISO 8601). Send together with `to`.","example":"2026-11-01T00:00:00Z","examples":["2026-11-01T00:00:00Z"]},"required":false,"description":"Start of the date range (ISO 8601). Send together with `to`.","name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End of the date range (ISO 8601). Send together with `from`.","example":"2026-11-15T23:59:59Z","examples":["2026-11-15T23:59:59Z"]},"required":false,"description":"End of the date range (ISO 8601). Send together with `from`.","name":"to","in":"query"}],"responses":{"200":{"description":"A page of transactions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionsResponse"}}}},"400":{"description":"Invalid request (ERR_VALIDATION, ERR_PHONE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key (MISSING_ACCESS_TOKEN, INVALID_ACCESS_TOKEN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed (IP_BLOCKED, IP_NOT_ALLOWED, API_DISABLED, ACCOUNT_DISABLED, READ_ONLY_KEY, INSUFFICIENT_BALANCE, DUPLICATED_REF, ERR_STOCK)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (RATE_LIMIT_EXCEEDED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable (ERR_SERVICE, AUTH_UNAVAILABLE, SERVICE_UNAVAILABLE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/mobile/plans":{"get":{"tags":["Mobile top-up"],"summary":"List plans","description":"Plans you can send. `dynamicPlans` take an `amount` between `min_amount` and `max_amount`. `offerPlans` (OFFER_*) need an `offer_id` from GET /v3/mobile/offers. Safe to cache for a few minutes.","security":[{"AccessToken":[]}],"responses":{"200":{"description":"Available plans","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlansResponse"}}}},"400":{"description":"Invalid request (ERR_VALIDATION, ERR_PHONE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key (MISSING_ACCESS_TOKEN, INVALID_ACCESS_TOKEN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed (IP_BLOCKED, IP_NOT_ALLOWED, API_DISABLED, ACCOUNT_DISABLED, READ_ONLY_KEY, INSUFFICIENT_BALANCE, DUPLICATED_REF, ERR_STOCK)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (RATE_LIMIT_EXCEEDED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable (ERR_SERVICE, AUTH_UNAVAILABLE, SERVICE_UNAVAILABLE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/mobile/offers":{"get":{"tags":["Mobile top-up"],"summary":"List offers for a number","description":"Asks the operator which offers (packages, internet bundles) a number can receive. Each offer has a signed `offer_id`, valid 30 minutes, to send with plan_code `OFFER_<OPERATOR>`. This call can take a few seconds.","security":[{"AccessToken":[]}],"parameters":[{"schema":{"type":"string","enum":["mobilis","djezzy","ooredoo"],"example":"mobilis","examples":["mobilis"]},"required":true,"name":"operator","in":"query"},{"schema":{"type":"string","pattern":"^0[1567]\\d{8}$","description":"Algerian mobile number with leading 0, no spaces, no +213. 05 Ooredoo, 06 Mobilis, 07 Djezzy, 01 Ooredoo Enterprise (OOREDOO plans only).","example":"0600000009","examples":["0600000009"]},"required":true,"description":"Algerian mobile number with leading 0, no spaces, no +213. 05 Ooredoo, 06 Mobilis, 07 Djezzy, 01 Ooredoo Enterprise (OOREDOO plans only).","name":"MSSIDN","in":"query"}],"responses":{"200":{"description":"Offers for this number","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffersResponse"}}}},"400":{"description":"Invalid request (ERR_VALIDATION, ERR_PHONE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key (MISSING_ACCESS_TOKEN, INVALID_ACCESS_TOKEN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed (IP_BLOCKED, IP_NOT_ALLOWED, API_DISABLED, ACCOUNT_DISABLED, READ_ONLY_KEY, INSUFFICIENT_BALANCE, DUPLICATED_REF, ERR_STOCK)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (RATE_LIMIT_EXCEEDED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable (ERR_SERVICE, AUTH_UNAVAILABLE, SERVICE_UNAVAILABLE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/mobile/send":{"post":{"tags":["Mobile top-up"],"summary":"Send a mobile top-up","description":"Starts a top-up and returns at once with `topupId` and `topupRef`. The result comes later: poll check-id or check-ref until the status is final (COMPLETED, REFUNDED or UNKNOWN_ERROR). DEBT_PENDING means the line has an unpaid debt: answer with POST /v3/mobile/resolve-debt. Always send your own `ref`; if the call fails or times out, check that ref before sending again.","security":[{"AccessToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MobileSendBody"}}}},"responses":{"200":{"description":"Top-up accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MobileSendResponse"}}}},"400":{"description":"Invalid request (ERR_VALIDATION, ERR_PHONE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key (MISSING_ACCESS_TOKEN, INVALID_ACCESS_TOKEN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed (IP_BLOCKED, IP_NOT_ALLOWED, API_DISABLED, ACCOUNT_DISABLED, READ_ONLY_KEY, INSUFFICIENT_BALANCE, DUPLICATED_REF, ERR_STOCK)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"DUPLICATE_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (RATE_LIMIT_EXCEEDED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable (ERR_SERVICE, AUTH_UNAVAILABLE, SERVICE_UNAVAILABLE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/mobile/resolve-debt":{"post":{"tags":["Mobile top-up"],"summary":"Answer a line-debt question","description":"When a top-up is DEBT_PENDING the operator reported an unpaid line debt (SABBAQLI) and waits for a decision. Choose PAY_ALL, PAY_OPERATION_ONLY, PAY_DEBT_ONLY or CANCEL; debt_options on the top-up shows what each costs. The top-up then continues (PENDING → … → COMPLETED) or ends REFUNDED for CANCEL. Unanswered top-ups are cancelled at debt_expires_at.","security":[{"AccessToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveDebtBody"}}}},"responses":{"200":{"description":"The top-up after the decision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveDebtResponse"}}}},"400":{"description":"Invalid request (ERR_VALIDATION, ERR_PHONE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key (MISSING_ACCESS_TOKEN, INVALID_ACCESS_TOKEN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed (IP_BLOCKED, IP_NOT_ALLOWED, API_DISABLED, ACCOUNT_DISABLED, READ_ONLY_KEY, INSUFFICIENT_BALANCE, DUPLICATED_REF, ERR_STOCK)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"NOT_DEBT_PENDING","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (RATE_LIMIT_EXCEEDED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable (ERR_SERVICE, AUTH_UNAVAILABLE, SERVICE_UNAVAILABLE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/mobile/check-id/{id}":{"get":{"tags":["Mobile top-up"],"summary":"Check a top-up by id","description":"Status of one top-up by its `topupId`. Poll every 5-10 seconds while PENDING or HANDLING. On DEBT_PENDING, stop polling and call resolve-debt.","security":[{"AccessToken":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"example":"F00012345","examples":["F00012345"]},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The top-up","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MobileTopupResponse"}}}},"400":{"description":"Invalid request (ERR_VALIDATION, ERR_PHONE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key (MISSING_ACCESS_TOKEN, INVALID_ACCESS_TOKEN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed (IP_BLOCKED, IP_NOT_ALLOWED, API_DISABLED, ACCOUNT_DISABLED, READ_ONLY_KEY, INSUFFICIENT_BALANCE, DUPLICATED_REF, ERR_STOCK)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (RATE_LIMIT_EXCEEDED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable (ERR_SERVICE, AUTH_UNAVAILABLE, SERVICE_UNAVAILABLE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/mobile/check-ref/{ref}":{"get":{"tags":["Mobile top-up"],"summary":"Check a top-up by ref","description":"Status of one top-up by your `ref`. Use it to recover after a timeout or a DUPLICATED_REF answer.","security":[{"AccessToken":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"example":"order-10293","examples":["order-10293"]},"required":true,"name":"ref","in":"path"}],"responses":{"200":{"description":"The top-up","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MobileTopupByRefResponse"}}}},"400":{"description":"Invalid request (ERR_VALIDATION, ERR_PHONE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key (MISSING_ACCESS_TOKEN, INVALID_ACCESS_TOKEN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed (IP_BLOCKED, IP_NOT_ALLOWED, API_DISABLED, ACCOUNT_DISABLED, READ_ONLY_KEY, INSUFFICIENT_BALANCE, DUPLICATED_REF, ERR_STOCK)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (RATE_LIMIT_EXCEEDED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable (ERR_SERVICE, AUTH_UNAVAILABLE, SERVICE_UNAVAILABLE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/mobile/list":{"get":{"tags":["Mobile top-up"],"summary":"List mobile top-ups","description":"Top-ups sent with your API keys, newest first.","security":[{"AccessToken":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number, starting at 1.","example":1,"examples":[1]},"required":false,"description":"Page number, starting at 1.","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Items per page (1-100).","example":20,"examples":[20]},"required":false,"description":"Items per page (1-100).","name":"pageSize","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Start of the date range (ISO 8601). Send together with `to`.","example":"2026-11-01T00:00:00Z","examples":["2026-11-01T00:00:00Z"]},"required":false,"description":"Start of the date range (ISO 8601). Send together with `to`.","name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End of the date range (ISO 8601). Send together with `from`.","example":"2026-11-15T23:59:59Z","examples":["2026-11-15T23:59:59Z"]},"required":false,"description":"End of the date range (ISO 8601). Send together with `from`.","name":"to","in":"query"}],"responses":{"200":{"description":"A page of top-ups","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MobileListResponse"}}}},"400":{"description":"Invalid request (ERR_VALIDATION, ERR_PHONE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key (MISSING_ACCESS_TOKEN, INVALID_ACCESS_TOKEN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed (IP_BLOCKED, IP_NOT_ALLOWED, API_DISABLED, ACCOUNT_DISABLED, READ_ONLY_KEY, INSUFFICIENT_BALANCE, DUPLICATED_REF, ERR_STOCK)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (RATE_LIMIT_EXCEEDED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable (ERR_SERVICE, AUTH_UNAVAILABLE, SERVICE_UNAVAILABLE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/internet/products":{"get":{"tags":["Internet top-up"],"summary":"List card values","description":"Idoom card values you can send for ADSL or 4G, with stock. Send the `value` with POST /v3/internet/send.","security":[{"AccessToken":[]}],"parameters":[{"schema":{"type":"string","enum":["ADSL","4G"],"example":"ADSL","examples":["ADSL"]},"required":true,"name":"type","in":"query"}],"responses":{"200":{"description":"Card values","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductsResponse"}}}},"400":{"description":"Invalid request (ERR_VALIDATION, ERR_PHONE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key (MISSING_ACCESS_TOKEN, INVALID_ACCESS_TOKEN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed (IP_BLOCKED, IP_NOT_ALLOWED, API_DISABLED, ACCOUNT_DISABLED, READ_ONLY_KEY, INSUFFICIENT_BALANCE, DUPLICATED_REF, ERR_STOCK)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (RATE_LIMIT_EXCEEDED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable (ERR_SERVICE, AUTH_UNAVAILABLE, SERVICE_UNAVAILABLE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/internet/check-number":{"get":{"tags":["Internet top-up"],"summary":"Validate a line number","description":"Checks with Algérie Télécom that the line exists for this type. Optional before a send, but it catches typos early. Can take a few seconds.","security":[{"AccessToken":[]}],"parameters":[{"schema":{"type":"string","enum":["ADSL","4G"],"example":"ADSL","examples":["ADSL"]},"required":true,"name":"type","in":"query"},{"schema":{"type":"string","pattern":"^(0[1-9]\\d{7}|2134\\d{8})$","description":"ADSL: fixed line like 030000009. 4G: 2134XXXXXXXX (no +).","example":"030000009","examples":["030000009"]},"required":true,"description":"ADSL: fixed line like 030000009. 4G: 2134XXXXXXXX (no +).","name":"number","in":"query"}],"responses":{"200":{"description":"The line exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckNumberResponse"}}}},"400":{"description":"Invalid request (ERR_VALIDATION, ERR_PHONE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key (MISSING_ACCESS_TOKEN, INVALID_ACCESS_TOKEN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed (IP_BLOCKED, IP_NOT_ALLOWED, API_DISABLED, ACCOUNT_DISABLED, READ_ONLY_KEY, INSUFFICIENT_BALANCE, DUPLICATED_REF, ERR_STOCK)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (RATE_LIMIT_EXCEEDED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable (ERR_SERVICE, AUTH_UNAVAILABLE, SERVICE_UNAVAILABLE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/internet/send":{"post":{"tags":["Internet top-up"],"summary":"Send an internet top-up","description":"Starts an Idoom ADSL or 4G top-up and returns at once. Poll check-id or check-ref until the status is final (COMPLETED, REFUNDED, MANUAL_REDEEM or UNKNOWN_ERROR).","security":[{"AccessToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternetSendBody"}}}},"responses":{"200":{"description":"Top-up accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternetSendResponse"}}}},"400":{"description":"Invalid request (ERR_VALIDATION, ERR_PHONE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key (MISSING_ACCESS_TOKEN, INVALID_ACCESS_TOKEN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed (IP_BLOCKED, IP_NOT_ALLOWED, API_DISABLED, ACCOUNT_DISABLED, READ_ONLY_KEY, INSUFFICIENT_BALANCE, DUPLICATED_REF, ERR_STOCK)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"DUPLICATE_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (RATE_LIMIT_EXCEEDED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable (ERR_SERVICE, AUTH_UNAVAILABLE, SERVICE_UNAVAILABLE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/internet/check-id/{id}":{"get":{"tags":["Internet top-up"],"summary":"Check a top-up by id","description":"Status of one internet top-up by its `topupId`. Poll every 5 seconds while HANDLING.","security":[{"AccessToken":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"example":"F00012345","examples":["F00012345"]},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The top-up","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternetTopupResponse"}}}},"400":{"description":"Invalid request (ERR_VALIDATION, ERR_PHONE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key (MISSING_ACCESS_TOKEN, INVALID_ACCESS_TOKEN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed (IP_BLOCKED, IP_NOT_ALLOWED, API_DISABLED, ACCOUNT_DISABLED, READ_ONLY_KEY, INSUFFICIENT_BALANCE, DUPLICATED_REF, ERR_STOCK)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (RATE_LIMIT_EXCEEDED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable (ERR_SERVICE, AUTH_UNAVAILABLE, SERVICE_UNAVAILABLE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/internet/check-ref/{ref}":{"get":{"tags":["Internet top-up"],"summary":"Check a top-up by ref","description":"Status of one internet top-up by your `ref`.","security":[{"AccessToken":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"example":"order-10293","examples":["order-10293"]},"required":true,"name":"ref","in":"path"}],"responses":{"200":{"description":"The top-up","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternetTopupByRefResponse"}}}},"400":{"description":"Invalid request (ERR_VALIDATION, ERR_PHONE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key (MISSING_ACCESS_TOKEN, INVALID_ACCESS_TOKEN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed (IP_BLOCKED, IP_NOT_ALLOWED, API_DISABLED, ACCOUNT_DISABLED, READ_ONLY_KEY, INSUFFICIENT_BALANCE, DUPLICATED_REF, ERR_STOCK)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (RATE_LIMIT_EXCEEDED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable (ERR_SERVICE, AUTH_UNAVAILABLE, SERVICE_UNAVAILABLE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v3/internet/list":{"get":{"tags":["Internet top-up"],"summary":"List internet top-ups","description":"Internet top-ups sent with your API keys, newest first. `topups` repeats `items` for clients migrating from other v3 APIs.","security":[{"AccessToken":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number, starting at 1.","example":1,"examples":[1]},"required":false,"description":"Page number, starting at 1.","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Items per page (1-100).","example":20,"examples":[20]},"required":false,"description":"Items per page (1-100).","name":"pageSize","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Start of the date range (ISO 8601). Send together with `to`.","example":"2026-11-01T00:00:00Z","examples":["2026-11-01T00:00:00Z"]},"required":false,"description":"Start of the date range (ISO 8601). Send together with `to`.","name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End of the date range (ISO 8601). Send together with `from`.","example":"2026-11-15T23:59:59Z","examples":["2026-11-15T23:59:59Z"]},"required":false,"description":"End of the date range (ISO 8601). Send together with `from`.","name":"to","in":"query"}],"responses":{"200":{"description":"A page of top-ups","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternetListResponse"}}}},"400":{"description":"Invalid request (ERR_VALIDATION, ERR_PHONE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key (MISSING_ACCESS_TOKEN, INVALID_ACCESS_TOKEN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed (IP_BLOCKED, IP_NOT_ALLOWED, API_DISABLED, ACCOUNT_DISABLED, READ_ONLY_KEY, INSUFFICIENT_BALANCE, DUPLICATED_REF, ERR_STOCK)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (RATE_LIMIT_EXCEEDED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (INTERNAL_ERROR)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable (ERR_SERVICE, AUTH_UNAVAILABLE, SERVICE_UNAVAILABLE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}