Introduction

REST API documentation.

Base URL: https://app.gotsms.org

Use this API to check your balance, rent numbers, manage your rents and read incoming SMS.

All timestamps are in UTC, in ISO 8601 format.

Authentication for protected endpoints is done via `Authorization: Bearer {token}` header.
You can generate token in your profile page after enabling API access.

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {YOUR_API_TOKEN}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

Enable API access, then click Generate Token.

API

GotSMS API methods.

Pricelist

Get public pricelist

The icon field is returned only when the request is sent without a token.

Example request:

curl --request GET \
    --get "https://app.gotsms.org/api/pricelist" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://app.gotsms.org/api/pricelist"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.org/api/pricelist';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "success": true,
    "data": [
        {
            "id": "9b1f8c3e-1c2a-4f5b-8d7e-0a1b2c3d4e5f",
            "name": "Telegram",
            "slug": "telegram",
            "icon": "https://example.com/icons/telegram.png",
            "plans": [
                {
                    "service_name": "Telegram",
                    "period": 1,
                    "period_type": "day",
                    "period_type_label": "day",
                    "duration_translation": "1 day",
                    "price": 1,
                    "renew_price": 1,
                    "country": "USA",
                    "billing_type": "duration"
                }
            ]
        },
        {
            "id": "2c7d9a41-5e6f-4a8b-9c0d-1e2f3a4b5c6d",
            "name": "WhatsApp",
            "slug": "whatsapp",
            "icon": null,
            "plans": [
                {
                    "service_name": "WhatsApp",
                    "period": 1,
                    "period_type": "month",
                    "period_type_label": "month",
                    "duration_translation": "1 month",
                    "price": 4.99,
                    "renew_price": 4.99,
                    "country": "USA",
                    "billing_type": "duration"
                }
            ]
        }
    ]
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Rents

List cellular carriers

Example request:

curl --request GET \
    --get "https://app.gotsms.org/api/carriers" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://app.gotsms.org/api/carriers"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.org/api/carriers';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "success": true,
    "data": [
        {
            "id": "uuid",
            "name": "T-Mobile"
        }
    ]
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Get rent plans

requires authentication

By default only plans with numbers in stock are returned. Pass include_unavailable=1 to also get sold-out plans: they are marked is_available = false and listed after the available ones.

Example request:

curl --request GET \
    --get "https://app.gotsms.org/api/rents/plans" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://app.gotsms.org/api/rents/plans"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.org/api/rents/plans';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "success": true,
    "data": [
        {
            "id": "uuid",
            "service": {
                "id": "uuid",
                "name": "Telegram"
            },
            "country": {
                "id": "uuid",
                "name": "USA"
            },
            "billing_type": "duration",
            "duration_type": "day",
            "duration_in_type": 1,
            "duration_in_minutes": 1440,
            "duration_translation": "1 day",
            "price": 1,
            "renew_price": 1,
            "is_available": true
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 25,
        "total": 1
    }
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

GET api/rents/plans

Headers

Authorization

Bearer {YOUR_API_TOKEN}

Content-Type

application/json

Accept

application/json

Query Parameters

service_id string optional

Filter by service UUID.

country_id string optional

Filter by country UUID.

duration_type string optional

Filter by duration type.

Must be one of:

min
hour
day
week
month
year

billing_type string optional

Filter by billing type.

Must be one of:

sms
duration

search string optional

Search in service name.

per_page integer optional

Pagination size (max 100).

include_unavailable boolean optional true false

Also return plans that are currently sold out.

List user rents

requires authentication

Example request:

curl --request GET \
    --get "https://app.gotsms.org/api/rents" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://app.gotsms.org/api/rents"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.org/api/rents';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "success": true,
    "data": [
        {
            "id": "uuid",
            "service": {
                "id": "uuid",
                "name": "Telegram"
            },
            "plan": {
                "id": "uuid",
                "billing_type": "duration",
                "duration_type": "day",
                "duration_in_type": 1,
                "duration_translation": "1 day",
                "price": 1,
                "renew_price": 1
            },
            "phone": "+1 202-555-0123",
            "price": 1,
            "status": "active",
            "is_included_for_next_renewal": false,
            "active_from": "2026-03-11T12:00:00+00:00",
            "active_till": "2026-03-12T12:00:00+00:00",
            "wake_from": null,
            "wake_till": null,
            "can_wake_up": true,
            "notes": "Call customer after activation",
            "transition_options": [
                {
                    "plan_id": "uuid",
                    "duration_type": "day",
                    "duration_in_type": 7,
                    "duration_translation": "7 days",
                    "price": 5
                }
            ]
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 20,
        "total": 1
    }
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

GET api/rents

Headers

Authorization

Bearer {YOUR_API_TOKEN}

Content-Type

application/json

Accept

application/json

Query Parameters

status string optional

Filter by status.

Must be one of:

active
finished

service string optional

Service name search.

phone string optional

Phone search.

notes string optional

Search in rent notes.

per_page integer optional

Pagination size (max 100).

page integer optional

Page number, starting from 1.

List services that can be added to a rent

requires authentication

Services the same number can additionally receive SMS for. Only active rents support it; unavailable services are listed with is_available = false.

Example request:

curl --request GET \
    --get "https://app.gotsms.org/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/services" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://app.gotsms.org/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/services"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.org/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/services';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "success": true,
    "data": [
        {
            "service_id": "uuid",
            "name": "WhatsApp",
            "price": 2,
            "base_price": 1,
            "add_service_markup": 1,
            "is_available": true
        }
    ]
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

GET api/rents/{rent_id}/services

Headers

Authorization

Bearer {YOUR_API_TOKEN}

Content-Type

application/json

Accept

application/json

URL Parameters

rent_id string

Rent UUID. Example: 9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f

Create new rent

requires authentication

Example request:

curl --request POST \
    "https://app.gotsms.org/api/rents" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"plan_id\": null
}"

const url = new URL(
    "https://app.gotsms.org/api/rents"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "plan_id": null
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.org/api/rents';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'plan_id' => null,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201):


{
    "success": true,
    "message": "Rent created successfully.",
    "data": {
        "id": "uuid",
        "service": {
            "id": "uuid",
            "name": "Telegram"
        },
        "plan": {
            "id": "uuid",
            "billing_type": "duration",
            "duration_type": "day",
            "duration_in_type": 1,
            "duration_translation": "1 day",
            "price": 1,
            "renew_price": 1
        },
        "phone": "+1 202-555-0123",
        "price": 1,
        "status": "active",
        "is_included_for_next_renewal": false,
        "active_from": "2026-03-11T12:00:00+00:00",
        "active_till": "2026-03-12T12:00:00+00:00",
        "wake_from": null,
        "wake_till": null,
        "can_wake_up": true,
        "notes": null,
        "transition_options": []
    }
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

POST api/rents

Headers

Authorization

Bearer {YOUR_API_TOKEN}

Content-Type

application/json

Accept

application/json

Body Parameters

plan_id string

Plan UUID to rent.

area_code string optional

Area code the number must have. The request fails when no such number is available.

cellular_carrier_id string optional

UUID of the cellular carrier the number must have (see GET /api/carriers). The request fails when no such number is available.

Create several rents at once

requires authentication

Rents up to 25 numbers of one plan in a single request. When fewer numbers are available, the ones that could be rented are returned.

Example request:

curl --request POST \
    "https://app.gotsms.org/api/rents/bulk" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"plan_id\": \"No-example\",
    \"quantity\": 5
}"

const url = new URL(
    "https://app.gotsms.org/api/rents/bulk"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "plan_id": "No-example",
    "quantity": 5
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.org/api/rents/bulk';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'plan_id' => 'No-example',
            'quantity' => 5,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201):


{
    "success": true,
    "message": "Rented 2 of 3 numbers.",
    "data": [
        {
            "id": "uuid",
            "service": {
                "id": "uuid",
                "name": "Telegram"
            },
            "plan": {
                "id": "uuid",
                "billing_type": "duration",
                "duration_type": "day",
                "duration_in_type": 1,
                "duration_translation": "1 day",
                "price": 1,
                "renew_price": 1
            },
            "phone": "+1 202-555-0123",
            "price": 1,
            "status": "active",
            "is_included_for_next_renewal": false,
            "active_from": "2026-03-11T12:00:00+00:00",
            "active_till": "2026-03-12T12:00:00+00:00",
            "wake_from": null,
            "wake_till": null,
            "can_wake_up": true,
            "notes": null,
            "transition_options": []
        }
    ],
    "meta": {
        "requested": 3,
        "rented": 2,
        "failed": 0
    }
}

Example response (422):


{
    "success": false,
    "message": "No number available for this service.",
    "meta": {
        "requested": 3,
        "rented": 0,
        "failed": 0
    }
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

POST api/rents/bulk

Headers

Authorization

Bearer {YOUR_API_TOKEN}

Content-Type

application/json

Accept

application/json

Body Parameters

plan_id string

Plan UUID to rent. Must be a valid UUID. The id of an existing record in the plans table. Example: No-example

quantity integer

How many numbers to rent at once, from 1 to 25. Must be at least 1. Must not be greater than 25. Example: 5

area_code string optional

Area code the number must have. The request fails when no such number is available. Must match the regex /^\d{2,6}$/.

cellular_carrier_id string optional

UUID of the cellular carrier the number must have (see GET /api/carriers). The request fails when no such number is available. Must be a valid UUID. The id of an existing record in the cellular_carriers table.

Transition rent to another plan

requires authentication

Moves the rent to another plan. The plans a rent can move to are returned for it in transition_options by GET /api/rents. The new period is charged at the plan price and starts when the period already paid for ends.

Example request:

curl --request POST \
    "https://app.gotsms.org/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/transition" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"plan_id\": null
}"

const url = new URL(
    "https://app.gotsms.org/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/transition"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "plan_id": null
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.org/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/transition';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'plan_id' => null,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "success": true,
    "message": "Plan transitioned successfully.",
    "data": {
        "id": "uuid",
        "status": "active"
    }
}

Example response (422):


{
    "success": false,
    "message": "Transition to selected plan is unavailable."
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

POST api/rents/{rent_id}/transition

Headers

Authorization

Bearer {YOUR_API_TOKEN}

Content-Type

application/json

Accept

application/json

URL Parameters

rent_id string

Rent UUID. Example: 9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f

Body Parameters

plan_id string

Target plan UUID: a plan_id from transition_options of this rent in GET /api/rents.

Toggle auto renewal

requires authentication

With auto-renewal on, the renew price is charged at the moment the paid period ends and the next period starts right away, without a gap. If the balance does not cover it, the rent ends. A rent that has already ended cannot be switched back on.

Example request:

curl --request POST \
    "https://app.gotsms.org/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/renewal/toggle" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://app.gotsms.org/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/renewal/toggle"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.org/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/renewal/toggle';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "success": true,
    "message": "Auto renewal enabled.",
    "data": {
        "id": "uuid",
        "is_included_for_next_renewal": true
    }
}

Example response (422):


{
    "success": false,
    "message": "Failed to toggle auto renewal."
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

POST api/rents/{rent_id}/renewal/toggle

Headers

Authorization

Bearer {YOUR_API_TOKEN}

Content-Type

application/json

Accept

application/json

URL Parameters

rent_id string

Rent UUID. Example: 9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f

Refund rent

requires authentication

Example request:

curl --request POST \
    "https://app.gotsms.org/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/refund" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://app.gotsms.org/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/refund"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.org/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/refund';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "success": true,
    "message": "Rent has been refunded successfully.",
    "data": {
        "id": "uuid",
        "status": "finished"
    }
}

Example response (422):


{
    "success": false,
    "message": "Refund not available for this rent."
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

POST api/rents/{rent_id}/refund

Headers

Authorization

Bearer {YOUR_API_TOKEN}

Content-Type

application/json

Accept

application/json

URL Parameters

rent_id string

Rent UUID. Example: 9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f

Add a service to a rent

requires authentication

Adds one more service to the same number as a separate rent with the same duration, charged at the price from GET /api/rents/{rent_id}/services.

Example request:

curl --request POST \
    "https://app.gotsms.org/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/services" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"service_id\": \"No-example\"
}"

const url = new URL(
    "https://app.gotsms.org/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/services"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "service_id": "No-example"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.org/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/services';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'service_id' => 'No-example',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (201):


{
    "success": true,
    "message": "Service added to the number.",
    "data": {
        "id": "uuid",
        "status": "active"
    }
}

Example response (422):


{
    "success": false,
    "message": "Adding a service is not available for this number."
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

POST api/rents/{rent_id}/services

Headers

Authorization

Bearer {YOUR_API_TOKEN}

Content-Type

application/json

Accept

application/json

URL Parameters

rent_id string

Rent UUID. Example: 9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f

Body Parameters

service_id string

Service UUID from GET /api/rents/{rent_id}/services. Must be a valid UUID. The id of an existing record in the services table. Example: No-example

Account

Get account balance

requires authentication

Example request:

curl --request GET \
    --get "https://app.gotsms.org/api/account" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://app.gotsms.org/api/account"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.org/api/account';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "success": true,
    "data": {
        "balance": 125.5
    }
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Services

Get services

requires authentication

Includes services whose numbers are sold out right now, marked is_available = false.

Example request:

curl --request GET \
    --get "https://app.gotsms.org/api/services" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://app.gotsms.org/api/services"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.org/api/services';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "success": true,
    "data": [
        {
            "id": "uuid",
            "name": "Telegram",
            "is_available": true
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 25,
        "total": 1
    }
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

GET api/services

Headers

Authorization

Bearer {YOUR_API_TOKEN}

Content-Type

application/json

Accept

application/json

Query Parameters

search string optional

Search in service name.

per_page integer optional

Pagination size (max 100).

Messages

List all SMS messages across all rents

requires authentication

Example request:

curl --request GET \
    --get "https://app.gotsms.org/api/messages" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://app.gotsms.org/api/messages"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.org/api/messages';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "success": true,
    "data": [
        {
            "id": "uuid",
            "rent_id": "uuid",
            "service": {
                "id": "uuid",
                "name": "Telegram"
            },
            "phone": "+1 202-555-0123",
            "from": "+18001234567",
            "to": "+1 202-555-0123",
            "body": "Your verification code is 123456",
            "code": "123456",
            "received_at": "2026-03-11T12:00:00+00:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 20,
        "total": 1
    }
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

GET api/messages

Headers

Authorization

Bearer {YOUR_API_TOKEN}

Content-Type

application/json

Accept

application/json

Query Parameters

service_id string optional

Filter by service UUID. Must be a valid UUID.

phone string optional

Phone search. Must not be greater than 32 characters.

per_page integer optional

Pagination size (max 100). Must be at least 1. Must not be greater than 100.

page integer optional

Page number, starting from 1.

List unread SMS messages

requires authentication

Unread SMS received in the last 30 days, newest first.

Example request:

curl --request GET \
    --get "https://app.gotsms.org/api/messages/unread" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://app.gotsms.org/api/messages/unread"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.org/api/messages/unread';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "success": true,
    "data": [
        {
            "id": "uuid",
            "rent_id": "uuid",
            "service": {
                "id": "uuid",
                "name": "Telegram"
            },
            "phone": "+1 202-555-0123",
            "from": "+18001234567",
            "to": "+1 202-555-0123",
            "body": "Your verification code is 123456",
            "code": "123456",
            "received_at": "2026-03-11T12:00:00+00:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 20,
        "total": 1
    }
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

GET api/messages/unread

Headers

Authorization

Bearer {YOUR_API_TOKEN}

Content-Type

application/json

Accept

application/json

Query Parameters

service_id string optional

Filter by service UUID.

rent_id string optional

Filter by rent UUID.

phone string optional

Phone search.

per_page integer optional

Pagination size (max 100).

mark_as_read boolean optional true false

Mark returned messages as read.

page integer optional

Page number, starting from 1.

Numbers

List all active numbers

requires authentication

Every number currently rented by the account, without pagination.

Example request:

curl --request GET \
    --get "https://app.gotsms.org/api/numbers" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://app.gotsms.org/api/numbers"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.org/api/numbers';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "success": true,
    "data": [
        {
            "id": "uuid",
            "phone": "+1 202-555-0123",
            "service": "Telegram",
            "active_till": "2026-03-12T12:00:00+00:00",
            "is_included_for_next_renewal": true,
            "notes": "Farm A"
        }
    ],
    "meta": {
        "total": 1
    }
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Wake up a rented number

requires authentication

Example request:

curl --request POST \
    "https://app.gotsms.org/api/numbers/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/wake-up" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://app.gotsms.org/api/numbers/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/wake-up"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.org/api/numbers/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/wake-up';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "success": true,
    "message": "Wake up request sent.",
    "data": {
        "rent_id": "uuid",
        "status": "in_queue",
        "active_from": "2026-03-11T12:00:00+00:00",
        "active_till": "2026-03-12T12:00:00+00:00",
        "wake_from": "2026-03-11T12:03:00+00:00",
        "wake_till": "2026-03-11T12:08:00+00:00",
        "online_till": "2026-03-12T12:00:00+00:00",
        "wakeup_time_left_seconds": 480,
        "online_time_left_seconds": 86400,
        "can_wake_up": false
    }
}

Example response (422):


{
    "success": false,
    "message": "The rental has already ended."
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

POST api/numbers/{rent_id}/wake-up

Headers

Authorization

Bearer {YOUR_API_TOKEN}

Content-Type

application/json

Accept

application/json

URL Parameters

rent_id string

Rent UUID. Example: 9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f

Get SMS messages for a rent

requires authentication

Example request:

curl --request GET \
    --get "https://app.gotsms.org/api/numbers/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/messages" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://app.gotsms.org/api/numbers/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/messages"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.org/api/numbers/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/messages';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "success": true,
    "data": [
        {
            "id": "uuid",
            "from": "+18001234567",
            "to": "+1 202-555-0123",
            "body": "Your verification code is 123456",
            "code": "123456",
            "received_at": "2026-03-11T12:00:00+00:00"
        }
    ],
    "meta": {
        "next_before_id": "uuid",
        "count": 1
    }
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

GET api/numbers/{rent_id}/messages

Headers

Authorization

Bearer {YOUR_API_TOKEN}

Content-Type

application/json

Accept

application/json

URL Parameters

rent_id string

Rent UUID. Example: 9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f

Query Parameters

limit integer optional

Number of records (max 100).

before_id string optional

Return messages older than the message with this id. Pass meta.next_before_id from the previous response to get the next page.

Get notes for a rented number

requires authentication

Example request:

curl --request GET \
    --get "https://app.gotsms.org/api/numbers/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/notes" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://app.gotsms.org/api/numbers/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/notes"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.org/api/numbers/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/notes';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "success": true,
    "data": {
        "rent_id": "uuid",
        "notes": "Call customer after activation"
    }
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

GET api/numbers/{rent_id}/notes

Headers

Authorization

Bearer {YOUR_API_TOKEN}

Content-Type

application/json

Accept

application/json

URL Parameters

rent_id string

Rent UUID. Example: 9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f

Update notes for a rented number

requires authentication

Replaces the current note.

Example request:

curl --request PUT \
    "https://app.gotsms.org/api/numbers/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/notes" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"notes\": \"Call customer after activation\"
}"

const url = new URL(
    "https://app.gotsms.org/api/numbers/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/notes"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "notes": "Call customer after activation"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.org/api/numbers/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/notes';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'notes' => 'Call customer after activation',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "success": true,
    "message": "Notes updated successfully.",
    "data": {
        "rent_id": "uuid",
        "notes": "Call customer after activation"
    }
}

Example response (422, Validation failed):


{
    "message": "The notes field must contain plain text only. HTML is not allowed.",
    "errors": {
        "notes": [
            "The notes field must contain plain text only. HTML is not allowed."
        ]
    }
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

PUT api/numbers/{rent_id}/notes

Headers

Authorization

Bearer {YOUR_API_TOKEN}

Content-Type

application/json

Accept

application/json

URL Parameters

rent_id string

Rent UUID. Example: 9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f

Body Parameters

notes string

Plain-text note, max 1000 characters. HTML is rejected. Send null to clear the note. Example: Call customer after activation

Get number queue/wakeup/online status

requires authentication

Example request:

curl --request GET \
    --get "https://app.gotsms.org/api/numbers/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/status" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://app.gotsms.org/api/numbers/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/status"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.org/api/numbers/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/status';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "success": true,
    "data": {
        "rent_id": "uuid",
        "status": "active",
        "active_from": "2026-03-11T12:00:00+00:00",
        "active_till": "2026-03-12T12:00:00+00:00",
        "wake_from": "2026-03-11T12:00:00+00:00",
        "wake_till": "2026-03-11T12:05:00+00:00",
        "online_till": "2026-03-12T12:00:00+00:00",
        "wakeup_time_left_seconds": 120,
        "online_time_left_seconds": 86220,
        "can_wake_up": false
    }
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

GET api/numbers/{rent_id}/status

Headers

Authorization

Bearer {YOUR_API_TOKEN}

Content-Type

application/json

Accept

application/json

URL Parameters

rent_id string

Rent UUID. Example: 9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f

Introduction

Authenticating requests

API

Pricelist

Get public pricelist

Request

Headers

Rents

List cellular carriers

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Get rent plans

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Query Parameters

List user rents

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Query Parameters

List services that can be added to a rent

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

URL Parameters

Create new rent

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Body Parameters

Create several rents at once

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Body Parameters

Transition rent to another plan

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

URL Parameters

Body Parameters

Toggle auto renewal

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

URL Parameters

Refund rent

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

URL Parameters

Add a service to a rent

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

URL Parameters

Body Parameters

Account

Get account balance

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Services

Get services

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Query Parameters

Messages

List all SMS messages across all rents

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Query Parameters

List unread SMS messages

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Query Parameters

Numbers

List all active numbers

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Wake up a rented number

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

URL Parameters

Get SMS messages for a rent

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

URL Parameters

Query Parameters

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request