Getting started

This documentation will teach you how to send SMS, import lists or manage your accounts with our API. In order to use it, make sure to have an account. You can register here. Once your account has been created, you might want to set a balance alert. It will allow you to receive an email and/or an SMS each time your number of SMS left reaches the threshold you've defined

Our base URL for all API requests is https://api.smsfactor.com

Authentication

Once you have an account and created your first API token, you can authenticate yourself through the Authorization HTTP header as follows


Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMTY1NiIsImlhdCI6MTUxOTEyMDg2NX0.ZnGgbDC0OI3hPm2UXyl4rxU9JlpMTMBcTJT8RVgJbtQ
        
    

Content-Types

Our API supports application/json and application/xml Content-Types. You can specify a Content-Type with the Accept HTTP header. Our API expects and returns XML by default.


Accept: application/json
        
      

Request statuses

Here's the list of all the request statuses our API can send:

status Description
1 OK
-1 Authentication error
-2 XML error
-3 Not enough credits
-4 Incorrect date delay
-5 Contact list error
-6 JSON error
-7 Data error
-8 Your campaign is currently under moderation
-99 Unknown error

A few words about the SMS

How many characters are there in an SMS?

An SMS is made of 160 characters, according to international standards. In those 160 characters are recognized spaces, punctuation, letters, numbers and special characters. However, you are not restricted to those 160 characters, you may as well send a longer message but it will be recorded this way: 1 SMS every 153 characters.

Which are the two types of professional SMS?

Even though there is technically only one SMS, it exists a distinction separating two types of SMS according to the uses and legislation: alert SMS and promotional SMS.
Promotional SMS is designed for commercial offers, private sales, gifts, business events, etc. It is authorized only between 8am and 8pm from Monday to Saturday and is forbidden on Sundays and bank holidays. This type of SMS forces you to offer to your recipients a way to unsubscribe from your commercial offers.
Alert SMS is designed for meetings, gatherings, weather alerts, emergencies, financial transactions, etc. Given that they are informative and not commercial SMS text messages, they are not subjected to the same regulation. SMS alerts can be sent every day and at all times of day. You don’t have to add a STOP mention for alert sms as they do not have a commercial impact.

The choice of promotional or SMS alert is yours, we thank you for respecting those rules. If you are not sure, do not hesitate to contact our account executives, they’ll be glad to help you. Know that in case of problem due to a failure of respect of the rules, such as sending a promotional SMS as an alert SMS without a STOP mention, you’ll be held responsible.

How does unsubscription work?

You must always add a way for recipients to unsubscribe from your promotional SMS whereas it’s optional for alert sms. In France, if the sender is not personalized, a 5-digit number will be displayed as the sender of the SMS. The recipients will then be able to reply “STOP” directly to this number, thus a STOP mention won’t be added. If the sender is customized, a STOP mention will automatically be added at the end of the message, indicating to the recipient how to unsubscribe (example: “STOP SMS at 36173”). You should know that every country has its own rules about the sender, so feel free to contact us if you wanna know anything about sending toward a particular country. Because of the European data protection regulation, make sure you only send your promotional SMS campaigns to clients that have given their explicit consent and to always offer a way to unsubscribe.

How to receive replies to SMS sendings?

In order to receive replies, you can't personalize the sender as it prevents the recipients from replying. You should also know that replies aren't available in every country. For instance, they're available in France, Belgium and Switzerland. If replies are allowed in the country you're sending towards, you can create a webhook to receive them, .

How does sender personalization work?

As said before, every country has its own rules regarding the sender. For instance, for France and Switzerland, the sender can be up to 11 alphanumeric characters (no special character allowed). Remember that when the sender is personalized, your recipients are unable to reply. The sender can't be personalized for Belgium. You should also know that some phone models like iPhones are known for not being able to properly display 3 or less characters senders.

What is URL shortening used for?

Adding an URL to your message can be convenient but it would also take too many characters. URL shortening allows you to insert a link that's only 18 to 20 characters long. Furthermore, it also allows you to track the click of your recipients so you can see when and at which rate your recipients actually click on your link.

In which format the contacts’ numbers must be in when a list is created?

When you create a contact list, the numbers must be added in the international format E.164 (example: 33600000000, 33700000000 for France). Beware, every SMS sent is charged by operators, an updated list will avoid unnecessary spending. Therefore, you should delete false numbers (too short or too long numbers) but also invalid numbers.

How long is user related data hold?

We allow our clients to choose the retention period of their data on our platform or through the API. Therefore, it’s now possible to customize the retention period of messages, campaigns, contacts lists and surveys. Whether you choose to personalize the retention period of your data or not, know that we do not keep your data forever: a maximum period is decreed anyway. Therefore, you should delete false numbers (too short or too long numbers) but also invalid numbers.