MENU navbar-image

Introduction

REST API documentation.

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.

Webhooks push SMS and rent events to your server as soon as they happen: see the Webhooks section.

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.com/api/pricelist" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://app.gotsms.com/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.com/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"
                }
            ]
        }
    ]
}
 

Request   

GET api/pricelist

Headers

Content-Type        

application/json

Accept        

application/json

Rents

List cellular carriers

Example request:
curl --request GET \
    --get "https://app.gotsms.com/api/carriers" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://app.gotsms.com/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.com/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"
        }
    ]
}
 

Request   

GET api/carriers

Headers

Content-Type        

application/json

Accept        

application/json

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.com/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.com/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.com/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
    }
}
 

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    

Also return plans that are currently sold out.

Get area codes on sale

requires authentication

Area codes a number of the plan can be rented with right now, grouped by US state, the same list the area code picker shows in the cabinet. Pass one area_code, or a state for any of its area codes, to POST /api/rents or POST /api/rents/bulk.

Example request:
curl --request GET \
    --get "https://app.gotsms.com/api/rents/area-codes?plan_id=4b1e7c2a-8f3d-4a6b-9c0e-5d2f1a7b3c8e" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://app.gotsms.com/api/rents/area-codes"
);

const params = {
    "plan_id": "4b1e7c2a-8f3d-4a6b-9c0e-5d2f1a7b3c8e",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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.com/api/rents/area-codes';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'plan_id' => '4b1e7c2a-8f3d-4a6b-9c0e-5d2f1a7b3c8e',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "success": true,
    "data": [
        {
            "state": "California",
            "area_codes": [
                {
                    "area_code": "213",
                    "city": "Los Angeles",
                    "carriers": [
                        "AT&T",
                        "T-Mobile"
                    ]
                },
                {
                    "area_code": "415",
                    "city": null,
                    "carriers": [
                        "Verizon"
                    ]
                }
            ]
        }
    ]
}
 

Example response (422):


{
    "success": false,
    "message": "This tariff is not available for rent."
}
 

Request   

GET api/rents/area-codes

Headers

Authorization        

Bearer {YOUR_API_TOKEN}

Content-Type        

application/json

Accept        

application/json

Query Parameters

plan_id   string     

Plan UUID from GET /api/rents/plans. Must be a valid UUID. Example: 4b1e7c2a-8f3d-4a6b-9c0e-5d2f1a7b3c8e

cellular_carrier_id   string  optional    

Only area codes with numbers of this cellular carrier (see GET /api/carriers). Must be a valid UUID.

List user rents

requires authentication

Example request:
curl --request GET \
    --get "https://app.gotsms.com/api/rents" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://app.gotsms.com/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.com/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,
            "is_archived": 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
    }
}
 

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.com/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.com/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.com/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
        }
    ]
}
 

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.com/api/rents" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"plan_id\": \"4b1e7c2a-8f3d-4a6b-9c0e-5d2f1a7b3c8e\"
}"
const url = new URL(
    "https://app.gotsms.com/api/rents"
);

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

let body = {
    "plan_id": "4b1e7c2a-8f3d-4a6b-9c0e-5d2f1a7b3c8e"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.com/api/rents';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'plan_id' => '4b1e7c2a-8f3d-4a6b-9c0e-5d2f1a7b3c8e',
        ],
    ]
);
$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,
        "is_archived": 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": []
    }
}
 

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. Example: 4b1e7c2a-8f3d-4a6b-9c0e-5d2f1a7b3c8e

area_code   string  optional    

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

state   string  optional    

US state the number must be from, for example California: a number with any area code of that state is rented. The states and area codes on sale for a plan are returned by GET /api/rents/area-codes. Cannot be combined with area_code. 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.com/api/rents/bulk" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"plan_id\": \"4b1e7c2a-8f3d-4a6b-9c0e-5d2f1a7b3c8e\",
    \"quantity\": 5
}"
const url = new URL(
    "https://app.gotsms.com/api/rents/bulk"
);

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

let body = {
    "plan_id": "4b1e7c2a-8f3d-4a6b-9c0e-5d2f1a7b3c8e",
    "quantity": 5
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.com/api/rents/bulk';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'plan_id' => '4b1e7c2a-8f3d-4a6b-9c0e-5d2f1a7b3c8e',
            '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,
            "is_archived": 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
    }
}
 

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. Example: 4b1e7c2a-8f3d-4a6b-9c0e-5d2f1a7b3c8e

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}$/.

state   string  optional    

US state the number must be from, for example California: a number with any area code of that state is rented. The states and area codes on sale for a plan are returned by GET /api/rents/area-codes. Cannot be combined with area_code. The request fails when no such number is available. Must not be greater than 64 characters.

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.

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.com/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\": \"4b1e7c2a-8f3d-4a6b-9c0e-5d2f1a7b3c8e\"
}"
const url = new URL(
    "https://app.gotsms.com/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": "4b1e7c2a-8f3d-4a6b-9c0e-5d2f1a7b3c8e"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.com/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' => '4b1e7c2a-8f3d-4a6b-9c0e-5d2f1a7b3c8e',
        ],
    ]
);
$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."
}
 

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. Example: 4b1e7c2a-8f3d-4a6b-9c0e-5d2f1a7b3c8e

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.com/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.com/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.com/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."
}
 

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

Pay ahead for a rent

requires authentication

Pays for several periods of the rent's current plan at once, at its renew price per period. The new time starts when the time already paid for ends, so active_till moves forward by all the periods together. Auto-renewal is not changed.

Example request:
curl --request POST \
    "https://app.gotsms.com/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/prepay" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"periods\": 3
}"
const url = new URL(
    "https://app.gotsms.com/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/prepay"
);

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

let body = {
    "periods": 3
};

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

Example response (200):


{
    "success": true,
    "message": "The number is paid ahead.",
    "data": {
        "id": "uuid",
        "status": "active",
        "active_till": "2026-12-23T12:00:00+00:00"
    }
}
 

Example response (422):


{
    "success": false,
    "message": "Not enough balance to pay ahead."
}
 

Request   

POST api/rents/{rent_id}/prepay

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

periods   integer     

How many periods of the rent's current plan to pay for, from 1 to 30. Together they may reach at most one year past the time already paid for. Must be at least 1. Must not be greater than 30. Example: 3

Refund rent

requires authentication

Example request:
curl --request POST \
    "https://app.gotsms.com/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.com/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.com/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."
}
 

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

Archive rent

requires authentication

Moves an active number to the archive and turns its auto-renewal off. The rental keeps running until active_till and SMS keep arriving; the rent is returned with is_archived = true.

Example request:
curl --request POST \
    "https://app.gotsms.com/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/archive" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://app.gotsms.com/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/archive"
);

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.com/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/archive';
$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": "The number has been moved to the archive.",
    "data": {
        "id": "uuid",
        "status": "active",
        "is_included_for_next_renewal": false,
        "is_archived": true
    }
}
 

Example response (422):


{
    "success": false,
    "message": "This number cannot be moved to the archive."
}
 

Request   

POST api/rents/{rent_id}/archive

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

Unarchive rent

requires authentication

Takes an archived number that is still running back out of the archive. Auto-renewal stays off until you turn it on with POST /api/rents/{rent_id}/renewal/toggle.

Example request:
curl --request POST \
    "https://app.gotsms.com/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/unarchive" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://app.gotsms.com/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/unarchive"
);

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.com/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/unarchive';
$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": "The number is back among the active ones.",
    "data": {
        "id": "uuid",
        "status": "active",
        "is_included_for_next_renewal": false,
        "is_archived": false
    }
}
 

Example response (422):


{
    "success": false,
    "message": "This number is not in the archive."
}
 

Request   

POST api/rents/{rent_id}/unarchive

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.com/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\": \"7c2d9e4f-3a1b-4c5d-8e6f-0a9b8c7d6e5f\"
}"
const url = new URL(
    "https://app.gotsms.com/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": "7c2d9e4f-3a1b-4c5d-8e6f-0a9b8c7d6e5f"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.com/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' => '7c2d9e4f-3a1b-4c5d-8e6f-0a9b8c7d6e5f',
        ],
    ]
);
$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."
}
 

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. Example: 7c2d9e4f-3a1b-4c5d-8e6f-0a9b8c7d6e5f

Transfer a rent to another account

requires authentication

Hands the number over to another GotSMS account, the same as Transfer in the cabinet: the recipient becomes the owner and receives its SMS. Only a rent that has not ended can be transferred. A transfer cannot be undone. Turn on number transfer through the API in the API settings of your account first: it gives you the secret phrase this request needs.

Example request:
curl --request POST \
    "https://app.gotsms.com/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/transfer" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"email\": \"[email protected]\",
    \"secret\": \"q7Vd2LxN9pRt4KwZ8mHc3JsB6fYa1UeG5nTb0XiQ2oLv7DkE\"
}"
const url = new URL(
    "https://app.gotsms.com/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/transfer"
);

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

let body = {
    "email": "[email protected]",
    "secret": "q7Vd2LxN9pRt4KwZ8mHc3JsB6fYa1UeG5nTb0XiQ2oLv7DkE"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.com/api/rents/9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f/transfer';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'email' => '[email protected]',
            'secret' => 'q7Vd2LxN9pRt4KwZ8mHc3JsB6fYa1UeG5nTb0XiQ2oLv7DkE',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "success": true,
    "message": "Rent transferred successfully."
}
 

Example response (403):


{
    "success": false,
    "message": "Number transfer through the API is turned off. Turn it on in the API settings of your account."
}
 

Example response (422):


{
    "success": false,
    "message": "The secret phrase is incorrect."
}
 

Request   

POST api/rents/{rent_id}/transfer

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

email   string     

Email of the GotSMS account that receives the number. It must already be registered. Must be a valid email address. Must not be greater than 255 characters. Example: [email protected]

secret   string     

The transfer secret phrase from the API settings of your account. It is shown once, when number transfer through the API is turned on or the phrase is replaced. Must not be greater than 255 characters. Example: q7Vd2LxN9pRt4KwZ8mHc3JsB6fYa1UeG5nTb0XiQ2oLv7DkE

Account

Get account balance

requires authentication

Example request:
curl --request GET \
    --get "https://app.gotsms.com/api/account" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://app.gotsms.com/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.com/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
    }
}
 

Request   

GET api/account

Headers

Authorization        

Bearer {YOUR_API_TOKEN}

Content-Type        

application/json

Accept        

application/json

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.com/api/services" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://app.gotsms.com/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.com/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
    }
}
 

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.com/api/messages" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://app.gotsms.com/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.com/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
    }
}
 

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.com/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.com/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.com/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
    }
}
 

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    

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.com/api/numbers" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://app.gotsms.com/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.com/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,
            "is_archived": false,
            "notes": "Farm A"
        }
    ],
    "meta": {
        "total": 1
    }
}
 

Request   

GET api/numbers

Headers

Authorization        

Bearer {YOUR_API_TOKEN}

Content-Type        

application/json

Accept        

application/json

Wake up a rented number

requires authentication

Example request:
curl --request POST \
    "https://app.gotsms.com/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.com/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.com/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."
}
 

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.com/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.com/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.com/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
    }
}
 

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.com/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.com/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.com/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"
    }
}
 

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.com/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.com/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.com/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."
        ]
    }
}
 

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.com/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.com/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.com/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
    }
}
 

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

Webhooks

A webhook sends events from your account to an address on your server as soon as they happen, so you do not have to poll GET /api/messages/unread or GET /api/numbers/{rent_id}/status.

Events

Request

Every event is a POST with a JSON body:

{
    "id": "0199f1d2-7c1e-7a3b-9c4d-5e6f7a8b9c0d",
    "event": "message.received",
    "created_at": "2026-03-11T12:00:00+00:00",
    "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"
    }
}

Headers:

Checking the signature

Compute the signature over the raw body exactly as received, compare it in constant time, and reject requests whose timestamp is more than 5 minutes old:

$body = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_GOTSMS_TIMESTAMP'];
$expected = 'sha256='.hash_hmac('sha256', $timestamp.'.'.$body, $secret);

$valid = hash_equals($expected, $_SERVER['HTTP_X_GOTSMS_SIGNATURE'])
    && abs(time() - (int) $timestamp) <= 300;

Responding and retries

Reply with any 2xx status within 10 seconds. Redirects are not followed. Any other outcome is a failed attempt, and the event is sent again after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours: up to 6 attempts in total. Every attempt carries the same id, so use it to skip events you have already processed. Events may arrive out of order.

If every attempt fails for 12 hours in a row, the webhook is switched off: disabled_at in GET /api/webhook is set and you get a notification in your account. Fix your endpoint and send PUT /api/webhook with is_enabled: true to switch it back on.

The webhook address must point to a public address and use port 80, 443 or a port from 1025 to 65535. Both https:// and http:// are accepted; prefer https://, because over http:// the SMS text and codes travel unencrypted. The delivery history of the last 7 days is available in GET /api/webhook/deliveries.

Get webhook settings

requires authentication

Returns data: null while no webhook is set up.

Example request:
curl --request GET \
    --get "https://app.gotsms.com/api/webhook" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://app.gotsms.com/api/webhook"
);

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.com/api/webhook';
$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": {
        "url": "https://example.com/gotsms/webhook",
        "events": [
            "message.received",
            "rent.online"
        ],
        "is_enabled": true,
        "disabled_at": null,
        "secret": "whsec_...",
        "created_at": "2026-03-11T12:00:00+00:00",
        "updated_at": "2026-03-11T12:00:00+00:00"
    }
}
 

Request   

GET api/webhook

Headers

Authorization        

Bearer {YOUR_API_TOKEN}

Content-Type        

application/json

Accept        

application/json

Set up or update the webhook

requires authentication

Creates the webhook on the first call, with a new secret, and updates it afterwards. Sending is_enabled: true also switches back on a webhook that was switched off after failed deliveries.

Example request:
curl --request PUT \
    "https://app.gotsms.com/api/webhook" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"url\": \"https:\\/\\/example.com\\/gotsms\\/webhook\",
    \"events\": [
        \"message.received\"
    ],
    \"is_enabled\": true
}"
const url = new URL(
    "https://app.gotsms.com/api/webhook"
);

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

let body = {
    "url": "https:\/\/example.com\/gotsms\/webhook",
    "events": [
        "message.received"
    ],
    "is_enabled": true
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.com/api/webhook';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'url' => 'https://example.com/gotsms/webhook',
            'events' => ['message.received'],
            'is_enabled' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "success": true,
    "message": "Webhook saved.",
    "data": {
        "url": "https://example.com/gotsms/webhook",
        "events": [
            "message.received",
            "rent.online"
        ],
        "is_enabled": true,
        "disabled_at": null,
        "secret": "whsec_...",
        "created_at": "2026-03-11T12:00:00+00:00",
        "updated_at": "2026-03-11T12:00:00+00:00"
    }
}
 

Example response (422, Validation failed):


{
    "message": "The URL must start with http:// or https://.",
    "errors": {
        "url": [
            "The URL must start with http:// or https://."
        ]
    }
}
 

Request   

PUT api/webhook

Headers

Authorization        

Bearer {YOUR_API_TOKEN}

Content-Type        

application/json

Accept        

application/json

Body Parameters

url   string     

Address on your server that receives the events: https:// or http://, port 80, 443 or 1025-65535. Must not be greater than 2048 characters. Example: https://example.com/gotsms/webhook

events   string[]     

Event name.

Must be one of:
  • message.received
  • rent.online
  • rent.renewed
  • rent.renewal_failed
  • rent.ended
is_enabled   boolean  optional    

Set to false to pause deliveries without deleting the webhook. Defaults to true. Example: true

Delete the webhook

requires authentication

Stops all deliveries, including retries that are still scheduled.

Example request:
curl --request DELETE \
    "https://app.gotsms.com/api/webhook" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://app.gotsms.com/api/webhook"
);

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


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());
$client = new \GuzzleHttp\Client();
$url = 'https://app.gotsms.com/api/webhook';
$response = $client->delete(
    $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": "Webhook deleted."
}
 

Request   

DELETE api/webhook

Headers

Authorization        

Bearer {YOUR_API_TOKEN}

Content-Type        

application/json

Accept        

application/json

Generate a new webhook secret

requires authentication

The previous secret stops working at once: requests are signed with the new one from now on, retries included.

Example request:
curl --request POST \
    "https://app.gotsms.com/api/webhook/secret" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://app.gotsms.com/api/webhook/secret"
);

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.com/api/webhook/secret';
$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": "Webhook secret regenerated.",
    "data": {
        "url": "https://example.com/gotsms/webhook",
        "events": [
            "message.received",
            "rent.online"
        ],
        "is_enabled": true,
        "disabled_at": null,
        "secret": "whsec_...",
        "created_at": "2026-03-11T12:00:00+00:00",
        "updated_at": "2026-03-11T12:00:00+00:00"
    }
}
 

Example response (404, No webhook is set up):


{
    "success": false,
    "message": "No webhook is set up for this account."
}
 

Request   

POST api/webhook/secret

Headers

Authorization        

Bearer {YOUR_API_TOKEN}

Content-Type        

application/json

Accept        

application/json

Send a test event

requires authentication

Sends one webhook.test event right away, without retries, and returns how your server answered. Works while the webhook is paused too.

Example request:
curl --request POST \
    "https://app.gotsms.com/api/webhook/test" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://app.gotsms.com/api/webhook/test"
);

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.com/api/webhook/test';
$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,
    "data": {
        "id": "uuid",
        "event": "webhook.test",
        "status": "delivered",
        "attempts": 1,
        "response_status": 200,
        "error": null,
        "duration_ms": 184,
        "created_at": "2026-03-11T12:00:00+00:00",
        "delivered_at": "2026-03-11T12:00:00+00:00",
        "next_attempt_at": null
    }
}
 

Example response (404, No webhook is set up):


{
    "success": false,
    "message": "No webhook is set up for this account."
}
 

Request   

POST api/webhook/test

Headers

Authorization        

Bearer {YOUR_API_TOKEN}

Content-Type        

application/json

Accept        

application/json

List webhook deliveries

requires authentication

The latest 50 deliveries of the last 7 days, newest first. status is pending while retries are still scheduled, then delivered or failed. error is one of timeout, connection_failed, address_not_allowed, http_error, webhook_disabled, or null.

Example request:
curl --request GET \
    --get "https://app.gotsms.com/api/webhook/deliveries" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://app.gotsms.com/api/webhook/deliveries"
);

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.com/api/webhook/deliveries';
$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",
            "event": "message.received",
            "status": "pending",
            "attempts": 2,
            "response_status": 503,
            "error": "http_error",
            "duration_ms": 87,
            "created_at": "2026-03-11T12:00:00+00:00",
            "delivered_at": null,
            "next_attempt_at": "2026-03-11T12:06:00+00:00"
        }
    ]
}
 

Request   

GET api/webhook/deliveries

Headers

Authorization        

Bearer {YOUR_API_TOKEN}

Content-Type        

application/json

Accept        

application/json