API Docs
OpenAPI spec (opens in a new tab)

Services API

Last updated

Browse available SMS verification services with current pricing, stock levels and the time you have to receive the code.

The service object

Both endpoints return services with these fields. An order can receive its code for code_window_seconds after purchase. The value depends on the service: the window ends shortly before its reservation (ttl_minutes) runs out. An order with no code expires when its window ends and its price is credited back to your balance.

FieldTypeDescription
namestringService identifier; use this value when placing orders
display_namestringHuman-readable service name
pricenumberPrice in USD per number rental
carrier_pricenumberPrice in USD when you choose a specific carrier (AT&T or T-Mobile): about 20% more
stockintegerNumbers available right now. 0 means temporarily out of stock; the service is still listed.
ttl_minutesintegerMinutes the number is reserved for this service. Not the order deadline; see code_window_seconds.
code_window_secondsintegerSeconds you have to receive the code after renting. It can differ from one service to another.

GET /v1/services

List services with price, carrier price, stock and code window

Query parameters for listing services

NameTypeRequiredDescription
searchstringNoFilter services by name
pageintegerNoPage number (default: 1)
per_pageintegerNoResults per page, 1-100 (default: 20)
curl "https://api.diddysms.com/v1/services?search=google" \
  -H "Authorization: Bearer dsk_your_api_key_here"
resp = requests.get(
    "https://api.diddysms.com/v1/services",
    headers={"Authorization": "Bearer dsk_your_api_key_here"},
    params={"search": "google"},
)
print(resp.json())
const resp = await fetch(
  "https://api.diddysms.com/v1/services?search=google",
  { headers: { Authorization: "Bearer dsk_your_api_key_here" } }
);
const data = await resp.json();

Response

{
  "services": [
    {
      "name": "google",
      "display_name": "Google",
      "price": 1.50,
      "carrier_price": 1.80,
      "stock": 142,
      "ttl_minutes": 10,
      "code_window_seconds": 540
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total_pages": 1
  }
}

Error responses

StatusCodeMeaning
503SERVICE_UNAVAILABLETemporarily unable to load services. Please try again.

GET /v1/services/{service_name}

Get the price, stock and code window of one service

Path parameter for a single service

NameTypeRequiredDescription
service_namestringYesService identifier (e.g. "google")
curl https://api.diddysms.com/v1/services/google \
  -H "Authorization: Bearer dsk_your_api_key_here"

Response

{
  "name": "google",
  "display_name": "Google",
  "price": 1.50,
  "carrier_price": 1.80,
  "stock": 142,
  "ttl_minutes": 10,
  "code_window_seconds": 540
}

Error responses

StatusCodeMeaning
404NOT_FOUNDService does not exist
503SERVICE_UNAVAILABLETemporarily unable to load the service. Please try again.