{
  "openapi": "3.0.3",
  "info": {
    "title": "BudgetSMS HTTP API",
    "version": "1.0.0",
    "description": "The BudgetSMS HTTP API is a set of plain HTTPS GET endpoints. Every call carries your account credentials as query parameters (username, userid and handle, all found in the control panel) and answers with a single line of text: `OK ...` on success or `ERR <code>` on failure (see the error code list). Only the account pricing call returns JSON. Numbers are written in international format without a leading + or 00, for example 31612345678. Full documentation with examples: https://www.budgetsms.net/sms-http-api/",
    "termsOfService": "https://www.budgetsms.net/terms/",
    "contact": {"name": "BudgetSMS support", "url": "https://www.budgetsms.net/contact-us/"}
  },
  "externalDocs": {"description": "HTTP API documentation", "url": "https://www.budgetsms.net/sms-http-api/"},
  "servers": [{"url": "https://api.budgetsms.net"}],
  "security": [{"username": [], "userid": [], "handle": []}],
  "tags": [
    {"name": "SMS", "description": "Sending messages and delivery reports"},
    {"name": "Lookup", "description": "HLR and number portability lookups"},
    {"name": "Account", "description": "Credit and pricing of your account"}
  ],
  "paths": {
    "/sendsms/": {
      "get": {
        "tags": ["SMS"],
        "summary": "Send an SMS",
        "description": "Sends one SMS message. Long messages are split into parts and charged per part. Returns the smsid, optionally followed by the price and number of parts (price=1), the MCC and MNC of the destination network (mccmnc=1) and the remaining credit (credit=1), separated by spaces.",
        "externalDocs": {"url": "https://www.budgetsms.net/sms-http-api/send-sms/"},
        "parameters": [
          {"$ref": "#/components/parameters/msg"},
          {"$ref": "#/components/parameters/from"},
          {"$ref": "#/components/parameters/to"},
          {"$ref": "#/components/parameters/customid"},
          {"$ref": "#/components/parameters/price"},
          {"$ref": "#/components/parameters/mccmnc"},
          {"$ref": "#/components/parameters/credit"}
        ],
        "responses": {
          "200": {
            "description": "Always HTTP 200; the first word of the body tells success (OK) or failure (ERR).",
            "content": {
              "text/plain": {
                "schema": {"$ref": "#/components/schemas/TextResponse"},
                "examples": {
                  "accepted": {"summary": "Message accepted", "value": "OK 64354593"},
                  "withExtras": {"summary": "With price=1, mccmnc=1 and credit=1", "value": "OK 64354593 0.0450 1 20408 123.4550"},
                  "noCredit": {"summary": "Not enough credit", "value": "ERR 1001"}
                }
              }
            }
          }
        },
        "callbacks": {
          "pushDlr": {
            "{pushUrlConfiguredInTheControlPanel}": {
              "get": {
                "summary": "Push DLR: BudgetSMS calls your URL on every status update of a sent message",
                "description": "Enable Push DLR and enter your URL in the control panel. Each update is one GET request with the parameters below. Your URL may contain its own query string (https://example.com/dlr?token=abc); our parameters are appended with &. Requests come from 188.240.53.76 (IPv4) or 2a01:7c8:bb04:2c:5054:ff:fe60:d620 (IPv6) with user agent 'BudgetSMS DLRbot V2.1'; a server that cannot be reached is retried with increasing intervals for about 5.5 hours. Documentation: https://www.budgetsms.net/sms-http-api/push-dlr/",
                "parameters": [
                  {"name": "to", "in": "query", "required": true, "description": "Destination number of the message", "schema": {"type": "string", "example": "31612345678"}},
                  {"name": "id", "in": "query", "required": true, "description": "smsid from the /sendsms/ response", "schema": {"type": "integer", "example": 25745294}},
                  {"name": "customid", "in": "query", "required": false, "description": "Your own id, only when the message was sent with the customid parameter", "schema": {"type": "string", "example": "order-4821"}},
                  {"name": "status", "in": "query", "required": true, "description": "DLR status code, see DlrStatus", "schema": {"$ref": "#/components/schemas/DlrStatus"}},
                  {"name": "date", "in": "query", "required": true, "description": "Unix timestamp of the status", "schema": {"type": "integer", "example": 1484407297}}
                ],
                "responses": {"200": {"description": "An HTTP 200 response from your server acknowledges the update; any other status, or no answer within 10 seconds, leads to retries with increasing intervals for about 5.5 hours (15 attempts)."}}
              }
            }
          }
        }
      }
    },
    "/testsms/": {
      "get": {
        "tags": ["SMS"],
        "summary": "Simulate sending an SMS",
        "description": "Simulator for /sendsms/ with the same parameters and response format: checks your credentials, account and IP lockdown, then returns a random message id and a random price. No SMS is sent and no credit is deducted. About one in five calls returns a random 2xxx error so error handling can be tested. The destination number is not validated.",
        "externalDocs": {"url": "https://www.budgetsms.net/sms-http-api/test-sms/"},
        "parameters": [
          {"$ref": "#/components/parameters/msg"},
          {"$ref": "#/components/parameters/from"},
          {"$ref": "#/components/parameters/to"},
          {"$ref": "#/components/parameters/customid"},
          {"$ref": "#/components/parameters/price"},
          {"$ref": "#/components/parameters/mccmnc"},
          {"$ref": "#/components/parameters/credit"}
        ],
        "responses": {
          "200": {
            "description": "Same format as /sendsms/.",
            "content": {"text/plain": {"schema": {"$ref": "#/components/schemas/TextResponse"}, "example": "OK 64354593"}}
          }
        }
      }
    },
    "/hlr/": {
      "get": {
        "tags": ["Lookup"],
        "summary": "HLR lookup",
        "description": "Returns the network a mobile number is currently on (MCC and MNC, also for ported numbers) and whether the subscriber is reachable, plus the price of one SMS to that network for your account. Charged per request at your HLR price; a result served from the cache (cache parameter) costs half.",
        "externalDocs": {"url": "https://www.budgetsms.net/sms-http-api/hlr/"},
        "parameters": [
          {"$ref": "#/components/parameters/lookupTo"},
          {"name": "cache", "in": "query", "required": false, "description": "Accept a result looked up earlier, at most this many days old (0-7). 0 (default) forces a fresh lookup.", "schema": {"type": "integer", "minimum": 0, "maximum": 7, "default": 0}}
        ],
        "responses": {
          "200": {
            "description": "`OK <mcc> <mnc> <price>` or `ERR <code>`. ERR 4003 means the lookup failed at the provider and nothing was charged.",
            "content": {"text/plain": {"schema": {"$ref": "#/components/schemas/LookupResponse"}, "example": "OK 204 08 0.0450"}}
          }
        }
      }
    },
    "/np/": {
      "get": {
        "tags": ["Lookup"],
        "summary": "Number portability (NP) lookup",
        "description": "Returns the network a mobile number currently belongs to (MCC and MNC, also for ported numbers) and the price of one SMS to that network for your account. Cheaper than an HLR lookup and the right choice for routing, list cleaning and detecting ported numbers; it does not check whether the handset is switched on. Results are kept for 30 days and answered from the cache within that period.",
        "externalDocs": {"url": "https://www.budgetsms.net/sms-http-api/np/"},
        "parameters": [{"$ref": "#/components/parameters/lookupTo"}],
        "responses": {
          "200": {
            "description": "`OK <mcc> <mnc> <price>` or `ERR <code>`.",
            "content": {"text/plain": {"schema": {"$ref": "#/components/schemas/LookupResponse"}, "example": "OK 204 08 0.0450"}}
          }
        }
      }
    },
    "/checksms/": {
      "get": {
        "tags": ["SMS"],
        "summary": "Pull DLR: delivery status of one message",
        "description": "Returns the current delivery status of a message sent through the API. Push DLR is the preferred method; use this call for occasional checks.",
        "externalDocs": {"url": "https://www.budgetsms.net/sms-http-api/pull-dlr/"},
        "parameters": [{"name": "smsid", "in": "query", "required": true, "description": "smsid from the /sendsms/ response", "schema": {"type": "integer", "example": 64354593}}],
        "responses": {
          "200": {
            "description": "`OK <status>` with a DLR status code, or `ERR <code>` (for example ERR 2017 for an invalid smsid).",
            "content": {"text/plain": {"schema": {"$ref": "#/components/schemas/TextResponse"}, "example": "OK 1"}}
          }
        }
      }
    },
    "/checkcredit/": {
      "get": {
        "tags": ["Account"],
        "summary": "Check credit",
        "description": "Returns the current credit of the account in euro.",
        "externalDocs": {"url": "https://www.budgetsms.net/sms-http-api/check-credit/"},
        "responses": {
          "200": {
            "description": "`OK <credit>` or `ERR <code>`.",
            "content": {"text/plain": {"schema": {"$ref": "#/components/schemas/TextResponse"}, "example": "OK 123.4550"}}
          }
        }
      }
    },
    "/getpricing/": {
      "get": {
        "tags": ["Account"],
        "summary": "Account pricing",
        "description": "Returns the price per SMS part for every destination operator of your account as JSON: an object keyed by operator id. Customer-specific prices override the default prices.",
        "externalDocs": {"url": "https://www.budgetsms.net/sms-http-api/account-pricing/"},
        "responses": {
          "200": {
            "description": "JSON object keyed by operator id, or the text `ERR <code>` when the credentials are wrong.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": {"$ref": "#/components/schemas/OperatorPrice"},
                  "example": {"6": {"countryprefix": 31, "countryname": "Netherlands", "mcc": 204, "operatorname": "KPN", "mnc": "08", "price": "0.06400", "old_price": "", "last_modified": "2026-09-03 11:24:03"}}
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "username": {"type": "apiKey", "in": "query", "name": "username", "description": "Your BudgetSMS username"},
      "userid": {"type": "apiKey", "in": "query", "name": "userid", "description": "Your numeric BudgetSMS user id"},
      "handle": {"type": "apiKey", "in": "query", "name": "handle", "description": "Your API handle from the control panel"}
    },
    "parameters": {
      "msg": {"name": "msg", "in": "query", "required": true, "description": "Message text, UTF-8 (URL-encoded). Longer texts are split into several parts and charged per part.", "schema": {"type": "string", "example": "This is example content"}},
      "from": {"name": "from", "in": "query", "required": true, "description": "Sender id: alphanumeric (max 11 characters) or numeric (max 16 digits). Some countries restrict or register alphanumeric senders; see the country pages.", "schema": {"type": "string", "example": "BudgetSMS"}},
      "to": {"name": "to", "in": "query", "required": true, "description": "Receiver in international format (E.164 digits only): country code followed by the number without the leading 0, no + or 00, no spaces.", "schema": {"type": "string", "pattern": "^[1-9][0-9]{5,15}$", "example": "31612345678"}},
      "lookupTo": {"name": "to", "in": "query", "required": true, "description": "Mobile number to look up, international format, digits only.", "schema": {"type": "string", "pattern": "^[1-9][0-9]{5,15}$", "example": "31612345678"}},
      "customid": {"name": "customid", "in": "query", "required": false, "description": "Your own identifier that may be used only once per account; a second message with the same customid is refused with ERR 2014. Only for de-duplication.", "schema": {"type": "string", "example": "1324513254"}},
      "price": {"name": "price", "in": "query", "required": false, "description": "1 = add the total price and the number of SMS parts to the response", "schema": {"type": "integer", "enum": [0, 1], "default": 0}},
      "mccmnc": {"name": "mccmnc", "in": "query", "required": false, "description": "1 = add the MCC and MNC of the destination network (the actual operator for ported numbers) to the response", "schema": {"type": "integer", "enum": [0, 1], "default": 0}},
      "credit": {"name": "credit", "in": "query", "required": false, "description": "1 = add the remaining credit of the account to the response", "schema": {"type": "integer", "enum": [0, 1], "default": 0}}
    },
    "schemas": {
      "TextResponse": {
        "type": "string",
        "description": "One line: `OK` followed by space-separated values, or `ERR <code>`. Error codes: 1001 not enough credit, 1002 wrong credentials, 1003 account not active, 1004 IP address not allowed for this account, 1005 no handle, 1006 no userid, 1007 no username, 2001 message text empty, 2002 numeric sender id longer than 16 digits, 2003 alphanumeric sender id longer than 11 characters, 2004 sender id empty or invalid, 2005 destination too short, 2006 destination not numeric, 2007 destination empty, 2008 message text not OK (encoding), 2009 parameter issue, 2010 destination formatted invalidly, 2011 destination invalid, 2012 message text too long, 2013 message invalid, 2014 customid used before, 2015 charset problem, 2016 invalid UTF-8, 2017 invalid smsid, 3001 no route to destination, 3002 no routes set up, 3003 invalid destination (check international formatting), 4001 system error related to customid, 4002 temporary system error (retry in 2-3 minutes), 4003 HLR/NP lookup failed at the carrier (nothing charged), 4004 temporary system error (contact BudgetSMS), 4005 permanent system error, 4006 gateway not reachable, 4007 system error (contact BudgetSMS), 5001 send error, 5002 wrong SMS type, 5003 wrong operator, 6001 unknown error, 7001 no HLR provider present, 7002 unexpected result from HLR provider, 7003 bad number format, 7901-7903 HLR provider errors. Full list: https://www.budgetsms.net/sms-http-api/error-code/",
        "pattern": "^(OK( \\S+)*|ERR [0-9]{4})$"
      },
      "LookupResponse": {
        "type": "string",
        "description": "`OK <mcc> <mnc> <price>`: mobile country code and mobile network code of the network the subscriber is currently on, and the price of one SMS to that network for your account. Or `ERR <code>`.",
        "pattern": "^(OK [0-9]{3} [0-9]{1,3} [0-9]+\\.[0-9]+|ERR [0-9]{4})$"
      },
      "DlrStatus": {
        "type": "integer",
        "enum": [0, 1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 13],
        "description": "0 sent, no status yet (default); 1 delivered; 2 not sent; 3 delivery failed; 4 sent; 5 expired; 6 invalid destination address; 7 SMSC error, message could not be processed; 8 message not allowed; 11 status unknown, usually after 24 hours without update from the SMSC; 12 status unknown, SMSC returned an unknown status code; 13 status unknown, no update from the SMSC after 72 hours. Documentation: https://www.budgetsms.net/sms-http-api/dlr-status/"
      },
      "OperatorPrice": {
        "type": "object",
        "description": "Price of one SMS part to one destination operator. Types as delivered by the API: countryprefix and mcc are numbers, the other values strings.",
        "properties": {
          "countryprefix": {"type": "integer", "description": "International dialling code", "example": 31},
          "countryname": {"type": "string", "example": "Netherlands"},
          "mcc": {"type": "integer", "description": "Mobile country code", "example": 204},
          "operatorname": {"type": "string", "example": "KPN"},
          "mnc": {"type": "string", "description": "Mobile network code", "example": "08"},
          "price": {"type": "string", "description": "Price per SMS part in euro", "example": "0.06400"},
          "old_price": {"type": "string", "description": "Previous price, empty when there was none", "example": ""},
          "last_modified": {"type": "string", "description": "When the price last changed (server time), empty when unknown", "example": "2026-09-03 11:24:03"}
        }
      }
    }
  }
}
