REST API Documentation
Integrate SMS Sending & Receiving via our SMS REST API
Before you start...
To use this API, you will need an SMS Everyone account.
We will provide you with a username, password and at least one originator (where the message will appear to come from).
Please sign up for a free trial to get started.
Introduction
The REST API allows you to access SMS Everyone's full sending and receiving functionality.
This includes the sending of single messages and bulk campaigns.
You can schedule, modify and delete campaigns.
Plus you can check the delivery status of messages, as well as your credit balance and account status.
If you have sub-accounts, you can programmatically top up their credits
You can even subscribe and unsubscribe end users.
We support the sending/scheduling in your time zone and we accept full unicode characters if required.
We highly recommend using SSL
Use of this API assumes a working knowledge of RESTful web APIs.
<<< Click on any of the links to the left to quickly jump to the required section.
Authentication
You will be provided with a username and password to access our API.
The username and password are sent to our API in the authorization header and the authentication type = Basic
eg:
Authorization: Basic bWNo*****************bGUx
If you don't have a username and password, sign up and we'll send it to you.
Mention you want to hit our API and we will send you your basic auth string.
Or to create your basic authorization string yourself, the format is USERNAME:PASSWORD and then base 64 encode that.
for example, if your username was jimsbusiness and your password was s56sbdyte83fs the format would be:
jimsbusiness:s56sbdyte83fs
Then base 64 encode that string.
You can use https://www.base64encode.org/ if required.
Header Examples
cURL
--header 'Authorization: Basic bWNo*****************bGUx' \
--header 'Content-Type: application/json' \
C#
request.AddHeader("Authorization", "Basic bWNo*****************bGUx");
request.AddHeader("Content-Type", "application/json");
SMS REST formats and conventions
This section will take a brief look at some of the formats used in the REST API.
JSON
JSON (application/json) is the content type of both requests and responses if not otherwise specified.
eg: Content-Type: application/json
Requests with invalid JSON will be rejected.
New features might result in additional request and response parameters. New request parameters will either have a default value or
considered optional to retain backwards compatibility. It is highly recommended to ignore any unexpected parameters when reading JSON in API responses.
Phone numbers (MSISDN)
Only MSISDNs in international format without the + sign are accepted by the API. For example:
-
To send to the Australian number 0400123456, the format would be 61400123456.
-
To send to the New Zealand number 021123456, it would be 6421123456
All MSISDNs returned by the REST API will be without a + or 00 prefix, even if they were sent in with one.
Timestamps
Timestamps are used for expressing a moment in time. They are represented using the ISO-8601 standard without the time zone extension.
An example of this is the received field for SMS replies to show when a reply SMS was received by the system. eg: 2020-07-27T10:01:10
All timestamps returned by the API can be represented in your local time or UTC. Just let us know what you prefer.
HTTP Status Codes
The REST API returns an HTTP status and code each time a request is made.
The following HTTP status codes are used by the API. Additional codes might be added in the future and if you encounter a code not in this list please contact us for a definition.
HTTP Errors
Where we pass back an error, there will be a JSON object in the body explaining the error. It has the following structure:
Error Codes
If there is an error with your API request, the error codes in the table below can be returned as values for the code field.
✨ PRO TIP (ESPECIALLY FOR AI DEVELOPERS) ✨
You should write your application to consume the error codes that are returned from API calls.
in other words - if we respond to your API call with an error code, you should take that error code and put it into your application so that you recognise there is a problem.
Where applicable you should also display our error message (or your interpretation of our error message) to the end user.
This will significantly reduce issues with your software.
It will make you and your users aware of any failed attempts immediately and allow you to rectify any mistakes quickly.
It will make it faster and easier for us to support you if you can tell us the error code you are receiving when you contact us for help.
Error Code | Error Description |
|---|---|
0 | Message is OK (so far). Or successful response. |
-2 | Account suspended. Please contact SMS Everyone for more info. |
-100 | Campaign create attempt with no CampaignID or ClientRef specified |
-101 | Campaign create attempted to modify a deleted campaign |
-102 | Campaign create attempted to modify a running campaign |
-103 | Campaign create attempted to modify a completed campaign |
-104 | Deletion request after campaign start time cutoff |
-105 | Campaign deletion request for campaign that does not exist |
-106 | Deletion request for completed campaign |
-107 | Deletion request for previously deleted campaign |
-108 | Campaign rescheduled due to outage |
-109 | Campaign rescheduled due to unknown reason |
Sending SMS Messages
Be sure to read the Authentication section above before you send.
The following operation will send an SMS message or a bulk SMS campaign.
Individual characters used in the message determine the type of encoding that will ultimately be used to send the SMS message. The API automatically detects the encoding required from the characters used, which allows us to support the delivery of SMS in any language.
Depending on the length of the message field, one message might be split into multiple parts and charged accordingly. (Although it will land on the phone as a single concatenated message)
The limit of a single SMS is 160 characters including spaces, carriage returns, line feeds etc.
Once you exceed 160 characters, the SMS is broken into chunks of 153 characters.
(7 characters are required to tell the phone that it is part 1 of 3, part 2 of 3, part 3 of 3 etc.
Character limits per SMS message:
1 SMS = 160 characters
2 SMS = 306 characters (2 x 153)
3 SMS = 459 characters (3 x 153)
4 SMS = 612 characters (4 x 153)
5 SMS = 765 characters (5 x 153)
Unicode
As soon as you include a unicode character in the message field (eg an emoji or non English character), the character limit drops to 70 characters. Once you exceed 70 characters, the SMS is broken into chunks of 67 characters.
Character limits per unicode message:
1 SMS = 70 characters
2 SMS = 134 characters (2 x 67)
3 SMS = 201 characters (3 x 67)
4 SMS = 268 characters (4 x 67)
5 SMS = 335 characters (5 x 67)
These character limits are an international standard.
Basic Character Set
You can send up to 160 characters in a single SMS message if all characters in your message are part of the GSM 7-bit character set below:
LF is the Line Feed character - for JSON format, provide it as \n
SP is the Space character
Extended Character Set
The following characters are also available, however they are counted as two characters in the SMS message rather than one:
| , ^ , € , { , } , [ , ] , ~ , \
Other Characters
If other characters are required for different languages, 16-bit Unicode (UCS-2) encoding will be used. When using UCS-2 encoding, each character will take 2 bytes, which means up to 70 characters can be sent per UCS-2 encoded SMS message.
Long Messages
The message body in a request can contain up to 2000 characters.
Send SMS - API Request URL
The URL to POST to is https://smseveryone.com/api/campaign
JSON Body Parameters
Below are all of the available parameters for sending an SMS, modifying or deleting a campaign and checking the status of a campaign.
✨ PRO TIP (ESPECIALLY FOR AI DEVELOPERS) ✨
Please read this section carefully - It will save you a lot of time building your application if you submit these fields correctly from the beginning. Many JSON examples are below.
All parameters are caps sensitive. Please submit them exactly as we have them below.
Originator
-
JSON Type = String
-
Required = Yes
-
Description
-
The origin of the message. ie where the message will appear to come from when it hits the phone.
-
When you signed up, we will have sent you the originator/s that you can use for your account and country.
-
Enter the origin exactly as we gave it to you. Word origins are caps sensitive.
-
Please note: You cannot use an originator that is not registered with SMS Everyone. If you attempt to send from an originator that is different from what we gave you, we will throw an error.
-
-
Constraints
-
You can only send from an originator that is registered with SMS Everyone.
-
Must be either:
-
A valid MSISDN (Mobile phone number in international format without the + sign)
-
Short-code (a 4 - 6 digit number available in some countries like New Zealand)
-
Alphanumeric (Must be ACMA registered in Australia. Not available in New Zealand)
-
-
Destinations
-
JSON Type = String array
-
Required = Yes
-
Description
-
The mobile phone number/s of the recipient/s of the message.
-
This should be in international format without the + sign. However, we may fix the format for you automatically if you only send to either Australia or New Zealand.
-
An example of an Australian destination number would be 61400123456.
-
An example of a New Zealand destination number would be 6421123456
-
-
You can submit either a single number per post for individual messages or for bulk SMS campaigns you can submit up to 1000 numbers per post.
-
-
SENDING BULK SMS CAMPAIGNS
-
When sending bulk campaigns, submit up to 1000 destination numbers per API call and include a unique reference ID for the campaign.
-
Make this reference ID the same for all API calls that are for the same campaign. Then we will automatically combine the destination numbers together from all API calls that you submit with that Reference ID into one big campaign in our queues.
-
You can then modify or delete the whole campaign in a single post (See modifying / deleting a campaign below)
-
We will deduplicate the numbers for you at the time of sending and wash against any optouts.
-
-
Constraints
-
1 to 1000 elements
-
Message
-
JSON Type = String
-
Required = Yes
-
Description
-
The message content.
-
Can be plain text and/or unicode characters. See here for info on message length, characters, unicode etc
-
-
Constraints
-
Max 2000 characters
-
Action
-
JSON Type = String
-
Required = Yes
-
Description
-
The action you want the REST API to perform. (Caps sensitive)
-
create - creates an SMS campaign.
-
modify - modifies a scheduled campaign. You can update the originator, message and TimeScheduled fields with the modify action. You need to include our CampaignId field to modify a scheduled campaign. We pass this to you in the http response when you schedule the campaign.
-
delete - deletes a scheduled campaign. You must specify our CampaignId to delete a campaign.
-
status - retrieves the status of a campaign. (Scheduled, Running, Deleted etc)
-
pause - pauses a campaign either before it sends or during the send.
-
Note - we send bulk campaigns at well over 1000 messages per second so attempting to pause a sending campaign may not work unless the campaign is very large.
-
-
unpause - resumes the sending of a campaign.
-
-
-
Constraints
-
All actions are lower case. eg create, modify, delete
-
TimeScheduled
-
JSON Type = String
-
Required = No
-
Description
-
If you are scheduling a message, include this field.
-
Format = "YYYYMMDDHHmm"
-
If you are sending the campaign now, this field is not required.
-
Example: "TimeScheduled": "203507301300" would send the campaign at 1pm on the 30th of July 2035
-
If you set the date/time in the past, the SMS will be sent immediately.
-
-
Constraints
-
Must be 12 characters, numeric and in the above format.
-
Reference
-
JSON Type = String
-
Required = No
-
Description
-
Your unique reference ID of the message/campaign
-
Include this for all bulk SMS campaigns larger than 1000 recipients that you want to schedule for later so that you can include all recipients in the one campaign. Then you can modify or delete the campaign if required.
-
-
Constraints
-
Max 128 characters
-
CrmIds
-
JSON Type = String array
-
Required = No
-
Description
-
A CRMID (Or List ID) is the ID number of a list of mobile numbers stored in your SMS Everyone account.
-
You can submit the CRMID instead of the Destinations parameter and we will send the SMS to everyone in that stored list.
-
First you must either:
-
Upload the list to our web interface and retrieve the CRM ID by hovering your mouse over the list description. OR
-
Create the list and add the numbers via the 'Lists' API. We will give you the CRM ID in the API response.
-
-
CampaignId
-
JSON Type = String
-
Required = No
-
Description
-
If you are wanting to delete, modify or check the status of a campaign.
-
We pass this field to you in the http response when you schedule or send an sms. eg "CampaignId": 11967223
-
Sending an SMS - JSON Examples
Example JSON Body to send a single message to one recipient
{
"Message": "Hello, this is a test",
"Originator": "61400190499",
"Destinations": [
"61400123456"
],
"Action": "create"
}
Example JSON to send a message to two recipients
{
"Message": "Hello, this is a test",
"Originator": "61400190499",
"Destinations": [
"61400123456",
"61400123999"
],
"Action": "create"
}
JSON example to schedule a message to five recipients with a reference ID
{
"Message": "Hello, this is a test",
"Originator": "61400190499",
"Reference": "1234567",
"TimeScheduled": "202008301300",
"Destinations": [
"61400123456",
"61400123999",
"61400123888",
"61400123777",
"61400123666"
],
"Action": "create"
}
Example to add 5 more numbers to the existing scheduled bulk campaign above with reference ID '1234567'
{
"Message": "Hello, this is a test",
"Originator": "61400190499",
"Reference": "1234567",
"TimeScheduled": "202008301300",
"Destinations": [
"61400123000",
"61400123111",
"61400123222",
"61400123333",
"61400123444"
],
"Action": "create"
}
Send an SMS to a stored list (You must upload a list to our web interface or via the API and have the CRMID first)
{
"Message": "Hello, this is a test to a list",
"Originator": "61400190499",
"TimeScheduled": "202307141230",
"Reference": "123456",
"Action": "create",
"CrmIds": [4398]
}
Responses for successfully created SMS campaigns
The JSON response object contains the following parameters:
JSON RESPONSE EXAMPLES
Example of a JSON response when successfully sending an SMS to one recipient
{
"Code": 0,
"CampaignId": 11967222,
"Messages": 1,
"Segments": 1,
"Credits": 1
}
Response when sending to two recipients
{
"Code": 0,
"CampaignId": 11967222,
"Messages": 2,
"Segments": 1,
"Credits": 2
}
Response when sending to five recipients and you've supplied a reference ID and a schedule time
{
"Code": 0,
"CampaignId": 11967222,
"Messages": 5,
"Segments": 1,
"Credits": 5
}
Response when adding 5 more numbers to the above scheduled message
{
"Code": 0,
"CampaignId": 11967222,
"Messages": 5,
"Segments": 1,
"Credits": 5
}
Error Response when the destination number is missing or incorrect
{
"Message": "No valid destination number(s) specified",
"Code": -111
}
Error Response when the message text field is blank
{
"Message": "Campaign message text not specified",
"Code": -117
}
Error Response when there are not enough credits on the account
{
"Message": "Insufficient credits available to start campaign",
"Code": -202
}
Cancel a scheduled SMS message
To cancel/delete a campaign, submit our campaignID and the delete action to the same URL as above.
The below JSON deletes a scheduled SMS campaign with our campaign ID of 11967218
{
"CampaignId": 11967218,
"Action": "delete"
}
Response
200 OK
The JSON response object for a successfully cancelled message is:
{
"Message": "Deleted",
"Code": 0
}
Modify a scheduled SMS message
To modify the message text, originator or send date/time of a campaign, submit our campaign ID (which we will have given you in the API response when you first scheduled the campaign) and the 'modify' action to the same URL as above.
Note: the destinations field is not required to modify a campaign.
{
"Message": "Modified message text",
"Originator": "61400111222",
"CampaignID": "111626243",
"TimeScheduled": "202008301330",
"Action": "modify"
}
Response
200 OK
An example JSON response object for a successfully modified message:
{
"Code": 0,
"CampaignId": 11967222,
"Messages": 5,
"Segments": 1,
"Credits": 5
}
Pause a scheduled message
To pause a campaign, submit our campaign ID and the "pause" action to the same URL as above. You cannot pause a campaign that is scheduled in the past.
You can attempt to pause a campaign that is sending now, however our gateway sends at very high speeds and it is unlikely you will pause the campaign before it finishes unless the campaign is extremely large.
{
"CampaignId": 11967218,
"Action": "pause"
}
Response
200 OK
Example of a JSON response object for a successfully paused message is:
{
"Message": "Paused",
"Code": 0
}
Un-pause a scheduled message
To un-pause a campaign, submit our campaignID and the "unpause" action. Unpausing a campaign that was scheduled to be sent in the past will send any unsent messages in the campaign immediately.
{
"CampaignId": 11967218,
"Action": "unpause"
}
Response
200 OK
An example JSON response object for a successfully un-paused message is:
{
"Message": "Unpaused",
"Code": 0
}
Check the status of a campaign
To check the status of a campaign, submit our campaign ID and the status action to the same URL above. eg:
{
"CampaignId": 11967218,
"Action": "status"
}
Response
200 OK
The JSON response object contains the following parameters:
JSON examples
Example JSON for a paused campaign:
{
"Message": "Paused",
"Code": 0
}
Example JSON for a Scheduled campaign:
{
"Message": "Scheduled",
"Code": 0
}
Example JSON for a Running campaign (ie the messages are being sent now):
{
"Message": "Running",
"Code": 0
}
Example JSON for a Deleted campaign:
{
"Message": "Deleted",
"Code": 0
}
Check the delivery status of a campaign or message
(Delivery receipts)
You can check the delivery status of either a single message or retrieve the delivery status of all messages in a bulk SMS campaign.
If you are sending single messages at a time, you can submit just the campaign ID as there will only be one destination per campaign.
If you are sending in bulk (more than one mobile number per post) you have the option to request just the status of one of the mobile numbers in that bulk campaign or all of the numbers in that campaign (that we have delivery status info for)
-
To retrieve the status of all numbers in the campaign, submit only the CampaignID
-
To retrieve just the info on one of the numbers, submit the CampaignID and the specific Destination
-
Note: SMS carriers can try for up to 24 hours to reach a mobile handset if they are having trouble delivering. If we have not received a delivery receipt from the handset, we will not return any delivery status results in the JSON response. You can try again later if required.
We ask that you don't hit this API any more frequently than once a minute once you have it in production. Every 5 minutes is ideal for delivery receipts.
Delivery Status - API Request URL
POST to the URL https://smseveryone.com/api/DRStatus
JSON Body fields:
JSON examples
Example JSON for checking for delivery status of all mobile numbers on campaign ID 11967215.
This can be just one mobile number or many.
{
"CampaignId": 11967215
}
Example for checking the delivery status of just the mobile number 61400123456 on campaign ID 11967215
{
"CampaignId": 11967215,
"Destination": "61400123456"
}
Response
200 OK
The JSON response object contains the following parameters:
JSON response examples
Example JSON response showing successful delivery of an SMS to 61400123456
{
"CampaignId": 11967215,
"Count": 1,
"Destinations": [
{
"Destination": "61400123456",
"TimeStamp": "2020-07-28T11:06:02",
"Status": {
"DeliveryReceiptStatusId": 1,
"Code": 0
}
}
]
}
JSON example showing failed delivery to 61400123456. This is a permanent error (the mobile number can be deleted) The reason is 'Invalid destination'
(See Delivery Status Error Codes below)
{
"CampaignId": 11967218,
"Count": 1,
"Destinations": [
{
"Destination": "61400123456",
"TimeStamp": "2020-07-28T11:29:16",
"Status": {
"DeliveryReceiptStatusId": 2,
"Code": 300
}
}
]
}
JSON response example showing no delivery status information available as yet for campaign ID 11967210
OR you have submitted a campaign ID that does not belong to your account.
{
"CampaignId": 11967210,
"Count": 0,
"Destinations": []
}
Delivery Status codes
The following table contains the possible delivery status codes (DeliveryReceiptStatusID in our JSON response) and their explanation
Delivery Status Error Codes
The following table contains a description of the error codes that we pass to you in the "code" field of the JSON response when a message fails.
These codes come directly from the carriers in your country and we pass them through to you without altering them.
This info may not include all of the possible carrier codes as there are many and they are subject to change.
New codes may be added over time.
Permanent errors are when there is no point trying to send again as the number is dead, not provisioned, cancelled etc.
You can remove these numbers from your database.
Temporary errors are when the phone is unreachable, out of credit, switched off, the network is down etc.
You can try again at another time and you may be successful.
Retrieving SMS Replies via REST
You can hit our replies API to retrieve all available SMS replies on your account.
Use the same Basic authentication that you use to send an SMS campaign.
SMS Replies - API Request URL
POST to the URL https://smseveryone.com/api/replies
You don't need to add any JSON fields in the body.
However you do still need to include the curly brace {} brackets in the body. Like this:
{
}
When you hit this API, we will pass back all replies for your account in JSON format since the last time you checked.
Any replies that we pass to you are then flagged our end as 'retrieved' so that we don't pass them to you again unless you specify a date range and/or use one of the additional JSON body fields below.
The recommended frequency for checking for any new replies is every 5 minutes.
Please do not check this API any more often than once a minute once in production.
✨ PRO TIP (ESPECIALLY FOR AI DEVELOPERS) ✨
If you receive the JSON response that there are no messages ("Count": 0) this is not an error. It just means that there are no replies on the account to retrieve. You need to put some replies on the account if you want to retrieve them.
Send an SMS to your phone from your SMS Everyone account, then reply to it.
Wait 5 seconds, then hit the API again and you should see your reply in the JSON response to the API call.
But remember that we only give you a reply once so if you want to do more tests, keep replying to the SMS to add more replies to the account.
Or add "Test": true to your JSON body temporarily and we will give you the replies again and again without marking them as retrieved. Remove this field once you have finished testing.
JSON Body fields:
JSON examples:
To retrieve all replies on your account since you last checked:
{
}
To test replies without us flagging them as retrieved
{
"Test": true
}
To check replies for the last 2 days. (Note: we show results from 12am your time until now for the number of days selected)
{
"Days": 2
}
To check replies for a date range.
{
"DateStart": "2020-06-01",
"DateEnd": "2020-06-30"
}
Response
200 OK
The JSON response object contains the following parameters:
JSON examples
Retrieving 2 replies:
{
"Count": 2,
"Messages": [
{
"Received": "2020-07-27T10:01:10",
"Originator": "61400123456",
"Recipient": "61400190444",
"MessageText": "Thanks, yes i will be at the appointment",
"ReferenceId": "4499850"
},
{
"Received": "2020-07-27T11:35:10",
"Originator": "61400987654",
"Recipient": "61400190555",
"MessageText": "Can we reschedule?",
"ReferenceId": "4499851"
}
]
}
No messages available to retrieve:
{
"Count": 0,
"Messages": []
}
SMS Replies via Webhook (HTTP GET to your URL)
If you are using us via a single connection (not multiple accounts or sub-accounts), we can post SMS replies to a URL of yours via HTTP GET (JSON unavailable at this time)
Contact Us to discuss options or to set this up.
The following table includes all of the fields we pass to you.
You must respond with nothing but a 0 (zero) so that we know you received the data. No HTML. Just plain text.
Example HTTP GET String Sent from SMS Everyone to Your Site:
http://yourwebsite.aspx?username=xyz&password=xyz&originator=61402756334&recipient=61429848254&reference=4255525&message_text=Hello
Example HTTP response from your application:
0
Credit Balance, User ID & Account Status
You can hit our Retrieve User Settings API to get your SMS Everyone User ID, your current balance, whether your account has unicode enabled and if it can send messages longer 160 characters. Additional information may be added to this API call at any time.
Credit Balance - API Request URL
POST to https://smseveryone.com/api/RetrieveUserSettings
You only need basic authorization. No Body fields required.
Response
200 OK
The JSON response object contains the following parameters:
JSON examples
A balance of 116 SMS credits remaining on the account, the account can send unicode sms, messaging is limited to Australia only and userID is 9999:
{
"UserId": 9999,
"AllowUnicode": true,
"AllowInternational": false,
"Credits": 116,
"Code": 0
}
A balance of 119 SMS credits remaining on the account, the account can not send unicode sms, messaging is worldwide and userID is 9998:
{
"UserId": 9998,
"AllowUnicode": false,
"AllowInternational": true,
"Credits": 119,
"Code": 0
}
Optouts
SMS Everyone maintains an Optout Database for every client.
All SMS messages are washed against your optout database at the time of sending.
Contact Us if youd like to use one of our opt out numbers in your messages. This way if anybody replies to the optout number, they are automatically added to your optout database and you cannot send them a message again.
This REST API allows you to manually add mobile numbers to your optout database, opt a number back in (resubscribe) and retrieve a list of all optouts on your account.
Optouts - API Request URL
POST to https://smseveryone.com/api/optouts
JSON Body fields:
JSON examples:
JSON example to opt out (unsubscribe) the numbers 61400123456 and 61400222333 from your account
{
"Action": "add",
"Originator": [
"61400123456",
"61400222333"
]
}
To opt the number 61400123456 back in. (resubscribe)
{
"Action": "delete",
"Originator": [
"61400123456"
]
}
To retrieve a list of all opted out numbers
{
"Action":"list"
}
Response
200 OK
The JSON response object contains the following parameters:
JSON examples
JSON response where a number has been successfully opted out:
{
"Message": "Origins added",
"Code": 0
}
Successfully opted a number back in:
{
"Message": "Deleted 1 OptOut number",
"Code": 0
}
Retrieving a list of all optouts. (2 opted out numbers are associated with the account):
{
"Count": 2,
"OptOut": [
{
"Added": "2018-12-05 18:52:42",
"Originator": "61400555555",
"MessageText": "",
"Reason": "Client"
},
{
"Added": "2016-12-02 15:11:40",
"Originator": "61400999999",
"MessageText": "",
"Reason": "Client"
}
]
}
Lists
SMS Everyone allows you to store lists of mobile phone numbers in our database if required.
This way you can send SMS campaigns to pre-stored lists of any size (see Sending an SMS) instead of passing us all of the mobile phone numbers for each campaign every time you send.
You can also retrieve the list data via our web interface or via an API call
We allow you to add and delete lists as well as add and delete numbers within those lists.
One usage example might be that you have a website with a sign up form or somewhere that an end user can add their mobile number to receive updates or alerts. When they enter their mobile number, you hit our API with the 'Append' Action and add the mobile number to a list to be sent to later. If they unsubscribe, unsubscribe them via our Optouts API.
Lists - API Request URL
POST to https://smseveryone.com/api/crm
JSON Body fields:
JSON examples:
LIST
To retrieve a list of all of your CRM Groups (lists) in our database:
{
"Action": "list"
}
DETAILS
To retrieve all of the mobile numbers in the list with list ID 1234
{
"Action": "details",
"CrmId": 1234
}
CREATE
To create a list called 'Daily VIP client SMS' with 2 numbers in it.
{
"Action": "create",
"Description": "Daily VIP client SMS",
"Records": [
{
"Number": "61400123456,61400999111"
}
]
}
APPEND
To add 2 more numbers to the above list. (You will have retrieved the CrmID from our JSON response when you created the list)
{
"Action": "append",
"CrmId": 14456,
"Records": [
{
"Number": "61400111555,61400222333"
}
]
}
REMOVE
To remove a number from the above list.
{
"Action": "remove",
"CrmId": 14456,
"Records": [
{
"Number": "61400111555"
}
]
}
DELETE
To delete the above list.
{
"Action": "delete",
"CrmId": 14456,
}
Response
200 OK
The JSON response object contains the following parameters:
JSON examples
LIST - Retrieving a list of all lists in your database. (4 lists retrieved)
{
"Count": 4,
"Groups": [
{
"CrmId": 123,
"Description": "Saturday Night SMS",
"Count": 76,
"ParentGroup": 0,
"ActiveCampaign": 0,
"Deleted": ""
},
{
"CrmId": 710,
"Description": "Staff List",
"Count": 6,
"ParentGroup": 0,
"ActiveCampaign": 0,
"Deleted": ""
},
{
"CrmId": 2494,
"Description": "The Boss",
"Count": 1,
"ParentGroup": 0,
"ActiveCampaign": 0,
"Deleted": ""
},
{
"CrmId": 756,
"Description": "VIP list",
"Count": 494,
"ParentGroup": 0,
"ActiveCampaign": 0,
"Deleted": ""
}
]
}
DETAILS - Retrieving all of the numbers in a list. (6 mobile numbers in the list)
{
"CrmId": 710,
"Description": "Staff List",
"Count": 6,
"Records": [
{
"Number": "61400000000"
},
{
"Number": "61400999888"
},
{
"Number": "61423090878"
},
{
"Number": "61423646978"
},
{
"Number": "61434222777"
},
{
"Number": "61444888777"
}
]
}
CREATE - List successfully created.
{
"CrmId": 2496,
"Message": "CRM created"
}
APPEND - Successfully added 1 number to an existing list.
{
"Message": "Added 1 number",
"Code": 0
}
REMOVE - Successfully removed 1 number from an existing list.
{
"Message": "Removed 1 number",
"Code": 0
}
DELETE- Successfully deleted a list.
{
"Message": "Deleted",
"Code": 0
}
Add credits
You can add credits to an account via our credits API call. The usage scenario is more for software partners who have many sub-clients. Your software can hit our API requesting that the sub-account be topped up by x number of credits, we bill you at the end of the month for all top ups and you bill your clients accordingly. Ideally your software should send you an alert whenever a sub client tops up.
Please note: This is only for pre-approved clients and will return an error if you attempt to add credits via this method without approval.
Add Credits - API Request URL
POST to https://smseveryone.com/api/credits
Authentication for this particular API
Use basic auth as per all other API calls above. However the username and password must be of the sub-client that the credits are to be added to, not any parent/master account.
JSON Body fields:
JSON examples:
To add 1000 credits to an account:
{
"credits" : 1000,
"action" : "add"
}
Response
200 OK
The JSON response object contains the following parameters:
JSON examples:
Successfully added 1000 credits to an account and the new balance is 8488 credits:
{
"Credits": 8488,
"Code": 0
}
Attempting to add credits to an account that does not have approval from SMS Everyone.
{
"Message": "Not allowed to add credits",
"Code": -129
}
Attempting to add a negative amount of credits to an account or adding 0 credits.
{
"Message": "Invalid amount of credits to add",
"Code": -130
}
Extras
Time zones
We can set your account to any time zone in the world so that when you specify the send time, it will be in that countries’ time zone. Contact SMS Everyone to set this up.
Send Window
To prevent your staff or clients sending sms messages at inconvenient times, we can enable a send window on your account. This prevents sending sms outside of whatever hours you specify. For example, you could set your account to only send between 8am and 9pm in your time zone.
If you schedule/send before the window opens, we queue it until the window opens.
If you schedule/send after the window closes, we queue it for the following day when the window opens.
Contact SMS Everyone to set this up.
International SMS
We can send SMS to pretty much any country in the world. Contact us to discuss your requirements as there are certain restrictions in some countries and some countries require sender numbers (origins) to be set up and approved by the carriers.
Unicode Characters / International languages
We can send and receive SMS messages in any language. This includes emojis. eg ✨👍😊 ⭐ or for example Chinese characters eg 中国 etc etc.
See the unicode section under 'Sending SMS Messages' above as different character limits apply.
Contact Us for more information