Getting started with our SMS API
Welcome to SMSFactor ! This documentation will show you how to send SMS, import contact lists or manage your account through our API. Follow the guide for a fast and efficient SMS API integration !
In this documentation, you'll find all the key features of our SMS API :
- webhooks to retrieve and store data related to SMS sending;
- SMS sending simulation to test your configurations and automations;
- insertion of short tracked links to inform or generate traffic;
- receipt of SMS responses and acknowledgements;
- automatic unsubscribe management.
Please note: Our base URL for all queries is https://api.smsfactor.com
1. Create an SMSFactor account
In order to use our SMS API, you must first have an account.
You can register here.
2. Configure your account
Once you've created your account, a few steps are required to enable you to send your first SMS via API. Here's a breakdown of the steps you may need to take.
| Manipulation | Type of manipulation | How it works |
|---|---|---|
| Creating your API token | MANDATORY | In order to authenticate yourself, you first need to create a unique API token. |
| Buying credits | MANDATORY | To be able to send your first messages, you'll need an SMS pack, which can be purchased directly from the SMSFactor platform. |
| Monthly billing configuration | RECOMMENDED | If you estimate that you send more than 3,000 SMS per month, please contact us to benefit from monthly billing. |
| Registering your sender(s) | RECOMMENDED | Depending on the country you plan to send SMS to, sender registration may be mandatory. You can find the relevant rules here. |
| Setting up a balance alert | RECOMMENDED | This alert lets you receive an e-mail or SMS when your SMS credit reaches the critical threshold you've set (e.g.: 10, 100, 500 SMS). |
| Entering VAT number | DEPENDS ON YOUR USE CASE | Action required if you operate in a European Union country. To be able to purchase SMS credits, add your VAT number to your account (if applicable in your country). |
| Creating your sub-accounts | DEPENDS ON YOUR USE CASE | If required, you can create sub-accounts with their own SMS credits. |
| International SMS sending authorization request | DEPENDS ON YOUR USE CASE | If you need to send SMS to a country other than the one from which you created your account, you need to request an international sending authorization. |
3. Authenticate yourself
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
4. Select your content type
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
5. Test sending a SMS via our API
With our sample code, you can send a test in just a few clicks to check that the connection has been established and that your tool is ready to use our SMS API.
Choose your line of code to copy and paste :
You can also use our SDKs for :
6. Configure all the features you need
To take advantage of all the possibilities offered by sending SMS via API, select the features you need!
From sending SMS to setting up webhooks, managing contact lists and invoicing... It's all made easy with our API documentation!
Here's a list of some of the key features you'll find in our documentation:
- sending messages: configure the sending of single messages, campaigns with or without lists, add tracked short links and simulate your mailings;
- campaigns: manage the history, scheduling, STOPs, NPAIs and responses of your campaigns;
- lists: create, clean, retrieve and delete your lists. Also manage your blacklist and NPAI list;
- webhooks: retrieve your acknowledgements, responses, STOPs, clickers and balance alerts via API.
7. Familiarize yourself with our request statuses
For accurate tracking of your SMS API shipments, take a look at the different request statuses that our SMS API can send you:
| status | Description |
|---|---|
| 1 | OK |
| -1 | Authentication error |
| -2 | XML error |
| -3 | Not enough credits |
| -4 | Incorrect date delay |
| -5 | Resource not found |
| -6 | JSON error |
| -7 | Data error |
| -8 | Your campaign is currently under moderation. This status doesn't mean that your SMS won't be sent, quite the contrary actually. This is just to warn you that your campaign is being moderated and should be accepted quickly. No need to create a retry mechanism for this one or else the same SMS while be sent multiple times. |
| -99 | Unknown error |
8. Familiarize yourself with our anti-fraud anti-flood systems
Our API has an anti-fraud filter and an anti-flood filter.
If one of your campaigns passes through the anti-fraud system, it will be subject to manual validation by our team. In the event of fraudulent content, we reserve the right to refuse your campaign, in which case it will not be sent and the credits will be refunded.
Our API has an anti-flood filter. This is a maximum number of SMS sent to the same phone number over 1 hour. There are two limits: the number of text messages sent to a phone number and the number of text messages sent with the same content to a phone number. If you exceed these limits, we will block the sending of SMS to this number for 1 hour, and no credit will be deducted.