Get a key
Create a key on your API keys page. It starts with sbz_ and is shown once, so store it somewhere safe. Send it on every request as a bearer token. Orders are paid from the same naira wallet as the dashboard.
Authorization: Bearer sbz_…Call the API from your server only. A key in a browser or mobile app can be copied and spent from your wallet, so if one leaks, revoke it on the same page and create a new one.
Build your first call
Choose an app and a country that are on sale right now. The call below is ready to paste.
List what's on sale
Every app and country with stock, the cheapest price for each, and how many numbers are available. Prices are in kobo (₦1 = 100 kobo).
GET https://simbazaar.com/api/v1/catalogue
{ "data": [
{ "country": "NG", "service": "whatsapp", "stock": 25, "price_kobo": 25000 }
] }Buy a number
Send the app's service name and the two-letter country code from the catalogue. The price is held from your wallet and charged only when a code arrives. The response is your order, with status: "active" and the number to use.
POST https://simbazaar.com/api/v1/orders
{ "service": "whatsapp", "country": "NG" }
201 Created
{ "data": {
"uuid": "9c1b…",
"status": "active",
"phone_number": "+2348101234567",
"price_kobo": 25000,
"expires_at": "…T12:20:00+01:00",
"code_received_at": null,
"codes": [] } }Read the code
Ask for the order every few seconds until codes has something in it, or status becomes final. If no code arrives before expires_at, the order expires and the hold is lifted on its own.
GET https://simbazaar.com/api/v1/orders/{uuid}
{ "data": { "status": "code_received", "codes": ["482913"], … } }Cancel
If no code has come, you can cancel once the order has been active for two minutes, the same as in the dashboard. The hold is lifted straight away.
POST https://simbazaar.com/api/v1/orders/{uuid}/cancelLimits and errors
- Rate limits, per key: 60 orders a minute and 120 requests a minute in total. Going over returns
429; wait and try again. - Something refused:
422with a plain-languagemessage, for example too little in your wallet or an app that isn't on sale. - Key missing or wrong:
401. - Your customers' use: you're responsible for it, and must apply rules at least as strict as our Acceptable Use Policy.