REST API

You can easily send SMS and verify users with our intuitive API

Getting an API key

To be able to use TextFlow for sending an SMS or user verification, you first have to register an account, after that you are going to get a free API key with two free SMS, which you can use to send SMS or verify user request anywhere in the world.

After you have registered an account, your API key will be available on the API console.

Sending an SMS

Send an SMS wih the custom body to the recipient phone number.

POST https://textflow.me/api/send-sms

Headers

Name	Type	Description
Content-Type*		The value should be "application/json"
Authorization*		The value should be "Bearer API_KEY", where API_KEY is the API key that you have registered on the API console

Request Body

Name	Type	Description
phone_number*	String	Recipient phone number, with country prefix. E.g. [phone]
text*	String	Message body

200: OK Message successfully sent

{
  ok: true,
  status: 200,
  message: 'Message sent successfully',
  data: {
    to: '[phone]',
    content: 'Dummy message text...',
    country_code: 'Serbia',
    price: 0.15,
    timestamp: 1676842652256
  }
}

400: Bad Request Invalid API key

{ 
    ok: false, 
    status: 400, 
    message: 'Invalid API key' 
}

400: Bad Request Invalid phone number

{ 
    ok: false, 
    status: 400, 
    message: 'Phone number is invalid'
}

User verification

There are two endpoints that you should call in the user verification process.

/send-code is used to send user the verification code, while the /verify-code is used to check if the code that the user has entered is valid.

When you call the /send-code endpoint, we will send an SMS to the specified phone number. It should be the phone number that you want to verify, e.g. the phone number the user has entered in your app.

After sending the verification SMS, you can show the user a form where he should enter the verification code that he should have got in the SMS. When he submits the code, you should call the /verify-code endpoint from your backend and supply his phone number (which he can send again when submitting the code) along with the code that you want verified.

That way, you do not have to worry about keeping data about phone verification in your database, because we are doing it for you.

Send phone number verification SMS to your customers

POST https://textflow.me/api/send-code

Headers

Name	Type	Description
Content-Type*	String	The value should be "application/json"
Authorization*	String	The value should be "Bearer API_KEY", where API_KEY is the API key that you have registered on the API console

Request Body

Name	Type	Description
phone_number*	String	Phone number to verify, with country prefix. E.g. [phone]
service_name	String	What the user will see in the verification message. If the service_name is "Guest", he would get the following message: Your verification code for Guest is: CODE Default is none
seconds	Integer	How many seconds is the code valid for. Default is 10 minutes. Maximum is one day.

200: OK Verification code successfully sent

{
  ok: true,
  status: 200,
  message: 'Verification SMS sent. ',
  data: {
    verification_code: '214158',
    expires: 1676846234264,
    message_text: 'Your verification code is:\n214158'
  }
}

400: Bad Request Invalid `seconds` property

{
  ok: false,
  status: 400,
  message: 'Code can not be stored more then one day.'
}

400: Bad Request Invalid `service_name` property

{
  ok: false,
  status: 400,
  message: 'Provider name can not be more than 110 characters and it can only consist of letters, numbers and spaces.'
}

400: Bad Request Invalid API key

{
    ok: false,
    status: 401,
    message: 'Invalid API key or user id.'
}

400: Bad Request Invalid phone number

{
    ok: false,
    status: 400,
    message: 'Invalid phone number'
}

Verify the code that the customer has submitted

POST https://textflow.me/api/verify-code

Headers

Name	Type	Description
Content-Type*	String	The value should be "application/json"
Authorization*	String	The value should be "Bearer API_KEY", where API_KEY is the API key that you have registered on the API console

Request Body

Name	Type	Description
phone_number*	String	Phone number to verify the code for, with country prefix. E.g. [phone]
code*	String	Verification code that the user has submited.

400: Bad Request The code has expired

{
  ok: true,
  status: 400,
  message: 'The code has expired. ',
  valid: false,
  valid_code: '214158',
  expires: 1676846234264
}

400: Bad Request The code is invalid.

{
  ok: true,
  status: 400,
  message: 'The code is invalid. ',
  valid: false,
  valid_code: '214158',
  expires: 1676846234264
}

200: OK The code is valid

{
  ok: true,
  status: 200,
  message: 'The code is valid. ',
  valid: true,
  valid_code: '606399',
  expires: 1676848594111
}

400: Bad Request Invalid code format

{ 
    ok: true,
    status: 400,
    message: 'Invalid code',
    valid: false
}

400: Bad Request Invalid phone number

{
  ok: false,
  status: 400,
  message: 'Invalid phone number',
  valid: false
}

400: Bad Request Invalid API key

{
  ok: false,
  status: 401,
  message: 'Invalid API key or user id.',
  valid: false
}

Sending bulk SMS

You can aslo use the TextFlow API to send one SMS to multiple recipients. It is similar to send-sms, but with the array of phone numbers which you want to receive the message.

Send an SMS wih the custom body to multiple phone numbers.

POST https://textflow.me/api/bulk-sms

Headers

Name	Type	Description
Content-Type*		The value should be "application/json"
Authorization*		The value should be "Bearer API_KEY", where API_KEY is the API key that you have registered on the API console

Request Body

Name	Type	Description
phone_numbers*	String Array	Recipient phone numbers, with country prefixes. E.g. ["[phone]", "[phone]", "[phone]"]
text*	String	Message body

200: OK Bulk SMS sending started

{
    ok: true,
    userId: 1,
    status: 200,
    message: "Bulk SMS sending started"
}

400: Bad Request Invalid API key

{ 
    ok: false, 
    status: 400, 
    message: 'Invalid API key' 
}

After starting the "Send bulk SMS job", you can check the number of recipients that have not yet received the SMS, but should receive them in a few minutes or hours, depending on the server load.

Get the number of recipients that should receive your SMS soon

POST https://textflow.me/api/bulk-count

Headers

Name	Type	Description
Content-Type*		The value should be "application/json"
Authorization*		The value should be "Bearer API_KEY", where API_KEY is the API key that you have registered on the API console

200: OK Bulk SMS sending started

{
    ok: true,
    count: 0,
    status: 200,
    message: "Bulk messages successfully counted"
}

Getting help

If you need help installing or using the library, please check the FAQ first, and contact us at [email protected] if you don't find an answer to your question.

If you've found a bug in the API, package or would like new features added, you are also free to contact us!