# API

TextLink API enables developers to send SMS in a very straightforward and user-friendly way. 

## Getting an API key

To be able to use TextLink for sending an SMS or user verification, you first have to [register an account](https://textlinksms.com/signup), after that you are going to get 300 free messages, which you can use to test our API.

After you have registered an account, your API key will be available in the[ API console](https://textlinksms.com/dashboard/api). 

## Sending an SMS

To send an SMS, you can send the following POST request with tool of your choice (like Postman), or use any of the programming languages that support REST API calls.

### Using API

<mark style="color:green;">`POST`</mark> `https://textlinksms.com/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 in  the[ API Console](https://textlinksms.com/dashboard/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                                                                                                                                                                                                                 |
| sim\_card\_id                                   | Number | (Optional) Id of the SIM card that you want to send the message from. Can be found in the [Devices Console](https://textlinksms.com/dashboard/your-devices/overview), by clicking on the device having the SIM card you need |
| custom\_id                                      | String | (Optional) Custom id that you want us to send to you in our [failed message webhook](/webhooks.md#failed-message)                                                                                                            |

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

```javascript
{
  ok: true
}
```

{% endtab %}

{% tab title="200: OK Message sending failed" %}

```javascript
{
  ok: false,
  message: "Reason string"
}
```

{% endtab %}

{% tab title="200: OK Message queued (all senders busy, should be sent soon)" %}

```javascript
{
  ok: true,
  queued: true
}
```

{% endtab %}
{% endtabs %}

### Using our official packages

{% tabs %}
{% tab title="Node.js" %}

<pre class="language-javascript"><code class="lang-javascript">// Firstly, install the helper library using <a data-footnote-ref href="#user-content-fn-1">npm</a> or <a data-footnote-ref href="#user-content-fn-2">yarn</a>

const textlink = require("textlink-sms");
textlink.useKey("YOUR_API_KEY"); // Replace with your API key

<strong>textlink.sendSMS("+381611231234", "Dummy message text...");
</strong></code></pre>

{% endtab %}

{% tab title="TypeScript" %}

<pre class="language-typescript"><code class="lang-typescript">// Firstly, install the helper library using <a data-footnote-ref href="#user-content-fn-1">npm</a> or <a data-footnote-ref href="#user-content-fn-2">yarn</a>

import TextLink from "textlink-sms";
TextLink.useKey("YOUR_API_KEY"); // Replace with your API key

<strong>TextLink.sendSMS("+381611231234", "Dummy message text...");
</strong></code></pre>

{% endtab %}

{% tab title="Python" %}

<pre class="language-python"><code class="lang-python"># Firstly, install the helper library using <a data-footnote-ref href="#user-content-fn-3">pip</a>

import textlink as tl

tl.useKey("YOUR_API_KEY") # Replace with your API key

<strong>result = tl.sendSMS("+381637443242", "Your message text...")
</strong>print(result)
</code></pre>

{% endtab %}
{% endtabs %}

## OTP / Phone verification

Besides [sending SMS](#sending-an-sms), TextLink API can automate one-time-password (OTP) verification for phone numbers. The pricing for OTP verification is the same as sending a normal SMS, but we give OTP messages higher priority and faster delivery times.

The main perk of using our solution for verifying phone number is the removal of need to store the valid codes in your database, since we can verify codes for you.

<figure><img src="/files/WJiwxHN39eeN53cd5ZvA" alt=""><figcaption></figcaption></figure>

To send a verification SMS, you can send the following POST request with tool of your choice (like Postman), or use any of the programming languages that support REST API calls.

### Using API&#x20;

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

#### 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://textlinksms.com/dashboard/api) |

#### Request Body

| Name                                            | Type   | Description                                                                                                                                                                                                                  |
| ----------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| phone\_number<mark style="color:red;">\*</mark> | String | Recipient phone number, with country prefix. E.g. **+11234567890**                                                                                                                                                           |
| service\_name                                   | String | Your name to be shown in the message                                                                                                                                                                                         |
| sim\_card\_id                                   | Number | (Optional) Id of the SIM card that you want to send the message from. Can be found in the [Devices Console](https://textlinksms.com/dashboard/your-devices/overview), by clicking on the device having the SIM card you need |
| custom\_id                                      | String | (Optional) Custom id that you want us to send to you in our [failed message webhook](/webhooks.md#failed-message)                                                                                                            |

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

```javascript
{
  ok: true,
  code: "123456" // The code sent
}
```

{% endtab %}

{% tab title="200: OK Message sending failed" %}

```javascript
{
  ok: false,
  message: "Reason string"
}
```

{% endtab %}
{% endtabs %}

### Using our official packages

{% tabs %}
{% tab title="Node.js" %}

<pre class="language-javascript"><code class="lang-javascript">// Firstly, install the helper library using <a data-footnote-ref href="#user-content-fn-4">npm</a> or <a data-footnote-ref href="#user-content-fn-5">yarn</a>

const textlink = require("textlink-sms");
textlink.useKey("YOUR_API_KEY"); // Replace with your API key

const verificationOptions = {
    service_name: "Tribal"
}; // This is optional

<strong>await textlink.sendVerificationSMS("+11234567890", verificationOptions);
</strong></code></pre>

{% endtab %}

{% tab title="TypeScript" %}

<pre class="language-typescript"><code class="lang-typescript">// Firstly, install the helper library using <a data-footnote-ref href="#user-content-fn-4">npm</a> or <a data-footnote-ref href="#user-content-fn-5">yarn</a>

import TextLink from "textlink-sms";
TextLink.useKey("YOUR_API_KEY");

const verificationOptions = {
    service_name: "Tribal"
}; // This is optional

<strong>await TextLink.sendVerificationSMS("+11234567890", verificationOptions);
</strong></code></pre>

{% endtab %}

{% tab title="Python" %}

<pre class="language-python"><code class="lang-python"># Firstly, install the helper library using <a data-footnote-ref href="#user-content-fn-6">pip</a>

import textlink as tl

tl.useKey("YOUR_API_KEY") # Replace with your API key

<strong>result = tl.sendVerificationSMS("+11234567890", service_name="Tribal")
</strong>print(result)
</code></pre>

{% endtab %}
{% endtabs %}

## Check if the code is valid

After you have sent the one-time-password to your user, you can prompt him to enter the code in your website or application. After he has entered the code, you can use the **`/verify-code`** endpoint, to check if it is valid, without having to store the code locally.&#x20;

### Using API

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

#### 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://textlinksms.com/dashboard/api) |

#### Request Body

| Name                                            | Type   | Description                                    |
| ----------------------------------------------- | ------ | ---------------------------------------------- |
| phone\_number<mark style="color:red;">\*</mark> | String | The phone number that you would like to verify |
| code                                            | String | The OTP code to verify                         |

{% tabs %}
{% tab title="200: OK Code verified successfully" %}

```javascript
{
  ok: true
}
```

{% endtab %}

{% tab title="200: OK Verification failed" %}

```javascript
{
  ok: false,
  message: "Reason string"
}
```

{% endtab %}
{% endtabs %}

### Using our official packages

{% tabs %}
{% tab title="Node.js" %}

<pre class="language-javascript"><code class="lang-javascript"><strong>const result = await textlink.verifyCode("+11234567890", "USER_ENTERED_CODE"); 
</strong>//if `result.ok` is true, then the phone number is verified. 
</code></pre>

{% endtab %}

{% tab title="TypeScript" %}

<pre class="language-typescript"><code class="lang-typescript"><strong>const result = await TextLink.verifyCode("+11234567890", "USER_ENTERED_CODE"); 
</strong>//if `result.ok` is true, then the phone number is verified. 
</code></pre>

{% endtab %}

{% tab title="Python" %}

<pre class="language-python"><code class="lang-python"><strong>result = tl.verifyCode("+11234567890", "USER_ENTERED_CODE")
</strong># if `result.ok` is true, then the phone number is verified.
</code></pre>

{% endtab %}
{% endtabs %}

## Update contact tag

You can use TextLink API to update contact tags. Contact tags allows you to track status of communication with them (e.g. cold/warm), and can be shown in the Chat app. Besides the chat app, they are also received as a part of [Received Message Webhook](/webhooks.md), and each change of tag triggers the [Tag Update Webhook](/webhooks.md).

<figure><img src="/files/DIJagT5LTSOUP62oVCxI" alt=""><figcaption><p>This contact has "VIP" tag</p></figcaption></figure>

### Using API

<mark style="color:green;">`POST`</mark> `https://textlinksms.com/api/update-contect-tag`

#### 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://textlinksms.com/dashboard/api) |

#### Request Body

| Name                                            | Type   | Description                                                |
| ----------------------------------------------- | ------ | ---------------------------------------------------------- |
| phone\_number<mark style="color:red;">\*</mark> | String | The phone number that you would like to update the tag for |
| tag                                             | String | Tag to set for your contact                                |

{% tabs %}
{% tab title="200: OK Code verified successfully" %}

```javascript
{
  ok: true
}
```

{% endtab %}
{% endtabs %}

[^1]: npm install textlink-sms

[^2]: yarn add textlink-sms

[^3]: pip install textlink

[^4]: ```
    npm install textlink-sms
    ```

[^5]: ```
    yarn addtextlink-sms
    ```

[^6]: ```
    pip install textlink
    ```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.textlinksms.com/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.