API | AirSMS API

AirSMS REST API

In addition to referred request options you can set format as json (raw response) or api (user friendly UI), default is autodetect depends on content type.

API key option is ignored if valid session cookie present (if you logged in to the site).

Get API Key

GET /api/sms/get_key/

Returns your API key.

You can request it only if logged in to the site.

Response examples

{
    "success": true,
    "key": "ieHie2hilahw0chuifex7ceu8cai7coc"
}

{
    "success": false,
    "error": "You are not allowed to use API."
}

Get Balance

GET /api/sms/get_balance/

Returns your current SMS balance.

Request options:

key (required if not authenticated)

API key.

Response examples

{
    "success": true,
    "balance": "42.00",
    "currency": "EUR"
}

Invalid API key

Get Price

GET /api/sms/get_price/

Returns the list of all available SMS services (or limited to specific service) with their properties like ID, name, price.

Request options:

key (optional)

API key. Ignored.
service_id (default: 0, recommended)

SMS service numeric ID. 0 means all.

OR

service (default: all)

SMS service full or short/corp name. Short/corp name can be used to select all services related to this corporation.

Response examples

{
    "success": true,
    "services": [
        {
            "service_id": 123,
            "service": "FooBarCorp: account verification code",
            "price": "0.93"
            "reuse_price": "0.80"
        }
    ],
    "currency": "EUR"
}

Get Number

GET /api/sms/get_number/

Reserves phone number for specific SMS service. You have 10 minutes to read SMS for this number.

Request options:

key (required if not authenticated)

API key.
service_id (required)

SMS service numeric ID.

OR

service (required)

SMS service full or short/corp name. Short/corp name can be used only if non-ambiguous (only one SMS service exists for this corporation).

The list of all available services with their IDs you can get calling Get Price endpoint.
number (optional)

Explicitly specify phone number you want to reuse. The number reuse request for specified service can be denied in some cases.

Optional leading + (plus sign) is acceptable, also these chars will be stripped from the value: + -_)(

Response examples

{
    "success": true,
    "number_request_id": 13585,
    "number": "+390123456789",
    "service_id": 13,
    "service": "BarFooCorp: any",
    "get_sms_before": "2020-08-25T00:34:46.913660Z"
}

{
    "success": false,
    "error": "Too much SMS number requests in progress (≥3).
Complete at least one of them first or wait up to 15 minutes for expiry.",
    "service_id": 13,
    "service": "BarFooCorp: any"
}

{
    "success": false,
    "error": "Insufficient funds",
    "service_id": 13,
    "service": "BarFooCorp: any",
    "price": "2.01",
    "currency": "EUR",
    "sms_balance": "2.00"
}

Ambiguous service name

Blacklist Number

GET /api/sms/blacklist_number/

Manage phone numbers blacklist. Blacklisted numbers will not appear on Get Number calls for all services (but you still can request blacklisted number reusing if specified explicitly).

Request options:

key (required if not authenticated)

API key.
number (optional for get action only)

Solo number or comma separated list of numbers for blacklisting.

Optional leading + (plus sign) is acceptable, also these chars will be stripped from the value: + -_)(
action (optional)

Supported values:
- get (default if number is not specified)
  
  Returns your current blacklist.
- add (default if number specified)
  
  Adds specified number(s) to blacklist.
- remove
  
  Removes specified number(s) from blacklist.
- add_get, remove_get
  
  Do the same as add or remove but also returns final blacklist the same way as get action.

Response examples

{
    "success": true,
}

{
    "success": true,
    "blacklist": ['+390123456788', '+390123456789'],
}

{
    "success": false,
    "error": "Failed to apply changes to blacklist",
}

Invalid "number" value

Star SMS Service

GET /api/sms/star_service/

Manage your favorite SMS services (star/unstar).

Request options:

key (required if not authenticated)

API key.
service_id (required)

SMS service numeric ID (or comma separated list of IDs).

OR

service (required)

SMS service full or short/corp name (or comma separated list of services). Short/corp name can be used only if non-ambiguous (only one SMS service exists for this corporation).

The list of all available services with their IDs you can get calling Get Price endpoint.
action (optional)

Supported values:
- get (default if service or service_id is not specified)
  
  Returns your current list of favorite services.
- add (default if service or service_id is specified)
  
  Adds specified service(s) to favorites (star).
- remove
  
  Removes specified service(s) from favorites (unstar).
- add_get, remove_get
  
  Do the same as add or remove but also returns final favorite services list the same way as get action.

Response examples

{
    "success": true,
}

{
    "success": true,
    "starred_services": [2, 5],
}

{
    "success": false,
    "error": "Failed to apply changes to starred services",
}

No such service

Get SMS

GET /api/sms/get_sms/

Returns SMS data.

Request options:

key (required if not authenticated)

API key.
sms_id (required)

SMS ID. You can set it if already known.

OR

number_request_id (required)

SMS number request ID. You get it in Get Number response.

Response examples

{
    "success": true,
    "sender": "BARFOOCORP",
    "number": "+390123456789",
    "content": "To bar your foo use: 487",
    "delivery_time": "2020-08-25T00:30:46Z",
    "read": false,
    "payload": "487",
    "service_id": 13,
    "service": "BarFooCorp: any",
    "number_request_id": 13585,
    "sms_id": 10584
}

{
    "success": false,
    "error": "This number request is expired. Try to get a new number or try to reuse the same.",
    "number_request_id": 13501,
    "number": "+390123456780"
}

{
    "success": false,
    "error": "SMS is not delivered yet. Try again a bit later."
}

No such number_request

Get SMS History

GET /api/sms/get_sms_history/

Returns your SMS history, optionally filtered by provided options.

Request options:

key (required if not authenticated)

API key.
service_id (default: 0, recommended)

SMS service numeric ID. 0 means all.

OR

service (default: any)

SMS service full or short/corp name. Short/corp name can be used to select all services related to this corporation.

The list of all available services with their IDs you can get calling Get Price endpoint.
delivery_time_from (inclusive)

delivery_time_till (exclusive)

Filter SMS by delivery time.

Can be unix time (in UTC timezone) or iso-8601.
order (default: -delivery_time)

Messages ordering.

Acceptable values: id, delivery_time, sender, number, content, payload, service, sms_number_request

The value can be prefixed with - (hyphen) to reverse order (descending).
count (default: 10, min: 1, max: 1000)

Show this number of messages at once.
page (default: 1, min: 1, max: total_pages value of the response)

Page number. Suitable if more than count messages found.

Response examples

{
    "success": true,
    "messages": [
        {
            "sender": "BARFOOCORP",
            "number": "+390123456789",
            "content": "To bar your foo use: 487",
            "delivery_time": "2020-08-25T00:30:46Z",
            "payload": "487",
            "service_id": 13,
            "service": "BarFooCorp: any",
            "number_request_id": 13585,
            "sms_id": 10584
        },
        {
            "sender": "FACEBOOK",
            "number": "+390123456780",
            "content": "25058 is John's Facebook confirmation code",
            "delivery_time": "2020-07-31T10:38:06Z",
            "payload": "25058",
            "service_id": 1,
            "service": "Facebook: account verification code",
            "number_request_id": 4322,
            "sms_id": 1234
        }
    ],
    "count": 2,
    "order": "-delivery_time",
    "page": 1,
    "total_pages": 1
}

Invalid "page" value

GET /api/sms/?format=api

HTTP 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

[
    {
        "name": "Get API Key",
        "description": "Returns your API key.\n\nYou can request it only if logged in to the site.\n\n<details>\n<summary>Response examples</summary>\n\n<pre class=\"prettyprint\">\n{\n    \"success\": true,\n    \"key\": \"ieHie2hilahw0chuifex7ceu8cai7coc\"\n}\n</pre>\n\n<pre class=\"prettyprint\">\n{\n    \"success\": false,\n    \"error\": \"You are not allowed to use API.\"\n}\n</pre>\n\n</details>",
        "url": "/api/sms/get_key/"
    },
    {
        "name": "Get Balance",
        "description": "Returns your current SMS balance.\n\n## Request options:\n\n -  ***key*** (required if not authenticated)\n\n    API key.\n\n<details>\n<summary>Response examples</summary>\n\n<pre class=\"prettyprint\">\n{\n    \"success\": true,\n    \"balance\": \"42.00\",\n    \"currency\": \"EUR\"\n}\n</pre>\n\n<pre class=\"prettyprint\">\nInvalid API key\n</pre>\n\n</details>",
        "url": "/api/sms/get_balance/"
    },
    {
        "name": "Get Price",
        "description": "Returns the list of all available SMS services (or limited to specific service) with their properties like ID, name, price.\n\n## Request options:\n\n -  *key* (optional)\n\n    API key. Ignored.\n\n -  *service_id* (default: `0`, recommended)\n\n    SMS service numeric ID. `0` means all.\n\n    OR\n\n    *service* (default: `all`)\n\n    SMS service full or short/corp name.\n    Short/corp name can be used to select all services related to this corporation.\n\n<details>\n<summary>Response examples</summary>\n\n<pre class=\"prettyprint\">\n{\n    \"success\": true,\n    \"services\": [\n        {\n            \"service_id\": 123,\n            \"service\": \"FooBarCorp: account verification code\",\n            \"price\": \"0.93\"\n            \"reuse_price\": \"0.80\"\n        }\n    ],\n    \"currency\": \"EUR\"\n}\n</pre>\n\n</details>",
        "url": "/api/sms/get_price/"
    },
    {
        "name": "Get Number",
        "description": "Reserves phone number for specific SMS service.\nYou have 10 minutes to read SMS for this number.\n\n## Request options:\n\n -  ***key*** (required if not authenticated)\n\n    API key.\n\n -  ***service_id*** (required)\n\n    SMS service numeric ID.\n\n    OR\n\n    ***service*** (required)\n\n    SMS service full or short/corp name.\n    Short/corp name can be used only if non-ambiguous (only one SMS service exists for this corporation).\n\n    The list of all available services with their IDs you can get calling [Get Price](#get-price) endpoint.\n\n -  *number* (optional)\n\n    Explicitly specify phone number you want to reuse.\n    The number reuse request for specified service can be denied in some cases.\n\n    Optional leading `+` (plus sign) is acceptable, also these chars will be stripped from the value: `+ -_)(`\n\n<details>\n<summary>Response examples</summary>\n\n<pre class=\"prettyprint\">\n{\n    \"success\": true,\n    \"number_request_id\": 13585,\n    \"number\": \"+390123456789\",\n    \"service_id\": 13,\n    \"service\": \"BarFooCorp: any\",\n    \"get_sms_before\": \"2020-08-25T00:34:46.913660Z\"\n}\n</pre>\n\n<pre class=\"prettyprint\">\n{\n    \"success\": false,\n    \"error\": \"Too much SMS number requests in progress (≥3).\nComplete at least one of them first or wait up to 15 minutes for expiry.\",\n    \"service_id\": 13,\n    \"service\": \"BarFooCorp: any\"\n}\n</pre>\n\n<pre class=\"prettyprint\">\n{\n    \"success\": false,\n    \"error\": \"Insufficient funds\",\n    \"service_id\": 13,\n    \"service\": \"BarFooCorp: any\",\n    \"price\": \"2.01\",\n    \"currency\": \"EUR\",\n    \"sms_balance\": \"2.00\"\n}\n</pre>\n\n<pre class=\"prettyprint\">\nAmbiguous service name\n</pre>\n\n</details>",
        "url": "/api/sms/get_number/"
    },
    {
        "name": "Blacklist Number",
        "description": "Manage phone numbers blacklist.\nBlacklisted numbers will not appear on [Get Number](#get-number) calls for all services (but you still can request blacklisted number reusing if specified explicitly).\n\n## Request options:\n\n -  ***key*** (required if not authenticated)\n\n    API key.\n\n -  *number* (optional for `get` action only)\n\n    Solo number or comma separated list of numbers for blacklisting.\n\n    Optional leading `+` (plus sign) is acceptable, also these chars will be stripped from the value: `+ -_)(`\n\n - *action* (optional)\n\n    Supported values:\n\n     - `get` (default if `number` is not specified)\n\n        Returns your current blacklist.\n\n     - `add` (default if `number` specified)\n\n        Adds specified number(s) to blacklist.\n\n     - `remove`\n\n        Removes specified number(s) from blacklist.\n\n     - `add_get`, `remove_get`\n\n        Do the same as `add` or `remove` but also returns final blacklist the same way as `get` action.\n\n<details>\n<summary>Response examples</summary>\n\n<pre class=\"prettyprint\">\n{\n    \"success\": true,\n}\n</pre>\n\n<pre class=\"prettyprint\">\n{\n    \"success\": true,\n    \"blacklist\": ['+390123456788', '+390123456789'],\n}\n</pre>\n\n<pre class=\"prettyprint\">\n{\n    \"success\": false,\n    \"error\": \"Failed to apply changes to blacklist\",\n}\n</pre>\n\n<pre class=\"prettyprint\">\nInvalid \"number\" value\n</pre>\n\n</details>",
        "url": "/api/sms/blacklist_number/"
    },
    {
        "name": "Star SMS Service",
        "description": "Manage your favorite SMS services (star/unstar).\n\n## Request options:\n\n -  ***key*** (required if not authenticated)\n\n    API key.\n\n -  ***service_id*** (required)\n\n    SMS service numeric ID (or comma separated list of IDs).\n\n    OR\n\n    ***service*** (required)\n\n    SMS service full or short/corp name (or comma separated list of services).\n    Short/corp name can be used only if non-ambiguous (only one SMS service exists for this corporation).\n\n    The list of all available services with their IDs you can get calling [Get Price](#get-price) endpoint.\n\n - *action* (optional)\n\n    Supported values:\n\n     - `get` (default if `service` or `service_id` is not specified)\n\n        Returns your current list of favorite services.\n\n     - `add` (default if `service` or `service_id` is specified)\n\n        Adds specified service(s) to favorites (star).\n\n     - `remove`\n\n        Removes specified service(s) from favorites (unstar).\n\n     - `add_get`, `remove_get`\n\n        Do the same as `add` or `remove` but also returns final favorite services list the same way as `get` action.\n\n<details>\n<summary>Response examples</summary>\n\n<pre class=\"prettyprint\">\n{\n    \"success\": true,\n}\n</pre>\n\n<pre class=\"prettyprint\">\n{\n    \"success\": true,\n    \"starred_services\": [2, 5],\n}\n</pre>\n\n<pre class=\"prettyprint\">\n{\n    \"success\": false,\n    \"error\": \"Failed to apply changes to starred services\",\n}\n</pre>\n\n<pre class=\"prettyprint\">\nNo such service\n</pre>\n\n</details>",
        "url": "/api/sms/star_service/"
    },
    {
        "name": "Get SMS",
        "description": "Returns SMS data.\n\n## Request options:\n\n -  ***key*** (required if not authenticated)\n\n    API key.\n\n -  ***sms_id*** (required)\n\n    SMS ID.\n    You can set it if already known.\n\n    OR\n\n    ***number_request_id*** (required)\n\n    SMS number request ID.\n    You get it in [Get Number](#get-number) response.\n\n<details>\n<summary>Response examples</summary>\n\n<pre class=\"prettyprint\">\n{\n    \"success\": true,\n    \"sender\": \"BARFOOCORP\",\n    \"number\": \"+390123456789\",\n    \"content\": \"To bar your foo use: 487\",\n    \"delivery_time\": \"2020-08-25T00:30:46Z\",\n    \"read\": false,\n    \"payload\": \"487\",\n    \"service_id\": 13,\n    \"service\": \"BarFooCorp: any\",\n    \"number_request_id\": 13585,\n    \"sms_id\": 10584\n}\n</pre>\n\n<pre class=\"prettyprint\">\n{\n    \"success\": false,\n    \"error\": \"This number request is expired. Try to get a new number or try to reuse the same.\",\n    \"number_request_id\": 13501,\n    \"number\": \"+390123456780\"\n}\n</pre>\n\n<pre class=\"prettyprint\">\n{\n    \"success\": false,\n    \"error\": \"SMS is not delivered yet. Try again a bit later.\"\n}\n</pre>\n\n<pre class=\"prettyprint\">\nNo such number_request\n</pre>\n\n</details>",
        "url": "/api/sms/get_sms/"
    },
    {
        "name": "Get SMS History",
        "description": "Returns your SMS history, optionally filtered by provided options.\n\n## Request options:\n\n -  ***key*** (required if not authenticated)\n\n    API key.\n\n -  *service_id* (default: `0`, recommended)\n\n    SMS service numeric ID. `0` means all.\n\n    OR\n\n    *service* (default: `any`)\n\n    SMS service full or short/corp name.\n    Short/corp name can be used to select all services related to this corporation.\n\n    The list of all available services with their IDs you can get calling [Get Price](#get-price) endpoint.\n\n -  *delivery_time_from* (inclusive)\n\n    *delivery_time_till* (exclusive)\n\n    Filter SMS by delivery time.\n\n    Can be unix time (in UTC timezone) or [iso-8601](https://en.wikipedia.org/wiki/ISO_8601).\n\n -  *order* (default: `-delivery_time`)\n\n    Messages ordering.\n\n    Acceptable values: id, delivery_time, sender, number, content, payload, service, sms_number_request\n\n    The value can be prefixed with `-` (hyphen) to reverse order (descending).\n\n -  *count* (default: `10`, min: `1`, max: `1000`)\n\n    Show this number of messages at once.\n\n -  *page* (default: `1`, min: `1`, max: `total_pages` value of the response)\n\n    Page number. Suitable if more than `count` messages found.\n\n<details>\n<summary>Response examples</summary>\n\n<pre class=\"prettyprint\">\n{\n    \"success\": true,\n    \"messages\": [\n        {\n            \"sender\": \"BARFOOCORP\",\n            \"number\": \"+390123456789\",\n            \"content\": \"To bar your foo use: 487\",\n            \"delivery_time\": \"2020-08-25T00:30:46Z\",\n            \"payload\": \"487\",\n            \"service_id\": 13,\n            \"service\": \"BarFooCorp: any\",\n            \"number_request_id\": 13585,\n            \"sms_id\": 10584\n        },\n        {\n            \"sender\": \"FACEBOOK\",\n            \"number\": \"+390123456780\",\n            \"content\": \"25058 is John's Facebook confirmation code\",\n            \"delivery_time\": \"2020-07-31T10:38:06Z\",\n            \"payload\": \"25058\",\n            \"service_id\": 1,\n            \"service\": \"Facebook: account verification code\",\n            \"number_request_id\": 4322,\n            \"sms_id\": 1234\n        }\n    ],\n    \"count\": 2,\n    \"order\": \"-delivery_time\",\n    \"page\": 1,\n    \"total_pages\": 1\n}\n</pre>\n\n<pre class=\"prettyprint\">\nInvalid \"page\" value\n</pre>\n\n</details>",
        "url": "/api/sms/get_sms_history/"
    }
]