Nov 24, 2023 -  We have integrated with Twilio’s toll-free number registration API! See Details Here 

UltraSMSScript API



 

UltraSMSScript provides HTTP SMS APIs

API calls can be executed from nearly any popular programming language. Through our API you can access the most core features of the UltraSMSScript platform. Adding and retrieving contacts, sending/scheduling bulk SMS to groups, sending/scheduling SMS to a specific contact, message delivery reports, retrieving your SMS/Voice credit balance, and adding contact appointments are available at the moment. More will be added in the future, but these 8 were requested the most and are most useful when extending the functionality of your own platform.

Check out the list of available APIs below and each of the API’s parameters, return values, and sample API JSON responses. Integrating the UltraSMSScript API into your application will enable you to extend the functionality of the platform into your own app!

You must first purchase Level 3, 4, or ULTRA to be able to use the APIs. Your API key will be available inside your user panel once you have the software installed on your hosting and have created yourself a user account.

Add Contacts

 

Description

Add contacts to group specified. Accepts GET or POST requests.

     
     

URL

http://{YOUR_URL_HERE}/apis/addcontact/
Example call:
http://{YOUR_URL_HERE}/apis/addcontact/?apikey=APIKEY&group=GROUPNAME&number=PHONENUMBER&name=NAME&email=EMAIL&bday=BDAY
PHP Code Sample (cURL):

Parameters

apikey
(Required) The API key of your account.
group
(Required) The name of the group you are associating this contact to. Must be a valid group name that already exists in the system.
number (Required) The number of the contact. NO spaces, dashes, or parentheses in phone numbers.

Include country code in the number
US Example: 12025248725 UK Example: 447481340516

name
(Optional) The name of the contact.
email
(Optional) The email address of the contact.
bday (Optional) The birthday of the contact. Format: YYYY-MM-DD

Return Values

0
0 is passed back on successful API call.
-1
Invalid API key passed in.
-2
There was no number passed in.
-3
Group and number required.
-4
There was no group passed in.
-5
The group passed in is invalid or does not exist in the group list.
-6
Other error.
-7
Number is already subscribed for [group name].
-20
Level 1 does not have access to the API. API can only be used with Levels 2, 3, and 4.

Example API Response (data is returned in universal and lightweight JSON format)

Get Contacts

 

Description

Return contacts based on optional search parameters passed in. Accepts GET or POST requests.

URL

http://{YOUR_URL_HERE}/apis/getcontacts/
Example call:
http://{YOUR_URL_HERE}/apis/getcontacts/?apikey=APIKEY&name=jimmy
PHP Code Sample (cURL):

     

Parameters

apikey
(Required) The API key of your account.
name
(Optional) Name passed in to search on.
email
(Optional) Email passed in to search on.
number
(Optional) Number passed in to search on.
group
(Optional) The group name to filter the contacts. Must pass in a valid group name that exists in the group list.
source
(Optional) The signup source to filter the contacts. Valid values are 0, 1, 2, 3.
0=>import, 1=>sms, 2=>web widget, 3=>kiosk
subscribed
(Optional) Opted out / opted in contacts to filter on. Valid values are 0, 1. 0=>subscribed, 1=>unsubscribed.
sortby
(Optional) Field to sort by. Valid values are name, phone_number, created. Default is created in desc order.
sortdir
(Optional) Direction of sorting. Available values are asc, desc. Default is created in desc order.
limit
(Optional) Used to return maximum number of contacts per page. Default is 50.
page
(Optional) Page of results to retrieve.

Return Values

Contacts
List of contacts returned on successful API call.
-1
Invalid API key passed in.
-2
The group passed in is invalid or does not exist.
-3
The source passed in is invalid. Proper values are 0, 1, 2, 3.
-4
The subscribed passed in is invalid. Proper values are 0, 1.
-5
The sortby passed in is invalid. Proper values are name, phone_number, created.
-6
The sortdir passed in is invalid. Proper values are asc, desc.
-7
No contacts found.
-20
Level 1 does not have access to the API. API can only be used with Levels 2, 3, and 4.

Example API Response (data is returned in universal and lightweight JSON format)

Send/Schedule Bulk SMS to a Group

Description

Send or Schedule a bulk SMS to a specific group. Accepts GET or POST requests.

     
     

URL

http://{YOUR_URL_HERE}/apis/smsgroup/
Example call:
http://{YOUR_URL_HERE}/apis/smsgroup/?apikey=APIKEY&from=FROMNUMBER&to=GROUPNAME&message=MESSAGE&rotate=1
PHP Code Sample (cURL):

   

Parameters

apikey
(Required) The API key of your account.
from
(Required) The number you are sending from. Could be any SMS-enabled number in your account.
to (Required) The group name you are sending the message to. Must be a valid group name that exists in your group list.

message
(Required) The message text you are sending. 1 credit is charged for each 160 character segment. If you have a message that is 300 characters, and you are sending to 10 people, 20 credits will be deducted (2 credits for each person).

NOTE: Messages containing non-GSM(unicode) characters will be charged 1 credit for each 70 character segment.

alphasender
(Optional) This is the alphanumeric sender ID you want to send the message from. Only certain countries can send from an alphanumeric sender id, which are included below:
AUSTRALIA, AUSTRIA, DENMARK, ESTONIA, FINLAND, FRANCE, GERMANY, HONG KONG, IRELAND, ISRAEL, LITHUANIA, NETHERLANDS, NORWAY, POLAND, SPAIN, SWEDEN, SWITZERLAND, UNITED KINGDOM

Alphanumeric SenderID requirements: Any combination of 1 to 11 letters(A-Z/a-z) and numbers(0-9). 1 letter and no more than 11 alphanumeric characters may be used.

rotate (Optional) Flag if you want to rotate through all your numbers in your account when sending the message. Set to 1 if you want to rotate. If nothing is passed in, it will NOT rotate through your numbers.
throttle (Optional) Sending throttle to control the sending rate of the message being sent. The default is 1, which will send the message at a rate of 1 SMS every 1 second per long code. If nothing is passed in, it will send at this rate. If you want to send a slower rate, you can pass in a 2, 3, 4, 5 or 6 which will send at a rate of 1 SMS every 2 seconds per long code, every 3 seconds, etc…The slowest setting which can be used is 6.
sendondate (Optional) If scheduling bulk SMS, this is the date/time message will be sent. If it’s a recurring event, this is the 1st date/time in the series.

Format: DD-MM-YYYY HH:MM
Example: 20-03-2017 19:30

recurring (Optional) Create recurring events. Set to 1 if you want to create a recurring event.
repeat (Optional) Type of recurring event you want to schedule. Valid values are ‘Daily’, ‘Weekly’, ‘Monthly’, ‘Yearly’.
frequency (Optional) How often you want the recurring events to happen based on the Repeat parameter above. For example, if you pass in ‘Daily’ for repeat and ‘3’ for Frequency, it will schedule the events every 3 days. Valid values are 1-30.
enddate (Optional) End date you want the recurring events to end. For example, if you pass in a sendondate(start date) of Oct 10 at 6:30 and you want the last event to run on Nov 10, you must pass in an end date of Nov 10 at 6:30 so Nov 10 will be included as the last date.

Format: DD-MM-YYYY HH:MM
Example: 20-03-2017 19:30

Return Values

0 or group SMS ID
0 is passed back on successful API call when scheduling bulk SMS. The group SMS ID will be passed back on successful API call when sending bulk SMS immediately.
-1
Invalid API key passed in.
-2
There was no ‘from’ number passed in.
-3
The ‘from’ number passed in doesn’t exist in your account or isn’t SMS-enabled.
-4
There was no message passed in to be sent.
-5
There was no group passed in.
-6
The group passed in is invalid or does not exist.
-7
The alphanumeric sender ID passed in is either invalid(doesn’t match requirements below) OR the user account does not have permission to send from an alphanumeric sender ID.
Requirements: You may use any combination of 1 to 11 letters(A-Z/a-z) and numbers(0-9). 1 letter and no more than 11 alphanumeric characters may be used.

-8
The rotate flag passed in is invalid. Proper values are either 1 or 0.
-9
The sending throttle flag passed is invalid. Proper values are 1, 2, 3, 4, 5, or 6.
-10
The recurring flag passed in is invalid. Proper values are either 1 or 0.
-11
The repeat parameter passed in is invalid. Proper values are ‘Daily’, ‘Weekly’, ‘Monthly’, ‘Yearly’. Also, if recurring flag is 1 and nothing passed in for this field will trip this error.
-12
The frequency parameter passed in is invalid. Proper values are 1-30. Also, if recurring flag is 1 and nothing passed in for this field will trip this error.
-13
Must have a recurring end date if you want to schedule a recurring event. The recurring flag is 1 and nothing passed in for enddate.
-14
Not enough credits to send the message.
-15
No subscribers found in group.
-16
Other error.
-20
Level 1 does not have access to the API. API can only be used with Levels 2, 3, and 4.

Example API Response (data is returned in universal and lightweight JSON format)

Get Bulk SMS Delivery Stats For a Group

Description

This gets the summarized delivery stats for the bulk SMS sent for the group SMS ID. # of successful and # of failed messages. Accepts GET or POST requests.

     
 

URL

http://{YOUR_URL_HERE}/apis/getbulksmsdeliveryreport/
Example call:
http://{YOUR_URL_HERE}/apis/getbulksmsdeliveryreport/?apikey=APIKEY&groupsmsid=GROUPSMSID
PHP Code Sample (cURL):

     

Parameters

apikey
(Required) The API key of your account.
groupsmsid
(Required) The group SMS ID you want to get the delivery stats for. This ID will be returned on successful API call for Send Bulk SMS to Group. It will NOT be returned when scheduling bulk SMS.

Return Values

successful
The number of successful messages.
failed
The number of failed messages.
-1
Invalid API key passed in.
-2
The group SMS ID is missing. You must pass this in to get delivery stats for this group.
-3
The group SMS ID is invalid or does not exist.
-20
Level 1 does not have access to the API. API can only be used with Levels 2, 3, and 4.

Example API Response (data is returned in universal and lightweight JSON format)

Send/Schedule SMS to a Contact

Description

Send or Schedule a SMS to a specific contact. Accepts GET or POST requests.

     
     

URL

http://{YOUR_URL_HERE}/apis/smscontact/
Example call:
http://{YOUR_URL_HERE}/apis/smscontact/?apikey=APIKEY&from=FROMNUMBER&to=CONTACTNUMBER&message=MESSAGE
PHP Code Sample (cURL):

     

Parameters

apikey
(Required) The API key of your account.
from
(Required) The number you are sending from. Could be any SMS-enabled number in your account.
to (Required) The contact number you are sending the message to.

Example: 18159819712
NO spaces, dashes, or parentheses in phone numbers. Include country code in the number

message
(Required) The message text you are sending. 1 credit is charged for each 160 character segment.

NOTE: Messages containing non-GSM(unicode) characters will be charged 1 credit for each 70 character segment.

alphasender
(Optional) This is the alphanumeric sender ID you want to send the message from. Only certain countries can send from an alphanumeric sender id, which are included below:
AUSTRALIA, AUSTRIA, DENMARK, ESTONIA, FINLAND, FRANCE, GERMANY, HONG KONG, IRELAND, ISRAEL, LITHUANIA, NETHERLANDS, NORWAY, POLAND, SPAIN, SWEDEN, SWITZERLAND, UNITED KINGDOM

Alphanumeric SenderID requirements: Any combination of 1 to 11 letters(A-Z/a-z) and numbers(0-9). 1 letter and no more than 11 alphanumeric characters may be used.

sendondate (Optional) If scheduling SMS, this is the date/time message will be sent. If it’s a recurring event, this is the 1st date/time in the series.

Format: DD-MM-YYYY HH:MM
Example: 20-03-2017 19:30

recurring (Optional) Create recurring events. Set to 1 if you want to create a recurring event.
repeat (Optional) Type of recurring event you want to schedule. Valid values are ‘Daily’, ‘Weekly’, ‘Monthly’, ‘Yearly’.
frequency (Optional) How often you want the recurring events to happen based on the Repeat parameter above. For example, if you pass in ‘Daily’ for repeat and ‘3’ for Frequency, it will schedule the events every 3 days. Valid values are 1-30.
enddate (Optional) End date you want the recurring events to end. For example, if you pass in a sendondate(start date) of Oct 10 at 6:30 and you want the last event to run on Nov 10, you must pass in an end date of Nov 10 at 6:30 so Nov 10 will be included as the last date.

Format: DD-MM-YYYY HH:MM
Example: 20-03-2017 19:30

Return Values

0
0 is passed back on successful API call.
-1
Invalid API key passed in.
-2
There was no ‘from’ number passed in.
-3
The ‘from’ number passed in doesn’t exist in your account or isn’t SMS-enabled.
-4
There was no message passed in to be sent.
-5
There was no contact number passed in.
-6
The contact number passed in is either invalid, does not exist in your contact list, or has unsubscribed.
-7
The alphanumeric sender ID passed in is either invalid(doesn’t match requirements below) OR the user account does not have permission to send from an alphanumeric sender ID.
Requirements: You may use any combination of 1 to 11 letters(A-Z/a-z) and numbers(0-9). 1 letter and no more than 11 alphanumeric characters may be used.

-8
The recurring flag passed in is invalid. Proper values are either 1 or 0.
-9
The repeat parameter passed in is invalid. Proper values are ‘Daily’, ‘Weekly’, ‘Monthly’, ‘Yearly’. Also, if recurring flag is 1 and nothing passed in for this field will trip this error.
-10
The frequency parameter passed in is invalid. Proper values are 1-30. Also, if recurring flag is 1 and nothing passed in for this field will trip this error.
-11
Must have a recurring end date if you want to schedule a recurring event. The recurring flag is 1 and nothing passed in for enddate.
-12
Not enough credits to send the message.
-16
Other error.
-20
Level 1 does not have access to the API. API can only be used with Levels 2, 3, and 4.

Example API Response (data is returned in universal and lightweight JSON format)

Get SMS Delivery Stats For a Contact

Description

This gets the delivery status for the most recent SMS sent to the contact. Accepts GET or POST requests.

     
 

URL

http://{YOUR_URL_HERE}/apis/getcontactsmsdeliveryreport/
Example call:
http://{YOUR_URL_HERE}/apis/getcontactsmsdeliveryreport/?apikey=APIKEY&number=NUMBER
PHP Code Sample (cURL):

     

Parameters

apikey
(Required) The API key of your account.
number
(Required) Number for the contact you want to get the most recent delivery status for. It will only return most recent outbound message status for this number.

Include country code in the number
US Example: 12025248725 UK Example: 447481340516

Return Values

smsstatus
The sms status of the most recent message sent to contact.
errormsg
The error message of the sms if it failed or was undelivered.
-1
Invalid API key passed in.
-2
Number passed in is blank.
-3
Number passed in is invalid or can’t be found for outbound SMS sent to this number.
-20
Level 1 does not have access to the API. API can only be used with Levels 2, 3, and 4.

Example API Response (data is returned in universal and lightweight JSON format)

Check SMS/Voice Credit Balance

Description

Check SMS or voice credit balances on user account. Accepts GET or POST requests.

     
     

URL

http://{YOUR_URL_HERE}/apis/getcreditbalance/
Example call:
http://{YOUR_URL_HERE}/apis/getcreditbalance/?apikey=APIKEY&type=TYPE
PHP Code Sample (cURL):

     

Parameters

apikey
(Required) The API key of your account.
type
(Required) Flag to determine SMS or Voice credit balance. 1 to return SMS credit balance and 2 for Voice.

Return Values

Credit balance number
Your credit balance is returned on successful API call.
-1
Invalid API key passed in.
-2
Invalid type passed in. Should only be either a 1 or 2 depending on what credit balance you want to retrieve. 1 for SMS and 2 for Voice.
-20
Level 1 does not have access to the API. API can only be used with Levels 2, 3, and 4.

Example API Response (data is returned in universal and lightweight JSON format)

Add Appointments

 

Description

Add contact appointments. Accepts GET or POST requests.

     
     

URL

http://{YOUR_URL_HERE}/apis/addappointment/
Example call:
http://{YOUR_URL_HERE}/apis/addappointment/?apikey=APIKEY&number=PHONENUMBER&apptdate=APPTDATE&status=STATUS
PHP Code Sample (cURL):

Parameters

apikey
(Required) The API key of your account.
number
(Required) The number of the contact. NO spaces, dashes, or parentheses in phone numbers.

Include country code in the number
US Example: 12025248725 UK Example: 447481340516

apptdate (Required) The appointment date/time.

Format: DD-MM-YYYY HH:MM
Example: 20-03-2017 19:30

status
(Required) The status of the appointment. Valid values are 0, 1, 2, 3.

0=>Unconfirmed, 1=>Confirmed, 2=>Cancelled, 3=>Rescheduled

Return Values

0
0 is passed back on successful API call.
-1
Invalid API key passed in.
-2
There was no contact number passed in.
-3
Number passed in should only contain numbers, NO spaces, dashes, or parentheses in phone numbers.
-4
There was no appt datetime passed in.
-5
There was no status passed in.
-6
The status passed in is invalid. Valid values are 0, 1, 2, 3.
-7
Contact not found.
-8
Appointment already exists for this contact and datetime.
-9
Other error.
-20
Level 1 does not have access to the API. API can only be used with Levels 2, 3, and 4.

Example API Response (data is returned in universal and lightweight JSON format)