# REST 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](https://textflow.me), 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](https://textflow.me/api). 

## Sending an SMS

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

<mark style="color:green;">`POST`</mark> `https://textflow.me/api/send-sms`

#### Headers

| Name                                            | Type | Description                                                                                                                                 |
| ----------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-Type<mark style="color:red;">\*</mark>  |      | The value should be "application/json"                                                                                                      |
| Authorization<mark style="color:red;">\*</mark> |      | The value should be "Bearer API\_KEY", where API\_KEY is the API key that you have registered on the [API console](https://textflow.me/api) |

#### Request Body

| Name                                            | Type   | Description                                                        |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------ |
| phone\_number<mark style="color:red;">\*</mark> | String | Recipient phone number, with country prefix. E.g. **+11234567890** |
| text<mark style="color:red;">\*</mark>          | String | Message body                                                       |

{% tabs %}
{% tab title="200: OK Message successfully sent" %}

```javascript
{
  ok: true,
  status: 200,
  message: 'Message sent successfully',
  data: {
    to: '+381690156360',
    content: 'Dummy message text...',
    country_code: 'Serbia',
    price: 0.15,
    timestamp: 1676842652256
  }
}
```

{% endtab %}

{% tab title="400: Bad Request Invalid API key" %}

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

{% endtab %}

{% tab title="400: Bad Request Invalid phone number" %}

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

{% endtab %}
{% endtabs %}

## User verification

There are two endpoints that you should call in the user verification process.&#x20;

`/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.&#x20;

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.&#x20;

## Send phone number verification SMS to your customers

<mark style="color:green;">`POST`</mark> `https://textflow.me/api/send-code`

#### Headers

| Name                                            | Type   | Description                                                                                                                                 |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-Type<mark style="color:red;">\*</mark>  | String | The value should be "application/json"                                                                                                      |
| Authorization<mark style="color:red;">\*</mark> | String | The value should be "Bearer API\_KEY", where API\_KEY is the API key that you have registered on the [API console](https://textflow.me/api) |

#### Request Body

| Name                                            | Type    | Description                                                                                                                                                                                                                 |
| ----------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| phone\_number<mark style="color:red;">\*</mark> | String  | Phone number to verify, with country prefix. E.g. **+11234567890**                                                                                                                                                          |
| service\_name                                   | String  | <p>What the user will see in the verification message. If the <code>service\_name</code> is "Guest", he would get the following message:</p><p><em>Your verification code for Guest is: CODE</em></p><p>Default is none</p> |
| seconds                                         | Integer | How many seconds is the code valid for. Default is 10 minutes. Maximum is one day.                                                                                                                                          |

{% tabs %}
{% tab title="200: OK Verification code successfully sent" %}

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

{% endtab %}

{% tab title="400: Bad Request Invalid `seconds` property" %}

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

{% endtab %}

{% tab title="400: Bad Request Invalid `service_name` property" %}

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

{% endtab %}

{% tab title="400: Bad Request Invalid API key" %}

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

{% endtab %}

{% tab title="400: Bad Request Invalid phone number" %}

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

{% endtab %}
{% endtabs %}

## Verify the code that the customer has submitted

<mark style="color:green;">`POST`</mark> `https://textflow.me/api/verify-code`

#### Headers

| Name                                            | Type   | Description                                                                                                                                 |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-Type<mark style="color:red;">\*</mark>  | String | The value should be "application/json"                                                                                                      |
| Authorization<mark style="color:red;">\*</mark> | String | The value should be "Bearer API\_KEY", where API\_KEY is the API key that you have registered on the [API console](https://textflow.me/api) |

#### Request Body

| Name                                            | Type   | Description                                                                     |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------------------- |
| phone\_number<mark style="color:red;">\*</mark> | String | Phone number to verify the code for, with country prefix. E.g. **+11234567890** |
| code<mark style="color:red;">\*</mark>          | String | Verification code that the user has submited.                                   |

{% tabs %}
{% tab title="400: Bad Request The code has expired" %}

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

{% endtab %}

{% tab title="400: Bad Request The code is invalid." %}

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

{% endtab %}

{% tab title="200: OK The code is valid" %}

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

{% endtab %}

{% tab title="400: Bad Request Invalid code format" %}

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

{% endtab %}

{% tab title="400: Bad Request Invalid phone number" %}

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

{% endtab %}

{% tab title="400: Bad Request Invalid API key" %}

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

{% endtab %}
{% endtabs %}

## 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.&#x20;

## Send an SMS wih the custom body to multiple phone numbers.&#x20;

<mark style="color:green;">`POST`</mark> `https://textflow.me/api/bulk-sms`

#### Headers

| Name                                            | Type | Description                                                                                                                                 |
| ----------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-Type<mark style="color:red;">\*</mark>  |      | The value should be "application/json"                                                                                                      |
| Authorization<mark style="color:red;">\*</mark> |      | The value should be "Bearer API\_KEY", where API\_KEY is the API key that you have registered on the [API console](https://textflow.me/api) |

#### Request Body

| Name                                             | Type         | Description                                                                                                |
| ------------------------------------------------ | ------------ | ---------------------------------------------------------------------------------------------------------- |
| phone\_numbers<mark style="color:red;">\*</mark> | String Array | Recipient phone numbers, with country prefixes. E.g. **\["+11234567891", "+11234567892", "+11234567893"]** |
| text<mark style="color:red;">\*</mark>           | String       | Message body                                                                                               |

{% tabs %}
{% tab title="200: OK Bulk SMS sending started" %}

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

{% endtab %}

{% tab title="400: Bad Request Invalid API key" %}

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

{% endtab %}
{% endtabs %}

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.&#x20;

## Get the number of recipients that should receive your SMS soon

<mark style="color:green;">`POST`</mark> `https://textflow.me/api/bulk-count`

#### Headers

| Name                                            | Type | Description                                                                                                                                 |
| ----------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-Type<mark style="color:red;">\*</mark>  |      | The value should be "application/json"                                                                                                      |
| Authorization<mark style="color:red;">\*</mark> |      | The value should be "Bearer API\_KEY", where API\_KEY is the API key that you have registered on the [API console](https://textflow.me/api) |

{% tabs %}
{% tab title="200: OK Bulk SMS sending started" %}

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

{% endtab %}
{% endtabs %}

## Getting help

If you need help installing or using the library, please check the [FAQ](https://textflow.me/api) first, and contact us at [support@textflow.me](mailto://support@textflow.me) 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!