# sms4sats API Documentation Instructions on how to use [sms4sats.com](https://sms4sats.com) API to generate sms activation code orders from anywhere, pay with Lightning Bitcoin and receive the activation codes. **Contact** Telegram: [pseudozach](https://t.me/pseudozach) or Email: Twitter: #### Node Info Feel free to open a direct channel to our node if you have trouble with routing or let us know and we're happy to open balanced channels to high volume partners. {% embed url="" %} sms4sats Lightning Node {% endembed %} ### Postman You can easily run the API in postman to understand the parameters and responses by clicking below. [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/92744-f0d90622-bd11-46c2-88d9-8a28c4659c14?action=collection%2Ffork\&collection-url=entityId%3D92744-f0d90622-bd11-46c2-88d9-8a28c4659c14%26entityType%3Dcollection%26workspaceId%3D1b640623-2040-457e-a2b5-a901b273ff18) ### API info API root is at: . You can also use this endpoint to check for availability. {% hint style="warning" %} You may need to use below country code list to map country names into country codes and send this code in certain queries. Normally, API should work with inputs such as country="germany". {% endhint %}
Country Code List {% code overflow="wrap" %} ```json const countrymap = [ { "cc": 999, "country": "Auto-Select" }, { "cc": 0, "country": "Russia" }, { "cc": 0, "country": "Russian" }, { "cc": 1, "country": "Ukraine" }, { "cc": 2, "country": "Kazakhstan" }, { "cc": 3, "country": "China" }, { "cc": 4, "country": "Philippines" }, { "cc": 5, "country": "Myanmar" }, { "cc": 6, "country": "Indonesia" }, { "cc": 7, "country": "Malaysia" }, { "cc": 8, "country": "Kenya" }, { "cc": 9, "country": "Tanzania" }, { "cc": 10, "country": "Vietnam" }, { "cc": 11, "country": "Kyrgyzstan" }, { "cc": 12, "country": "USA (virtual)" }, { "cc": 13, "country": "Israel" }, { "cc": 14, "country": "HongKong" }, { "cc": 15, "country": "Poland" }, { "cc": 16, "country": "England" }, { "cc": 16, "country": "United Kingdom" }, { "cc": 18, "country": "DCongo" }, { "cc": 19, "country": "Nigeria" }, { "cc": 20, "country": "Macao" }, { "cc": 21, "country": "Egypt" }, { "cc": 22, "country": "India" }, { "cc": 23, "country": "Ireland" }, { "cc": 24, "country": "Cambodia" }, { "cc": 25, "country": "Laos" }, { "cc": 26, "country": "Haiti" }, { "cc": 27, "country": "Ivory" }, { "cc": 28, "country": "Gambia" }, { "cc": 29, "country": "Serbia" }, { "cc": 30, "country": "Yemen" }, { "cc": 31, "country": "Southafrica" }, { "cc": 32, "country": "Romania" }, { "cc": 33, "country": "Colombia" }, { "cc": 34, "country": "Estonia" }, { "cc": 36, "country": "Canada" }, { "cc": 37, "country": "Morocco" }, { "cc": 38, "country": "Ghana" }, { "cc": 39, "country": "Argentina" }, { "cc": 40, "country": "Uzbekistan" }, { "cc": 41, "country": "Cameroon" }, { "cc": 42, "country": "Chad" }, { "cc": 43, "country": "Germany" }, { "cc": 44, "country": "Lithuania" }, { "cc": 45, "country": "Croatia" }, { "cc": 46, "country": "Sweden" }, { "cc": 47, "country": "Iraq" }, { "cc": 48, "country": "Netherlands" }, { "cc": 49, "country": "Latvia" }, { "cc": 50, "country": "Austria" }, { "cc": 51, "country": "Belarus" }, { "cc": 52, "country": "Thailand" }, { "cc": 53, "country": "Saudiarabia" }, { "cc": 54, "country": "Mexico" }, { "cc": 55, "country": "Taiwan" }, { "cc": 56, "country": "Spain" }, { "cc": 58, "country": "Algeria" }, { "cc": 59, "country": "Slovenia" }, { "cc": 60, "country": "Bangladesh" }, { "cc": 61, "country": "Senegal" }, { "cc": 62, "country": "Turkey" }, { "cc": 63, "country": "Czech" }, { "cc": 64, "country": "Srilanka" }, { "cc": 65, "country": "Peru" }, { "cc": 66, "country": "Pakistan" }, { "cc": 67, "country": "Newzealand" }, { "cc": 68, "country": "Guinea" }, { "cc": 69, "country": "Mali" }, { "cc": 70, "country": "Venezuela" }, { "cc": 71, "country": "Ethiopia" }, { "cc": 72, "country": "Mongolia" }, { "cc": 73, "country": "Brazil" }, { "cc": 74, "country": "Afghanistan" }, { "cc": 75, "country": "Uganda" }, { "cc": 76, "country": "Angola" }, { "cc": 77, "country": "Cyprus" }, { "cc": 78, "country": "France" }, { "cc": 79, "country": "Papua" }, { "cc": 80, "country": "Mozambique" }, { "cc": 81, "country": "Nepal" }, { "cc": 82, "country": "Belgium" }, { "cc": 83, "country": "Bulgaria" }, { "cc": 84, "country": "Hungary" }, { "cc": 85, "country": "Moldova" }, { "cc": 86, "country": "Italy" }, { "cc": 87, "country": "Paraguay" }, { "cc": 88, "country": "Honduras" }, { "cc": 89, "country": "Tunisia" }, { "cc": 90, "country": "Nicaragua" }, { "cc": 91, "country": "Timorleste" }, { "cc": 92, "country": "Bolivia" }, { "cc": 93, "country": "Costarica" }, { "cc": 94, "country": "Guatemala" }, { "cc": 95, "country": "Uae" }, { "cc": 96, "country": "Zimbabwe" }, { "cc": 97, "country": "Puertorico" }, { "cc": 99, "country": "Togo" }, { "cc": 100, "country": "Kuwait" }, { "cc": 101, "country": "Salvador" }, { "cc": 102, "country": "Libyan" }, { "cc": 103, "country": "Jamaica" }, { "cc": 104, "country": "Trinidad" }, { "cc": 105, "country": "Ecuador" }, { "cc": 106, "country": "Swaziland" }, { "cc": 107, "country": "Oman" }, { "cc": 108, "country": "Bosnia" }, { "cc": 109, "country": "Dominican" }, { "cc": 111, "country": "Qatar" }, { "cc": 112, "country": "Panama" }, { "cc": 114, "country": "Mauritania" }, { "cc": 115, "country": "Sierraleone" }, { "cc": 116, "country": "Jordan" }, { "cc": 117, "country": "Portugal" }, { "cc": 118, "country": "Barbados" }, { "cc": 119, "country": "Burundi" }, { "cc": 120, "country": "Benin" }, { "cc": 121, "country": "Brunei" }, { "cc": 122, "country": "Bahamas" }, { "cc": 123, "country": "Botswana" }, { "cc": 124, "country": "Belize" }, { "cc": 125, "country": "Caf" }, { "cc": 126, "country": "Dominica" }, { "cc": 127, "country": "Grenada" }, { "cc": 128, "country": "Georgia" }, { "cc": 129, "country": "Greece" }, { "cc": 130, "country": "Guineabissau" }, { "cc": 131, "country": "Guyana" }, { "cc": 132, "country": "Iceland" }, { "cc": 133, "country": "Comoros" }, { "cc": 134, "country": "Saintkitts" }, { "cc": 135, "country": "Liberia" }, { "cc": 136, "country": "Lesotho" }, { "cc": 137, "country": "Malawi" }, { "cc": 138, "country": "Namibia" }, { "cc": 139, "country": "Niger" }, { "cc": 140, "country": "Rwanda" }, { "cc": 141, "country": "Slovakia" }, { "cc": 142, "country": "Suriname" }, { "cc": 143, "country": "Tajikistan" }, { "cc": 144, "country": "Monaco" }, { "cc": 145, "country": "Bahrain" }, { "cc": 146, "country": "Reunion" }, { "cc": 147, "country": "Zambia" }, { "cc": 148, "country": "Armenia" }, { "cc": 149, "country": "Somalia" }, { "cc": 150, "country": "Congo" }, { "cc": 151, "country": "Chile" }, { "cc": 152, "country": "Furkinafaso" }, { "cc": 153, "country": "Lebanon" }, { "cc": 154, "country": "Gabon" }, { "cc": 155, "country": "Albania" }, { "cc": 156, "country": "Uruguay" }, { "cc": 157, "country": "Mauritius" }, { "cc": 158, "country": "Bhutan" }, { "cc": 159, "country": "Maldives" }, { "cc": 160, "country": "Guadeloupe" }, { "cc": 161, "country": "Turkmenistan" }, { "cc": 162, "country": "Frenchguiana" }, { "cc": 163, "country": "Finland" }, { "cc": 164, "country": "Saintlucia" }, { "cc": 165, "country": "Luxembourg" }, { "cc": 166, "country": "Saintvincentgrenadines" }, { "cc": 167, "country": "Equatorialguinea" }, { "cc": 168, "country": "Djibouti" }, { "cc": 169, "country": "Antiguabarbuda" }, { "cc": 170, "country": "Caymanislands" }, { "cc": 171, "country": "Montenegro" }, { "cc": 173, "country": "Switzerland" }, { "cc": 174, "country": "Norway" }, { "cc": 175, "country": "Australia" }, { "cc": 176, "country": "Eritrea" }, { "cc": 177, "country": "Southsudan" }, { "cc": 178, "country": "Saotomeandprincipe" }, { "cc": 179, "country": "Aruba" }, { "cc": 180, "country": "Montserrat" }, { "cc": 181, "country": "Anguilla" }, { "cc": 183, "country": "Northmacedonia" }, { "cc": 184, "country": "Seychelles" }, { "cc": 185, "country": "Newcaledonia" }, { "cc": 186, "country": "Capeverde" }, { "cc": 187, "country": "USA" }, { "cc": 187, "country": "United States" }, { "cc": 187, "country": "United States of America" }, { "cc": 189, "country": "Fiji" }, { "cc": 190, "country": "Southkorea" }, { "cc": 195, "country": "Bermuda" }, { "cc": 196, "country": "Singapore" } ]; ``` {% endcode %}
### Getting Prices Use this endpoint to check the price (in satoshis) that user will need to pay to use services offered by this API. ## Get Receive/Send/Rent Price (in satoshis) `GET` `https://api2.sms4sats.com/price` Note that at the moment, receive and send prices are static but this may change in the future. Rent price will vary based on country. #### Query Parameters | Name | Type | Description | | ------- | ------ | ----------- | | country | Number | | | service | String | | {% tabs %} {% tab title="200: OK " %} ```javascript { receive: 3000, //standard sms activation code price send: 1000, // standard sms send price rent: 15000, // minimum phone rental price (receive unlimited sms for 4 hours) s4s: 5000, // real phone numbers part of sms4sats network } ``` {% endtab %} {% endtabs %} ### Getting Available Services Use this endpoint to check for available numbers to **receive** activation codes for each offered service for a specific country. ## Get Available Services `GET` `https://api2.sms4sats.com/getnumbersstatus` Get an array of available services that can be ordered for a country. #### Query Parameters | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------- | | country\* | Number | Country Code (e.g. 187 for USA) | {% tabs %} {% tab title="200: OK " %} {% code overflow="wrap" %} ```javascript [ { "key": "vk", "text": "vk.com", "value": "vk", "count": "28", "image": { "avatar": true, "src": "/assets/saimages/vk0.png" } }, ... ] ``` {% endcode %} {% endtab %} {% endtabs %} ### Creating a Receive Order Use this endpoint to create a **receive SMS** order for a specific country and service. ## Create Receive Order `POST` `https://api2.sms4sats.com/createorder` Create an sms4sats order to be fulfilled. #### Request Body | Name | Type | Description | | ----------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | country\* | Number | Country Code (e.g. 187 for USA) | | service\* | String |

Short Code (e.g. vk for vk.com)

Refer to `value` field in response from#getting-available-services

| | isRental | Boolean | set to true if this is for a phone number rental order | | realphone | Boolean | set to true if this is for a real phone number that is part of sms4sats network | | ref | String | A valid [lightning address](https://lightningaddress.com) where you want to receive Referral Payments for the order. (Currently %10) | | immediate | Boolean | Set to **true** if you want to deduct the cost of receive from your API Key balance. | {% tabs %} {% tab title="200: OK " %} {% code overflow="wrap" %} ```javascript { status: 'OK', orderId: '7dc6e6b61d8c54dff6b8d6ea2e3f08b018e57963df81d493a6f9728c4dc83318', payreq: 'lnbc30u1p34yef6pp50hrwddsa332dla4c6m4zu0cgkqvw27trm7qafyaxl9egcnwgxvvqdp5wdkhxdrnv968xgrsv9uk6etwwssywetjd4sku7fqw3mkjar5v4eqcqzpgxqyz5vqsp5fnj032qs6fuht2p3r245h3u6r9x32fhdw5n4qyn7mqm95jt0ag5q9qyyssqlyeyhnqq4y6l5ynxatvnqg6zldnqmwxx7qel0q79slfv7wvuk23zm2shczj4vxf39a4s8x36k9dxcgtnvwdv0j8uq4jcuq3yclw393sp8uywdc' } ``` {% endcode %} {% endtab %} {% tab title="500: Internal Server Error " %} ```javascript { status: 'error', reason: 'unable to save data' } ``` {% endtab %} {% endtabs %} {% hint style="success" %} sms4sats uses [hold invoices](https://bolt.fun/guide/invoices/hodl-invoice) for payment, this means: * When invoice is paid by the user, it's not finalized but *HELD* by the sms4sats Lightning Node. * For ***receive*** orders, Only when an activation code is successfully received the invoice is *SETTLED*. * For ***send*** orders, Only when SMS status is "sent or delivered" the invoice is *SETTLED*. * If no code is received within 20 minutes, invoice will be *CANCELED* and funds will automatically return to user's wallet. {% endhint %} ### Getting Order Status Use this endpoint to check the status of an order ## Get Order Status `GET` `https://api2.sms4sats.com/orderstatus` Check an sms4sats order status. #### Query Parameters | Name | Type | Description | | ----------------------------------------- | ------ | --------------------------------------------------------------------------- | | orderId\* | String | Order ID returned by the \`/createorder\` or \`/createsendorder\` endpoint | {% tabs %} {% tab title="200: OK Normal Response for Receive Orders" %} {% code overflow="wrap" %} ```javascript { status: 'OK', paid: true, code: 48010, id: 1125699791, number: 12345678901, timestamp: 1666613406969, country: 'India', service: 'openAI', } ``` {% endcode %} {% endtab %} {% tab title="500: Internal Server Error Server side error" %} ```javascript { status: 'error', reason: 'unable to save data' } ``` {% endtab %} {% tab title="200: OK Error Getting a Phone Number or Code" %} ```javascript { status: 'OK', paid: true, error: 'No available number, payment request is canceled. Your funds are returned to your wallet automatically.' } ``` {% endtab %} {% tab title="200: OK Normal Response for Send Orders" %} ```javascript { status: 'OK', paid: true, id: 'SMfa2be998e8913565cbbd5f750e32b1b5', smsStatus: 'created | sent | delivered | failed', timestamp: 1666613406969, } ``` {% endtab %} {% endtabs %} ### Canceling a Receive Order Use this endpoint to cancel a receive order after 2 minutes in case no sms is received. Note: **all orders without a code will be automatically canceled after 21 minutes**. ## Cancel Order `GET` `https://api2.sms4sats.com/cancelorder` Cancel an sms4sats order and the hold invoice related to it. #### Query Parameters | Name | Type | Description | | ----------------------------------------- | ------ | -------------------------------------------------- | | orderId\* | String | Order ID returned by the \`/createorder\` endpoint | {% tabs %} {% tab title="200: OK Normal Response for Receive Orders" %} {% code overflow="wrap" %} ```javascript { status: 'OK' } ``` {% endcode %} {% endtab %} {% tab title="500: Internal Server Error Server side error" %} ```javascript { status: 'error', reason: 'unable to save data' } ``` {% endtab %} {% endtabs %} ### Creating SMS Send Order Use this endpoint to create a **send SMS** order for a phone number and message. ## Create SMS Send Order `POST` `https://api2.sms4sats.com/createsendorder` Create an sms4sats order to send an SMS message to a phone number. #### Headers | Name | Type | Description | | --------- | ------ | -------------------------------------------------------------------------------------------- | | X-API-Key | String | Optional API Key to use if you want to use a pre-funded account to immediately send the SMS. | #### Request Body | Name | Type | Description | | ----------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | message\* | String |

Message text that you want to send to the phone number.

Max 140 characters.

| | phone\* | String | A valid [E.164](https://en.wikipedia.org/wiki/E.164) phone number (e.g. +19871234567) | | immediate | Boolean | Set to **true** if you want to immediately send the SMS and deduct the cost from your API Key balance. | | webhookUrl | String |

Webhook URL where you want to receive order updates.

Same data as /orderstatus will be sent as POST to this URL.

| {% tabs %} {% tab title="200: OK Response for creating a send order" %} {% code overflow="wrap" %} ```javascript { status: 'OK', orderId: '7dc6e6b61d8c54dff6b8d6ea2e3f08b018e57963df81d493a6f9728c4dc83318', payreq: 'lnbc30u1p34yef6pp50hrwddsa332dla4c6m4zu0cgkqvw27trm7qafyaxl9egcnwgxvvqdp5wdkhxdrnv968xgrsv9uk6etwwssywetjd4sku7fqw3mkjar5v4eqcqzpgxqyz5vqsp5fnj032qs6fuht2p3r245h3u6r9x32fhdw5n4qyn7mqm95jt0ag5q9qyyssqlyeyhnqq4y6l5ynxatvnqg6zldnqmwxx7qel0q79slfv7wvuk23zm2shczj4vxf39a4s8x36k9dxcgtnvwdv0j8uq4jcuq3yclw393sp8uywdc | paid' } ``` {% endcode %} {% endtab %} {% tab title="500: Internal Server Error " %} ```javascript { status: 'error', reason: 'backend error' } ``` {% endtab %} {% endtabs %} ### Creating Email Send Order Use this endpoint to create a **send Email** order for an email address and message. ## Create Email Send Order `POST` `https://api2.sms4sats.com/createemailsendorder` Create an sms4sats order to send an Email message to an email address. #### Headers
NameTypeDescription
X-API-KeyStringOptional API Key to use if you want to use a pre-funded account to immediately send the SMS.
#### Request Body
NameTypeDescription
message*String

Message text that you want to send to the phone number.

Max 140 characters.

address*StringA valid email address
(e.g. pseudonym@protonmail.com)
immediateBooleanSet to true if you want to immediately send the SMS and deduct the cost from your API Key balance.
webhookUrlString

Webhook URL where you want to receive order updates.

Same data as /orderstatus will be sent as POST to this URL.

{% tabs %} {% tab title="200: OK Response for creating a send order" %} {% code overflow="wrap" %} ```javascript { status: 'OK', orderId: '7dc6e6b61d8c54dff6b8d6ea2e3f08b018e57963df81d493a6f9728c4dc83318', payreq: 'lnbc30u1p34yef6pp50hrwddsa332dla4c6m4zu0cgkqvw27trm7qafyaxl9egcnwgxvvqdp5wdkhxdrnv968xgrsv9uk6etwwssywetjd4sku7fqw3mkjar5v4eqcqzpgxqyz5vqsp5fnj032qs6fuht2p3r245h3u6r9x32fhdw5n4qyn7mqm95jt0ag5q9qyyssqlyeyhnqq4y6l5ynxatvnqg6zldnqmwxx7qel0q79slfv7wvuk23zm2shczj4vxf39a4s8x36k9dxcgtnvwdv0j8uq4jcuq3yclw393sp8uywdc | paid' } ``` {% endcode %} {% endtab %} {% tab title="500: Internal Server Error " %} ```javascript { status: 'error', reason: 'backend error' } ``` {% endtab %} {% endtabs %} ### Funding an Account If you have an API Key, you can fund your prepaid balance using this endpoint. ## Create Fund Order `POST` `https://api2.sms4sats.com/fund` Create an sms4sats order to send an SMS message to a phone number. #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------- | | X-API-Key\* | String | Optional API Key to use if you want to use a pre-funded account to immediately send or receive SMS. | #### Request Body | Name | Type | Description | | ---------------------------------------- | ------ | ------------------------------------ | | amount\* | Number | Amount in satoshis you want to fund. | {% tabs %} {% tab title="200: OK Response for creating a fund order" %} {% code overflow="wrap" %} ```javascript { status: 'OK', orderId: '7dc6e6b61d8c54dff6b8d6ea2e3f08b018e57963df81d493a6f9728c4dc83318', payreq: 'lnbc30u1p34yef6pp50hrwddsa332dla4c6m4zu0cgkqvw27trm7qafyaxl9egcnwgxvvqdp5wdkhxdrnv968xgrsv9uk6etwwssywetjd4sku7fqw3mkjar5v4eqcqzpgxqyz5vqsp5fnj032qs6fuht2p3r245h3u6r9x32fhdw5n4qyn7mqm95jt0ag5q9qyyssqlyeyhnqq4y6l5ynxatvnqg6zldnqmwxx7qel0q79slfv7wvuk23zm2shczj4vxf39a4s8x36k9dxcgtnvwdv0j8uq4jcuq3yclw393sp8uywdc' } ``` {% endcode %} {% endtab %} {% tab title="500: Internal Server Error " %} ```javascript { status: 'error', reason: 'backend error' } ``` {% endtab %} {% endtabs %} ### Getting Account Balance Use this endpoint to check the balance of an account ## Get Balance `GET` `https://api2.sms4sats.com/balance` Get balance for an API Key #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | ----------------------------------- | | X-API-Key\* | String | API Key that was previously funded. | {% tabs %} {% tab title="200: OK Normal Response" %} {% code overflow="wrap" %} ```javascript { status: 'OK', balance: 10000 } ``` {% endcode %} {% endtab %} {% tab title="400: Bad Request Request error" %} ```javascript { status: 'error', reason: 'X-API-Key header is missing.' } ``` {% endtab %} {% endtabs %} ### Getting Account History Use this endpoint to check the funding history of an account ## Get History `GET` `https://api2.sms4sats.com/history` Get funding history for an API Key #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | ----------------------------------- | | X-API-Key\* | String | API Key that was previously funded. | {% tabs %} {% tab title="200: OK Normal Response" %} {% code overflow="wrap" %} ```javascript { status: 'OK', totalAmount: 349500, orders: [ { amount: 9500, createdAt: 1668612831730, desc: 'fund account', description: 'fund account', holdinvoice: true, preimage: 'xxx', preimageHash: 'sha256(xxx)', price: 9500, userId: 'APIKEY' }, ... ], } ``` {% endcode %} {% endtab %} {% tab title="400: Bad Request Request error" %} ```javascript { status: 'error', reason: 'X-API-Key header is missing.' } ``` {% endtab %} {% endtabs %} {% hint style="info" %} Get in touch for volume discounts: . {% endhint %}