{ "components": { "schemas": { "ApiError": { "description": "Error body. `detail.error.code` is a stable machine-readable code; `detail.error.message` is for people.", "properties": { "detail": { "$ref": "#/components/schemas/ApiErrorBody" } }, "required": [ "detail" ], "title": "ApiError", "type": "object" }, "ApiErrorBody": { "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail" } }, "required": [ "error" ], "title": "ApiErrorBody", "type": "object" }, "ApiKeyResponse": { "properties": { "api_key": { "title": "Api Key", "type": "string" }, "message": { "default": "Store this key securely. It will not be shown again.", "title": "Message", "type": "string" }, "name": { "title": "Name", "type": "string" }, "prefix": { "title": "Prefix", "type": "string" } }, "required": [ "api_key", "prefix", "name" ], "title": "ApiKeyResponse", "type": "object" }, "BalanceResponse": { "properties": { "balance": { "title": "Balance", "type": "number" }, "currency": { "default": "USD", "title": "Currency", "type": "string" } }, "required": [ "balance" ], "title": "BalanceResponse", "type": "object" }, "CreateOrderRequest": { "properties": { "carrier": { "anyOf": [ { "enum": [ "at&t", "tmobile" ], "type": "string" }, { "type": "null" } ], "description": "Optional: choose 'at&t' or 'tmobile', for about 20% more. You get a number on that carrier, or 409 OUT_OF_STOCK (scope 'carrier') and nothing is charged. Omit to get whichever carrier is available.", "title": "Carrier" }, "carrier_fallback": { "default": "none", "description": "Only with `carrier`: what to do when that carrier has no numbers. 'none' (default): fail with 409 OUT_OF_STOCK. 'any': buy a number on whichever carrier is available instead, at the normal price; the order then has `carrier: null` and `requested_carrier` set to the carrier you asked for.", "enum": [ "none", "any" ], "title": "Carrier Fallback", "type": "string" }, "service": { "maxLength": 100, "minLength": 1, "title": "Service", "type": "string" } }, "required": [ "service" ], "title": "CreateOrderRequest", "type": "object" }, "ErrorDetail": { "properties": { "code": { "title": "Code", "type": "string" }, "message": { "title": "Message", "type": "string" }, "scope": { "anyOf": [ { "enum": [ "carrier", "service" ], "type": "string" }, { "type": "null" } ], "description": "OUT_OF_STOCK on a purchase only: 'carrier' when only the chosen carrier has no numbers (retrying without `carrier` can succeed), 'service' when the service has none.", "title": "Scope" } }, "required": [ "code", "message" ], "title": "ErrorDetail", "type": "object" }, "GenerateApiKeyRequest": { "properties": { "name": { "default": "default", "maxLength": 100, "title": "Name", "type": "string" } }, "title": "GenerateApiKeyRequest", "type": "object" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "title": "Detail", "type": "array" } }, "title": "HTTPValidationError", "type": "object" }, "OrderResponse": { "properties": { "carrier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The carrier of this number ('at&t' or 'tmobile') when you chose one, else null (whichever carrier was available).", "title": "Carrier" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Completed At" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Deadline for the SMS code: no code arrives after this time. An order with no code is expired and its price credited back to your balance automatically, at this time or, for a service whose code window is shorter than most, a few minutes later.", "title": "Expires At" }, "followup_codes": { "items": { "type": "string" }, "title": "Followup Codes", "type": "array" }, "id": { "title": "Id", "type": "integer" }, "messages": { "description": "Every SMS received on this order, oldest first: the one with sms_code, then any follow-up codes. Empty until the code arrives.", "items": { "$ref": "#/components/schemas/SmsMessage" }, "title": "Messages", "type": "array" }, "phone_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone Number" }, "price": { "title": "Price", "type": "number" }, "requested_carrier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The carrier you asked for. Equals `carrier`, except when carrier_fallback 'any' bought a number on whichever carrier was available, at the normal price: then `carrier` is null and this keeps your choice.", "title": "Requested Carrier" }, "service": { "title": "Service", "type": "string" }, "service_display_name": { "title": "Service Display Name", "type": "string" }, "sms_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The verification code, null until it arrives. Digits come without spaces. For some services it is a link plus an ID rather than digits.", "title": "Sms Code" }, "sms_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The full SMS text the code came in, as plain text. It may contain a link: treat it as untrusted text. null until the code arrives, when no text was received, and 30 days after the SMS arrived.", "title": "Sms Message" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "service", "service_display_name", "phone_number", "status", "price", "created_at" ], "title": "OrderResponse", "type": "object" }, "OrderWrapper": { "properties": { "order": { "$ref": "#/components/schemas/OrderResponse" } }, "required": [ "order" ], "title": "OrderWrapper", "type": "object" }, "OrdersListResponse": { "properties": { "orders": { "items": { "$ref": "#/components/schemas/OrderResponse" }, "title": "Orders", "type": "array" }, "pagination": { "$ref": "#/components/schemas/OrdersPaginationMeta" } }, "required": [ "orders", "pagination" ], "title": "OrdersListResponse", "type": "object" }, "OrdersPaginationMeta": { "properties": { "limit": { "title": "Limit", "type": "integer" }, "offset": { "title": "Offset", "type": "integer" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "limit", "offset", "total" ], "title": "OrdersPaginationMeta", "type": "object" }, "PaginationMeta": { "properties": { "page": { "title": "Page", "type": "integer" }, "per_page": { "title": "Per Page", "type": "integer" }, "total_pages": { "title": "Total Pages", "type": "integer" } }, "required": [ "page", "per_page", "total_pages" ], "title": "PaginationMeta", "type": "object" }, "RateLimitError": { "description": "The per-key rate limit for this endpoint was exceeded. This body carries no error code.", "properties": { "error": { "examples": [ "Rate limit exceeded: 60 per 1 minute" ], "title": "Error", "type": "string" } }, "required": [ "error" ], "title": "RateLimitError", "type": "object" }, "ServiceResponse": { "properties": { "carrier_price": { "title": "Carrier Price", "type": "number" }, "code_window_seconds": { "description": "Seconds after purchase in which an order of this service can receive its SMS code; no code arrives after that. An order with no code is expired and its price credited back to your balance automatically, when the window ends or, for a service whose window is shorter than most, a few minutes later.", "title": "Code Window Seconds", "type": "integer" }, "display_name": { "title": "Display Name", "type": "string" }, "name": { "title": "Name", "type": "string" }, "price": { "title": "Price", "type": "number" }, "stock": { "description": "Available phone numbers right now. 0 means the service is temporarily out of stock — the entry is still returned so clients can render an 'unavailable' state instead of silently dropping the service.", "title": "Stock", "type": "integer" }, "tier": { "anyOf": [ { "enum": [ "user_top", "popular", "alphabetical" ], "type": "string" }, { "type": "null" } ], "title": "Tier" }, "ttl_minutes": { "description": "Minutes the phone number is reserved. This is not the order deadline: see code_window_seconds.", "title": "Ttl Minutes", "type": "integer" } }, "required": [ "name", "display_name", "price", "carrier_price", "stock", "ttl_minutes", "code_window_seconds" ], "title": "ServiceResponse", "type": "object" }, "ServicesListResponse": { "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "services": { "items": { "$ref": "#/components/schemas/ServiceResponse" }, "title": "Services", "type": "array" } }, "required": [ "services", "pagination" ], "title": "ServicesListResponse", "type": "object" }, "SmsMessage": { "properties": { "code": { "description": "The code this SMS carried.", "title": "Code", "type": "string" }, "received_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the SMS arrived (UTC).", "title": "Received At" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The full SMS text, as plain text. It may contain a link: treat it as untrusted text. null when none was received and 30 days after the SMS arrived.", "title": "Text" } }, "required": [ "code" ], "title": "SmsMessage", "type": "object" }, "TransactionResponse": { "properties": { "amount": { "title": "Amount", "type": "number" }, "balance_after": { "title": "Balance After", "type": "number" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "id": { "title": "Id", "type": "integer" }, "reference_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Reference Id" }, "type": { "title": "Type", "type": "string" } }, "required": [ "id", "type", "amount", "balance_after", "created_at" ], "title": "TransactionResponse", "type": "object" }, "TransactionsListResponse": { "properties": { "pagination": { "$ref": "#/components/schemas/OrdersPaginationMeta" }, "transactions": { "items": { "$ref": "#/components/schemas/TransactionResponse" }, "title": "Transactions", "type": "array" } }, "required": [ "transactions", "pagination" ], "title": "TransactionsListResponse", "type": "object" }, "ValidationError": { "properties": { "ctx": { "title": "Context", "type": "object" }, "input": { "title": "Input" }, "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "title": "Location", "type": "array" }, "msg": { "title": "Message", "type": "string" }, "type": { "title": "Error Type", "type": "string" } }, "required": [ "loc", "msg", "type" ], "title": "ValidationError", "type": "object" } }, "securitySchemes": { "ApiKey": { "bearerFormat": "dsk_ API key", "description": "Your DiddySMS API key, sent as `Authorization: Bearer dsk_...`. Keys start with `dsk_` and are 52 characters long. A key is shown once, when it is created, and creating a new key revokes the previous one.", "scheme": "bearer", "type": "http" } } }, "externalDocs": { "description": "API documentation", "url": "https://diddysms.com/docs" }, "info": { "contact": { "name": "DiddySMS support", "url": "https://diddysms.com/support" }, "description": "REST API of DiddySMS, the US non-VoIP SMS verification number service: rent a temporary US phone number for a service, then read the SMS verification code it receives. Prices are in USD.\n\nEvery request needs an API key, sent as `Authorization: Bearer dsk_...`. Create your first key in your account at https://diddysms.com/account/api-keys.\n\nHTTPS only, with TLS 1.2 or newer (TLS 1.3 supported and preferred); TLS 1.0 and 1.1 are refused. Never send a request over plain `http://`: it is only redirected, after your API key has already travelled unencrypted.\n\nThe full reference, with the order lifecycle, rate limits, business rules and every error code, is at https://diddysms.com/docs, and as one Markdown file at https://diddysms.com/llms-full.txt.", "termsOfService": "https://diddysms.com/terms", "title": "DiddySMS Public API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/v1/auth/api-key": { "post": { "description": "Authenticate with your current key to receive a new one. Every previous key on the account is revoked at once, and the new key is shown only in this response. Your first key is created in your account at https://diddysms.com/account/api-keys.", "externalDocs": { "url": "https://diddysms.com/docs#post-v1-auth-api-key" }, "operationId": "rotate_api_key", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateApiKeyRequest", "default": { "name": "default" } } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`UNAUTHORIZED`: the API key is missing, malformed, unknown or revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`ACCOUNT_BANNED`, `ACCOUNT_FROZEN` or `ACCOUNT_MERGED`: the account behind the key cannot use the API." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The per-key rate limit for this endpoint was exceeded (limits: https://diddysms.com/docs#rate-limits). Retry after a short wait." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`MAINTENANCE`: a short maintenance; nothing was done and nothing was charged. Wait the seconds in the `Retry-After` header, then retry (https://diddysms.com/docs/errors#retries).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (sent with `MAINTENANCE`).", "schema": { "type": "integer" } } } } }, "summary": "Rotate your API key", "tags": [ "Authentication" ] } }, "/v1/balance": { "get": { "description": "Your account balance in USD.", "externalDocs": { "url": "https://diddysms.com/docs/balance#get-v1-balance" }, "operationId": "get_balance", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceResponse" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`UNAUTHORIZED`: the API key is missing, malformed, unknown or revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`ACCOUNT_BANNED`, `ACCOUNT_FROZEN` or `ACCOUNT_MERGED`: the account behind the key cannot use the API." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The per-key rate limit for this endpoint was exceeded (limits: https://diddysms.com/docs#rate-limits). Retry after a short wait." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`MAINTENANCE`: a short maintenance; nothing was done and nothing was charged. Wait the seconds in the `Retry-After` header, then retry (https://diddysms.com/docs/errors#retries).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (sent with `MAINTENANCE`).", "schema": { "type": "integer" } } } } }, "summary": "Get your balance", "tags": [ "Account" ] } }, "/v1/orders": { "get": { "description": "Your orders, newest first, paged with `limit` and `offset`. Pass `status=active` for only the orders still waiting for a code; that list is returned whole and ignores `limit` and `offset`.", "externalDocs": { "url": "https://diddysms.com/docs/orders#get-v1-orders" }, "operationId": "list_orders", "parameters": [ { "description": "Filter by status: 'active' or omit for all", "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "const": "active", "type": "string" }, { "type": "null" } ], "description": "Filter by status: 'active' or omit for all", "title": "Status" } }, { "description": "Max results", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Max results", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Results offset", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "description": "Results offset", "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrdersListResponse" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`UNAUTHORIZED`: the API key is missing, malformed, unknown or revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`ACCOUNT_BANNED`, `ACCOUNT_FROZEN` or `ACCOUNT_MERGED`: the account behind the key cannot use the API." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The per-key rate limit for this endpoint was exceeded (limits: https://diddysms.com/docs#rate-limits). Retry after a short wait." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`MAINTENANCE`: a short maintenance; nothing was done and nothing was charged. Wait the seconds in the `Retry-After` header, then retry (https://diddysms.com/docs/errors#retries).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (sent with `MAINTENANCE`).", "schema": { "type": "integer" } } } } }, "summary": "List orders", "tags": [ "Orders" ] }, "post": { "description": "Rent a US phone number for one service. The price is charged to your balance and the order starts `active`. Poll GET /v1/orders/{order_id} until `sms_code` is set. No code arrives after `expires_at`; an order with no code becomes `expired` and its price is credited back to your balance, at `expires_at` or, for a service whose code window is shorter than most, a few minutes later. When you stop waiting for a code, cancel the order rather than letting it expire. Every number is on AT&T or T-Mobile: omit `carrier` to get whichever is available, or choose one (`at&t` or `tmobile`) for about 20% more and get exactly that carrier. If it has no numbers the order is refused (409, nothing charged), or, with `carrier_fallback: \"any\"`, bought on whichever carrier is available, at the normal price.", "externalDocs": { "url": "https://diddysms.com/docs/orders#post-v1-orders" }, "operationId": "create_order", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderWrapper" } } }, "description": "Successful Response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`ORDER_ERROR`: the purchase was rejected; the message says why. Any charge is credited back automatically." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`UNAUTHORIZED`: the API key is missing, malformed, unknown or revoked." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`INSUFFICIENT_BALANCE`: your balance is too low for this purchase." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`ACCOUNT_BANNED`, `ACCOUNT_FROZEN` or `ACCOUNT_MERGED`: the account behind the key cannot use the API." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`NOT_FOUND`: there is no service with this name." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`OUT_OF_STOCK`: no numbers are left right now. `scope` is `carrier` when only the chosen carrier has none (retry without `carrier`, or send `carrier_fallback: \"any\"`) and `service` when the service has none. Nothing is charged." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ApiError" }, { "$ref": "#/components/schemas/RateLimitError" } ], "title": "Response 429 Create Order" } } }, "description": "`MAX_RENTALS`: the account already has the maximum number of concurrent active rentals; wait for one to complete or expire, or cancel one. A 429 whose body is `{\"error\": \"Rate limit exceeded: ...\"}`, with no error code, means the per-key rate limit was exceeded instead." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`SERVICE_UNAVAILABLE`: a number could not be rented right now. Retry after a few seconds. `MAINTENANCE`: a short maintenance; nothing was done and nothing was charged. Wait the seconds in the `Retry-After` header, then retry (https://diddysms.com/docs/errors#retries).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (sent with `MAINTENANCE`).", "schema": { "type": "integer" } } } } }, "summary": "Rent a number", "tags": [ "Orders" ] } }, "/v1/orders/{order_id}": { "get": { "description": "One order, including `sms_code` once the code arrives. The order updates as soon as a message arrives, so poll this endpoint every 3 seconds and stop when `status` is no longer `active`. `sms_message` is the full SMS text and `messages` lists every SMS on the order; texts are kept 30 days. `followup_codes` is present only on an order that received more codes after it completed.", "externalDocs": { "url": "https://diddysms.com/docs/orders#get-v1-orders-order-id" }, "operationId": "get_order", "parameters": [ { "description": "The order `id`.", "in": "path", "name": "order_id", "required": true, "schema": { "description": "The order `id`.", "title": "Order Id", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderWrapper" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`UNAUTHORIZED`: the API key is missing, malformed, unknown or revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`ACCOUNT_BANNED`, `ACCOUNT_FROZEN` or `ACCOUNT_MERGED`: the account behind the key cannot use the API." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`NOT_FOUND`: there is no order with this ID on your account." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The per-key rate limit for this endpoint was exceeded (limits: https://diddysms.com/docs#rate-limits). Retry after a short wait." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`MAINTENANCE`: a short maintenance; nothing was done and nothing was charged. Wait the seconds in the `Retry-After` header, then retry (https://diddysms.com/docs/errors#retries).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (sent with `MAINTENANCE`).", "schema": { "type": "integer" } } } } }, "summary": "Get an order", "tags": [ "Orders" ] } }, "/v1/orders/{order_id}/cancel": { "post": { "description": "Cancel an active order and get its price credited back to your balance. An order can be cancelled from 60 seconds after purchase. Recommended whenever you stop waiting for a code: the credit is immediate and the order stops counting toward your active rentals. If the SMS code arrives while you cancel, the order completes instead: the answer is 400 `ORDER_ERROR` and the order is charged like any order that got its code. Fetch the order to read `sms_code`.", "externalDocs": { "url": "https://diddysms.com/docs/orders#post-v1-orders-order-id-cancel" }, "operationId": "cancel_order", "parameters": [ { "description": "The order `id`.", "in": "path", "name": "order_id", "required": true, "schema": { "description": "The order `id`.", "title": "Order Id", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderWrapper" } } }, "description": "Successful Response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`COOLDOWN`: the order is less than 60 seconds old; the message says how long to wait. `ORDER_ERROR`: the order is no longer active, or its SMS code arrived first and the order completed with it." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`UNAUTHORIZED`: the API key is missing, malformed, unknown or revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`ACCOUNT_BANNED`, `ACCOUNT_FROZEN` or `ACCOUNT_MERGED`: the account behind the key cannot use the API." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`NOT_FOUND`: there is no order with this ID on your account." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The per-key rate limit for this endpoint was exceeded (limits: https://diddysms.com/docs#rate-limits). Retry after a short wait." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`SERVICE_UNAVAILABLE`: the order could not be cancelled right now. Retry after a few seconds. `MAINTENANCE`: a short maintenance; nothing was done and nothing was charged. Wait the seconds in the `Retry-After` header, then retry (https://diddysms.com/docs/errors#retries).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (sent with `MAINTENANCE`).", "schema": { "type": "integer" } } } } }, "summary": "Cancel an order", "tags": [ "Orders" ] } }, "/v1/orders/{order_id}/complete": { "post": { "description": "Check an active order for its SMS code right away. If the code has arrived, the order comes back `completed` with `sms_code` and `completed_at` set; if not, it comes back unchanged and still `active`. Orders complete on their own as soon as the code arrives, so polling GET /v1/orders/{order_id} is enough; call this only to force an immediate check.", "externalDocs": { "url": "https://diddysms.com/docs/orders#post-v1-orders-order-id-complete" }, "operationId": "complete_order", "parameters": [ { "description": "The order `id`.", "in": "path", "name": "order_id", "required": true, "schema": { "description": "The order `id`.", "title": "Order Id", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderWrapper" } } }, "description": "Successful Response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`ORDER_ERROR`: the order is no longer active (already completed, cancelled or expired)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`UNAUTHORIZED`: the API key is missing, malformed, unknown or revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`ACCOUNT_BANNED`, `ACCOUNT_FROZEN` or `ACCOUNT_MERGED`: the account behind the key cannot use the API." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`NOT_FOUND`: there is no order with this ID on your account." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The per-key rate limit for this endpoint was exceeded (limits: https://diddysms.com/docs#rate-limits). Retry after a short wait." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`SERVICE_UNAVAILABLE`: the order could not be checked right now. Retry after a few seconds. `MAINTENANCE`: a short maintenance; nothing was done and nothing was charged. Wait the seconds in the `Retry-After` header, then retry (https://diddysms.com/docs/errors#retries).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (sent with `MAINTENANCE`).", "schema": { "type": "integer" } } } } }, "summary": "Check an order for its code now", "tags": [ "Orders" ] } }, "/v1/orders/{order_id}/re-rent": { "post": { "description": "Rent the phone number of a previous order again, for example to receive another code on it. This creates a new order, with a new ID and the same phone number, charged to your balance.", "externalDocs": { "url": "https://diddysms.com/docs/orders#post-v1-orders-order-id-re-rent" }, "operationId": "re_rent_order", "parameters": [ { "description": "The order `id`.", "in": "path", "name": "order_id", "required": true, "schema": { "description": "The order `id`.", "title": "Order Id", "type": "integer" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderWrapper" } } }, "description": "Successful Response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`ORDER_ERROR`: this order cannot be re-rented; the message says why." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`UNAUTHORIZED`: the API key is missing, malformed, unknown or revoked." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`INSUFFICIENT_BALANCE`: your balance is too low for this purchase." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`ACCOUNT_BANNED`, `ACCOUNT_FROZEN` or `ACCOUNT_MERGED`: the account behind the key cannot use the API." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`NOT_FOUND`: there is no order with this ID on your account." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`OUT_OF_STOCK`: that number can't be rented again right now. Any charge is credited back automatically; rent a new number instead." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ApiError" }, { "$ref": "#/components/schemas/RateLimitError" } ], "title": "Response 429 Re Rent Order" } } }, "description": "`MAX_RENTALS`: the account already has the maximum number of concurrent active rentals; wait for one to complete or expire, or cancel one. A 429 whose body is `{\"error\": \"Rate limit exceeded: ...\"}`, with no error code, means the per-key rate limit was exceeded instead." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`SERVICE_UNAVAILABLE`: the number could not be rented again right now. Retry after a few seconds. `MAINTENANCE`: a short maintenance; nothing was done and nothing was charged. Wait the seconds in the `Retry-After` header, then retry (https://diddysms.com/docs/errors#retries).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (sent with `MAINTENANCE`).", "schema": { "type": "integer" } } } } }, "summary": "Rent the same number again", "tags": [ "Orders" ] } }, "/v1/services": { "get": { "description": "Paginated list of the services you can rent a US number for, with the price, carrier price, stock and code window (`code_window_seconds`) of each. A service that is out of stock stays in the list with `stock` 0. Pass a service's `name` as `service` when you create an order.", "externalDocs": { "url": "https://diddysms.com/docs/services#get-v1-services" }, "operationId": "list_services", "parameters": [ { "description": "Search by service name", "in": "query", "name": "search", "required": false, "schema": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "description": "Search by service name", "title": "Search" } }, { "description": "Page number", "in": "query", "name": "page", "required": false, "schema": { "default": 1, "description": "Page number", "minimum": 1, "title": "Page", "type": "integer" } }, { "description": "Results per page", "in": "query", "name": "per_page", "required": false, "schema": { "default": 20, "description": "Results per page", "maximum": 100, "minimum": 1, "title": "Per Page", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServicesListResponse" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`UNAUTHORIZED`: the API key is missing, malformed, unknown or revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`ACCOUNT_BANNED`, `ACCOUNT_FROZEN` or `ACCOUNT_MERGED`: the account behind the key cannot use the API." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The per-key rate limit for this endpoint was exceeded (limits: https://diddysms.com/docs#rate-limits). Retry after a short wait." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`SERVICE_UNAVAILABLE`: services could not be loaded right now. Retry after a few seconds. `MAINTENANCE`: a short maintenance; nothing was done and nothing was charged. Wait the seconds in the `Retry-After` header, then retry (https://diddysms.com/docs/errors#retries).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (sent with `MAINTENANCE`).", "schema": { "type": "integer" } } } } }, "summary": "List services", "tags": [ "Services" ] } }, "/v1/services/{service_name}": { "get": { "description": "The price, stock and code window of one service.", "externalDocs": { "url": "https://diddysms.com/docs/services#get-v1-services-service-name" }, "operationId": "get_service", "parameters": [ { "description": "A service `name` from GET /v1/services, e.g. `google`.", "in": "path", "name": "service_name", "required": true, "schema": { "description": "A service `name` from GET /v1/services, e.g. `google`.", "title": "Service Name", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceResponse" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`UNAUTHORIZED`: the API key is missing, malformed, unknown or revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`ACCOUNT_BANNED`, `ACCOUNT_FROZEN` or `ACCOUNT_MERGED`: the account behind the key cannot use the API." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`NOT_FOUND`: there is no service with this name." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The per-key rate limit for this endpoint was exceeded (limits: https://diddysms.com/docs#rate-limits). Retry after a short wait." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`SERVICE_UNAVAILABLE`: services could not be loaded right now. Retry after a few seconds. `MAINTENANCE`: a short maintenance; nothing was done and nothing was charged. Wait the seconds in the `Retry-After` header, then retry (https://diddysms.com/docs/errors#retries).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (sent with `MAINTENANCE`).", "schema": { "type": "integer" } } } } }, "summary": "Get a service", "tags": [ "Services" ] } }, "/v1/transactions": { "get": { "description": "Your balance history, newest first, paged with `limit` and `offset`: deposits, purchases and refunds. `amount` is negative when money leaves your balance. Other types, such as referral credits or balance adjustments, can appear; read the sign of `amount`.", "externalDocs": { "url": "https://diddysms.com/docs/balance#get-v1-transactions" }, "operationId": "list_transactions", "parameters": [ { "description": "Max results", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Max results", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Results offset", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "description": "Results offset", "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionsListResponse" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`UNAUTHORIZED`: the API key is missing, malformed, unknown or revoked." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`ACCOUNT_BANNED`, `ACCOUNT_FROZEN` or `ACCOUNT_MERGED`: the account behind the key cannot use the API." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The per-key rate limit for this endpoint was exceeded (limits: https://diddysms.com/docs#rate-limits). Retry after a short wait." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`MAINTENANCE`: a short maintenance; nothing was done and nothing was charged. Wait the seconds in the `Retry-After` header, then retry (https://diddysms.com/docs/errors#retries).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (sent with `MAINTENANCE`).", "schema": { "type": "integer" } } } } }, "summary": "List transactions", "tags": [ "Account" ] } } }, "security": [ { "ApiKey": [] } ], "servers": [ { "description": "Production", "url": "https://api.diddysms.com" } ], "tags": [ { "description": "API keys.", "externalDocs": { "url": "https://diddysms.com/docs#authentication" }, "name": "Authentication" }, { "description": "The services you can rent a number for, with price, stock and code window.", "externalDocs": { "url": "https://diddysms.com/docs/services" }, "name": "Services" }, { "description": "Rent a number, read its SMS code, cancel, complete or re-rent.", "externalDocs": { "url": "https://diddysms.com/docs/orders" }, "name": "Orders" }, { "description": "Your balance and transaction history.", "externalDocs": { "url": "https://diddysms.com/docs/balance" }, "name": "Account" } ] }