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"
}
]
}
]
}
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.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"
}
]
}
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.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
}
}
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 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."
}
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.
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
}
}
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.
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
}
]
}
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.
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": []
}
}
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.
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
}
}
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.
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."
}
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.
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."
}
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.
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."
}
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.
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."
}
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.
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."
}
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.
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."
}
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.
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."
}
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.
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."
}
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.
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
}
}
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.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
}
}
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.
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
}
}
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.
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
}
}
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.
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
}
}
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.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."
}
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 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
}
}
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 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"
}
}
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.
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."
]
}
}
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 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
}
}
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.
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
message.received: a new SMS arrived on one of your numbers.datahas the same fields as a message inGET /api/messages/unread.rent.online: a number you woke up withPOST /api/numbers/{rent_id}/wake-upis ready to receive SMS, andGET /api/numbers/{rent_id}/statusnow returnsready.data:rent_id,service,phone,status,wake_from,wake_till.rent.renewed: a rent got a new paid period, either renewed automatically when its period ran out or paid ahead withPOST /api/rents/{rent_id}/prepay.priceis what was charged,active_fromandactive_tillare the bounds of the new period; a period paid ahead starts when the time already paid for ends.data:rent_id,service,phone,price,active_from,active_till.rent.renewal_failed: automatic renewal did not happen because the balance did not cover the renewal price.data:rent_id,service,phone,renew_price,balance.rent.ended: a rent period ran out and the rent was not renewed.data:rent_id,service,phone,ended_at.webhook.test: sent only when you callPOST /api/webhook/test.data:message.
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:
X-GotSMS-Event: the event name;X-GotSMS-Delivery: the same value asidin the body;X-GotSMS-Timestamp: when the request was signed, Unix time in seconds;X-GotSMS-Signature:sha256=followed by the hex HMAC-SHA256 of{timestamp}.{raw request body}, keyed with your webhook secret.
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"
}
}
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.
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://."
]
}
}
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.
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."
}
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.
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."
}
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.
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."
}
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.
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"
}
]
}
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.