openapi: 3.0.3
info:
title: 'GotSMS API Documentation'
description: 'REST API documentation.'
version: 1.0.0
servers:
- url: 'https://app.gotsms.org'
tags:
- name: API
description: 'GotSMS API methods.'
components:
securitySchemes:
default:
type: http
scheme: bearer
description: 'Enable API access, then click Generate Token.'
security:
-
default: []
paths:
/api/pricelist:
get:
summary: 'Get public pricelist'
operationId: getPublicPricelist
description: 'The icon field is returned only when the request is sent without a token.'
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
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
properties:
success:
type: boolean
example: true
data:
type: array
example:
-
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
items:
type: object
properties:
id:
type: string
example: 9b1f8c3e-1c2a-4f5b-8d7e-0a1b2c3d4e5f
name:
type: string
example: Telegram
slug:
type: string
example: telegram
icon:
type: string
example: 'https://example.com/icons/telegram.png'
plans:
type: array
example:
- 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
items:
type: object
properties:
service_name:
type: string
example: Telegram
period:
type: integer
example: 1
period_type:
type: string
example: day
period_type_label:
type: string
example: day
duration_translation:
type: string
example: '1 day'
price:
type: integer
example: 1
renew_price:
type: integer
example: 1
country:
type: string
example: USA
billing_type:
type: string
example: duration
tags:
- API
security: []
/api/carriers:
get:
summary: 'List cellular carriers'
operationId: listCellularCarriers
description: ''
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
data:
-
id: uuid
name: T-Mobile
properties:
success:
type: boolean
example: true
data:
type: array
example:
- id: uuid
name: T-Mobile
items:
type: object
properties:
id:
type: string
example: uuid
name:
type: string
example: T-Mobile
tags:
- API
security: []
/api/account:
get:
summary: 'Get account balance'
operationId: getAccountBalance
description: ''
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
data:
balance: 125.5
properties:
success:
type: boolean
example: true
data:
type: object
properties:
balance:
type: number
example: 125.5
tags:
- API
/api/services:
get:
summary: 'Get services'
operationId: getServices
description: 'Includes services whose numbers are sold out right now, marked is_available = false.'
parameters:
-
in: query
name: search
description: 'Search in service name.'
example: null
required: false
schema:
type: string
description: 'Search in service name.'
example: null
-
in: query
name: per_page
description: 'Pagination size (max 100).'
example: null
required: false
schema:
type: integer
description: 'Pagination size (max 100).'
example: null
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
data:
-
id: uuid
name: Telegram
is_available: true
meta:
current_page: 1
last_page: 1
per_page: 25
total: 1
properties:
success:
type: boolean
example: true
data:
type: array
example:
- id: uuid
name: Telegram
is_available: true
items:
type: object
properties:
id:
type: string
example: uuid
name:
type: string
example: Telegram
is_available:
type: boolean
example: true
meta:
type: object
properties:
current_page:
type: integer
example: 1
last_page:
type: integer
example: 1
per_page:
type: integer
example: 25
total:
type: integer
example: 1
tags:
- API
/api/rents/plans:
get:
summary: 'Get rent plans'
operationId: getRentPlans
description: '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.'
parameters:
-
in: query
name: service_id
description: 'Filter by service UUID.'
example: null
required: false
schema:
type: string
description: 'Filter by service UUID.'
example: null
-
in: query
name: country_id
description: 'Filter by country UUID.'
example: null
required: false
schema:
type: string
description: 'Filter by country UUID.'
example: null
-
in: query
name: duration_type
description: 'Filter by duration type.'
example: null
required: false
schema:
type: string
description: 'Filter by duration type.'
example: null
enum:
- min
- hour
- day
- week
- month
- year
-
in: query
name: billing_type
description: 'Filter by billing type.'
example: null
required: false
schema:
type: string
description: 'Filter by billing type.'
example: null
enum:
- sms
- duration
-
in: query
name: search
description: 'Search in service name.'
example: null
required: false
schema:
type: string
description: 'Search in service name.'
example: null
-
in: query
name: per_page
description: 'Pagination size (max 100).'
example: null
required: false
schema:
type: integer
description: 'Pagination size (max 100).'
example: null
-
in: query
name: include_unavailable
description: 'Also return plans that are currently sold out.'
example: null
required: false
schema:
type: boolean
description: 'Also return plans that are currently sold out.'
example: null
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
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
properties:
success:
type: boolean
example: true
data:
type: array
example:
-
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
items:
type: object
properties:
id:
type: string
example: uuid
service:
type: object
properties:
id:
type: string
example: uuid
name:
type: string
example: Telegram
country:
type: object
properties:
id:
type: string
example: uuid
name:
type: string
example: USA
billing_type:
type: string
example: duration
duration_type:
type: string
example: day
duration_in_type:
type: integer
example: 1
duration_in_minutes:
type: integer
example: 1440
duration_translation:
type: string
example: '1 day'
price:
type: integer
example: 1
renew_price:
type: integer
example: 1
is_available:
type: boolean
example: true
meta:
type: object
properties:
current_page:
type: integer
example: 1
last_page:
type: integer
example: 1
per_page:
type: integer
example: 25
total:
type: integer
example: 1
tags:
- API
/api/rents:
get:
summary: 'List user rents'
operationId: listUserRents
description: ''
parameters:
-
in: query
name: status
description: 'Filter by status.'
example: null
required: false
schema:
type: string
description: 'Filter by status.'
example: null
enum:
- active
- finished
-
in: query
name: service
description: 'Service name search.'
example: null
required: false
schema:
type: string
description: 'Service name search.'
example: null
-
in: query
name: phone
description: 'Phone search.'
example: null
required: false
schema:
type: string
description: 'Phone search.'
example: null
-
in: query
name: notes
description: 'Search in rent notes.'
example: null
required: false
schema:
type: string
description: 'Search in rent notes.'
example: null
-
in: query
name: per_page
description: 'Pagination size (max 100).'
example: null
required: false
schema:
type: integer
description: 'Pagination size (max 100).'
example: null
-
in: query
name: page
description: 'Page number, starting from 1.'
example: null
required: false
schema:
type: integer
description: 'Page number, starting from 1.'
example: null
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
data:
-
id: uuid
service:
id: uuid
name: Telegram
plan:
id: uuid
billing_type: duration
duration_type: day
duration_in_type: 1
duration_translation: '1 day'
price: 1
renew_price: 1
phone: '+1 202-555-0123'
price: 1
status: active
is_included_for_next_renewal: false
active_from: '2026-03-11T12:00:00+00:00'
active_till: '2026-03-12T12:00:00+00:00'
wake_from: null
wake_till: null
can_wake_up: true
notes: 'Call customer after activation'
transition_options:
-
plan_id: uuid
duration_type: day
duration_in_type: 7
duration_translation: '7 days'
price: 5
meta:
current_page: 1
last_page: 1
per_page: 20
total: 1
properties:
success:
type: boolean
example: true
data:
type: array
example:
-
id: uuid
service:
id: uuid
name: Telegram
plan:
id: uuid
billing_type: duration
duration_type: day
duration_in_type: 1
duration_translation: '1 day'
price: 1
renew_price: 1
phone: '+1 202-555-0123'
price: 1
status: active
is_included_for_next_renewal: false
active_from: '2026-03-11T12:00:00+00:00'
active_till: '2026-03-12T12:00:00+00:00'
wake_from: null
wake_till: null
can_wake_up: true
notes: 'Call customer after activation'
transition_options:
- plan_id: uuid
duration_type: day
duration_in_type: 7
duration_translation: '7 days'
price: 5
items:
type: object
properties:
id:
type: string
example: uuid
service:
type: object
properties:
id:
type: string
example: uuid
name:
type: string
example: Telegram
plan:
type: object
properties:
id:
type: string
example: uuid
billing_type:
type: string
example: duration
duration_type:
type: string
example: day
duration_in_type:
type: integer
example: 1
duration_translation:
type: string
example: '1 day'
price:
type: integer
example: 1
renew_price:
type: integer
example: 1
phone:
type: string
example: '+1 202-555-0123'
price:
type: integer
example: 1
status:
type: string
example: active
is_included_for_next_renewal:
type: boolean
example: false
active_from:
type: string
example: '2026-03-11T12:00:00+00:00'
active_till:
type: string
example: '2026-03-12T12:00:00+00:00'
wake_from:
type: string
example: null
nullable: true
wake_till:
type: string
example: null
nullable: true
can_wake_up:
type: boolean
example: true
notes:
type: string
example: 'Call customer after activation'
transition_options:
type: array
example:
- plan_id: uuid
duration_type: day
duration_in_type: 7
duration_translation: '7 days'
price: 5
items:
type: object
properties:
plan_id:
type: string
example: uuid
duration_type:
type: string
example: day
duration_in_type:
type: integer
example: 7
duration_translation:
type: string
example: '7 days'
price:
type: integer
example: 5
meta:
type: object
properties:
current_page:
type: integer
example: 1
last_page:
type: integer
example: 1
per_page:
type: integer
example: 20
total:
type: integer
example: 1
tags:
- API
post:
summary: 'Create new rent'
operationId: createNewRent
description: ''
parameters: []
responses:
201:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
message: 'Rent created successfully.'
data:
id: uuid
service:
id: uuid
name: Telegram
plan:
id: uuid
billing_type: duration
duration_type: day
duration_in_type: 1
duration_translation: '1 day'
price: 1
renew_price: 1
phone: '+1 202-555-0123'
price: 1
status: active
is_included_for_next_renewal: false
active_from: '2026-03-11T12:00:00+00:00'
active_till: '2026-03-12T12:00:00+00:00'
wake_from: null
wake_till: null
can_wake_up: true
notes: null
transition_options: []
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Rent created successfully.'
data:
type: object
properties:
id:
type: string
example: uuid
service:
type: object
properties:
id:
type: string
example: uuid
name:
type: string
example: Telegram
plan:
type: object
properties:
id:
type: string
example: uuid
billing_type:
type: string
example: duration
duration_type:
type: string
example: day
duration_in_type:
type: integer
example: 1
duration_translation:
type: string
example: '1 day'
price:
type: integer
example: 1
renew_price:
type: integer
example: 1
phone:
type: string
example: '+1 202-555-0123'
price:
type: integer
example: 1
status:
type: string
example: active
is_included_for_next_renewal:
type: boolean
example: false
active_from:
type: string
example: '2026-03-11T12:00:00+00:00'
active_till:
type: string
example: '2026-03-12T12:00:00+00:00'
wake_from:
type: string
example: null
nullable: true
wake_till:
type: string
example: null
nullable: true
can_wake_up:
type: boolean
example: true
notes:
type: string
example: null
nullable: true
transition_options:
type: array
example: []
tags:
- API
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
plan_id:
type: string
description: 'Plan UUID to rent.'
example: null
area_code:
type: string
description: 'Area code the number must have. The request fails when no such number is available.'
example: null
cellular_carrier_id:
type: string
description: 'UUID of the cellular carrier the number must have (see GET /api/carriers). The request fails when no such number is available.'
example: null
required:
- plan_id
'/api/rents/{rent_id}/services':
get:
summary: 'List services that can be added to a rent'
operationId: listServicesThatCanBeAddedToARent
description: 'Services the same number can additionally receive SMS for. Only active rents support it; unavailable services are listed with is_available = false.'
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
data:
-
service_id: uuid
name: WhatsApp
price: 2
base_price: 1
add_service_markup: 1
is_available: true
properties:
success:
type: boolean
example: true
data:
type: array
example:
- service_id: uuid
name: WhatsApp
price: 2
base_price: 1
add_service_markup: 1
is_available: true
items:
type: object
properties:
service_id:
type: string
example: uuid
name:
type: string
example: WhatsApp
price:
type: integer
example: 2
base_price:
type: integer
example: 1
add_service_markup:
type: integer
example: 1
is_available:
type: boolean
example: true
tags:
- API
post:
summary: 'Add a service to a rent'
operationId: addAServiceToARent
description: '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.'
parameters: []
responses:
201:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
message: 'Service added to the number.'
data:
id: uuid
status: active
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Service added to the number.'
data:
type: object
properties:
id:
type: string
example: uuid
status:
type: string
example: active
422:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: 'Adding a service is not available for this number.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Adding a service is not available for this number.'
tags:
- API
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
service_id:
type: string
description: 'Service UUID from GET /api/rents/{rent_id}/services. Must be a valid UUID. The id of an existing record in the services table.'
example: No-example
required:
- service_id
parameters:
-
in: path
name: rent_id
description: 'Rent UUID.'
example: 9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f
required: true
schema:
type: string
/api/rents/bulk:
post:
summary: 'Create several rents at once'
operationId: createSeveralRentsAtOnce
description: '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.'
parameters: []
responses:
201:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
message: 'Rented 2 of 3 numbers.'
data:
-
id: uuid
service:
id: uuid
name: Telegram
plan:
id: uuid
billing_type: duration
duration_type: day
duration_in_type: 1
duration_translation: '1 day'
price: 1
renew_price: 1
phone: '+1 202-555-0123'
price: 1
status: active
is_included_for_next_renewal: false
active_from: '2026-03-11T12:00:00+00:00'
active_till: '2026-03-12T12:00:00+00:00'
wake_from: null
wake_till: null
can_wake_up: true
notes: null
transition_options: []
meta:
requested: 3
rented: 2
failed: 0
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Rented 2 of 3 numbers.'
data:
type: array
example:
-
id: uuid
service:
id: uuid
name: Telegram
plan:
id: uuid
billing_type: duration
duration_type: day
duration_in_type: 1
duration_translation: '1 day'
price: 1
renew_price: 1
phone: '+1 202-555-0123'
price: 1
status: active
is_included_for_next_renewal: false
active_from: '2026-03-11T12:00:00+00:00'
active_till: '2026-03-12T12:00:00+00:00'
wake_from: null
wake_till: null
can_wake_up: true
notes: null
transition_options: []
items:
type: object
properties:
id:
type: string
example: uuid
service:
type: object
properties:
id:
type: string
example: uuid
name:
type: string
example: Telegram
plan:
type: object
properties:
id:
type: string
example: uuid
billing_type:
type: string
example: duration
duration_type:
type: string
example: day
duration_in_type:
type: integer
example: 1
duration_translation:
type: string
example: '1 day'
price:
type: integer
example: 1
renew_price:
type: integer
example: 1
phone:
type: string
example: '+1 202-555-0123'
price:
type: integer
example: 1
status:
type: string
example: active
is_included_for_next_renewal:
type: boolean
example: false
active_from:
type: string
example: '2026-03-11T12:00:00+00:00'
active_till:
type: string
example: '2026-03-12T12:00:00+00:00'
wake_from:
type: string
example: null
nullable: true
wake_till:
type: string
example: null
nullable: true
can_wake_up:
type: boolean
example: true
notes:
type: string
example: null
nullable: true
transition_options:
type: array
example: []
meta:
type: object
properties:
requested:
type: integer
example: 3
rented:
type: integer
example: 2
failed:
type: integer
example: 0
422:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: 'No number available for this service.'
meta:
requested: 3
rented: 0
failed: 0
properties:
success:
type: boolean
example: false
message:
type: string
example: 'No number available for this service.'
meta:
type: object
properties:
requested:
type: integer
example: 3
rented:
type: integer
example: 0
failed:
type: integer
example: 0
tags:
- API
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
plan_id:
type: string
description: 'Plan UUID to rent. Must be a valid UUID. The id of an existing record in the plans table.'
example: No-example
quantity:
type: integer
description: '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:
type: string
description: 'Area code the number must have. The request fails when no such number is available. Must match the regex /^\d{2,6}$/.'
example: null
nullable: true
cellular_carrier_id:
type: string
description: 'UUID of the cellular carrier the number must have (see GET /api/carriers). The request fails when no such number is available. Must be a valid UUID. The id of an existing record in the cellular_carriers table.'
example: null
nullable: true
required:
- plan_id
- quantity
'/api/rents/{rent_id}/transition':
post:
summary: 'Transition rent to another plan'
operationId: transitionRentToAnotherPlan
description: '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.'
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
message: 'Plan transitioned successfully.'
data:
id: uuid
status: active
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Plan transitioned successfully.'
data:
type: object
properties:
id:
type: string
example: uuid
status:
type: string
example: active
422:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: 'Transition to selected plan is unavailable.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Transition to selected plan is unavailable.'
tags:
- API
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
plan_id:
type: string
description: 'Target plan UUID: a plan_id from transition_options of this rent in GET /api/rents.'
example: null
required:
- plan_id
parameters:
-
in: path
name: rent_id
description: 'Rent UUID.'
example: 9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f
required: true
schema:
type: string
'/api/rents/{rent_id}/renewal/toggle':
post:
summary: 'Toggle auto renewal'
operationId: toggleAutoRenewal
description: '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.'
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
message: 'Auto renewal enabled.'
data:
id: uuid
is_included_for_next_renewal: true
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Auto renewal enabled.'
data:
type: object
properties:
id:
type: string
example: uuid
is_included_for_next_renewal:
type: boolean
example: true
422:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: 'Failed to toggle auto renewal.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Failed to toggle auto renewal.'
tags:
- API
parameters:
-
in: path
name: rent_id
description: 'Rent UUID.'
example: 9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f
required: true
schema:
type: string
'/api/rents/{rent_id}/refund':
post:
summary: 'Refund rent'
operationId: refundRent
description: ''
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
message: 'Rent has been refunded successfully.'
data:
id: uuid
status: finished
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Rent has been refunded successfully.'
data:
type: object
properties:
id:
type: string
example: uuid
status:
type: string
example: finished
422:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: 'Refund not available for this rent.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Refund not available for this rent.'
tags:
- API
parameters:
-
in: path
name: rent_id
description: 'Rent UUID.'
example: 9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f
required: true
schema:
type: string
/api/messages:
get:
summary: 'List all SMS messages across all rents'
operationId: listAllSMSMessagesAcrossAllRents
description: ''
parameters:
-
in: query
name: service_id
description: 'Filter by service UUID. Must be a valid UUID.'
example: null
required: false
schema:
type: string
description: 'Filter by service UUID. Must be a valid UUID.'
example: null
nullable: true
-
in: query
name: phone
description: 'Phone search. Must not be greater than 32 characters.'
example: null
required: false
schema:
type: string
description: 'Phone search. Must not be greater than 32 characters.'
example: null
nullable: true
-
in: query
name: per_page
description: 'Pagination size (max 100). Must be at least 1. Must not be greater than 100.'
example: null
required: false
schema:
type: integer
description: 'Pagination size (max 100). Must be at least 1. Must not be greater than 100.'
example: null
nullable: true
-
in: query
name: page
description: 'Page number, starting from 1.'
example: null
required: false
schema:
type: integer
description: 'Page number, starting from 1.'
example: null
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
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
properties:
success:
type: boolean
example: true
data:
type: array
example:
-
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'
items:
type: object
properties:
id:
type: string
example: uuid
rent_id:
type: string
example: uuid
service:
type: object
properties:
id:
type: string
example: uuid
name:
type: string
example: Telegram
phone:
type: string
example: '+1 202-555-0123'
from:
type: string
example: '+18001234567'
to:
type: string
example: '+1 202-555-0123'
body:
type: string
example: 'Your verification code is 123456'
code:
type: string
example: '123456'
received_at:
type: string
example: '2026-03-11T12:00:00+00:00'
meta:
type: object
properties:
current_page:
type: integer
example: 1
last_page:
type: integer
example: 1
per_page:
type: integer
example: 20
total:
type: integer
example: 1
tags:
- API
/api/messages/unread:
get:
summary: 'List unread SMS messages'
operationId: listUnreadSMSMessages
description: 'Unread SMS received in the last 30 days, newest first.'
parameters:
-
in: query
name: service_id
description: 'Filter by service UUID.'
example: null
required: false
schema:
type: string
description: 'Filter by service UUID.'
example: null
-
in: query
name: rent_id
description: 'Filter by rent UUID.'
example: null
required: false
schema:
type: string
description: 'Filter by rent UUID.'
example: null
-
in: query
name: phone
description: 'Phone search.'
example: null
required: false
schema:
type: string
description: 'Phone search.'
example: null
-
in: query
name: per_page
description: 'Pagination size (max 100).'
example: null
required: false
schema:
type: integer
description: 'Pagination size (max 100).'
example: null
-
in: query
name: mark_as_read
description: 'Mark returned messages as read.'
example: null
required: false
schema:
type: boolean
description: 'Mark returned messages as read.'
example: null
-
in: query
name: page
description: 'Page number, starting from 1.'
example: null
required: false
schema:
type: integer
description: 'Page number, starting from 1.'
example: null
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
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
properties:
success:
type: boolean
example: true
data:
type: array
example:
-
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'
items:
type: object
properties:
id:
type: string
example: uuid
rent_id:
type: string
example: uuid
service:
type: object
properties:
id:
type: string
example: uuid
name:
type: string
example: Telegram
phone:
type: string
example: '+1 202-555-0123'
from:
type: string
example: '+18001234567'
to:
type: string
example: '+1 202-555-0123'
body:
type: string
example: 'Your verification code is 123456'
code:
type: string
example: '123456'
received_at:
type: string
example: '2026-03-11T12:00:00+00:00'
meta:
type: object
properties:
current_page:
type: integer
example: 1
last_page:
type: integer
example: 1
per_page:
type: integer
example: 20
total:
type: integer
example: 1
tags:
- API
/api/numbers:
get:
summary: 'List all active numbers'
operationId: listAllActiveNumbers
description: 'Every number currently rented by the account, without pagination.'
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
data:
-
id: uuid
phone: '+1 202-555-0123'
service: Telegram
active_till: '2026-03-12T12:00:00+00:00'
is_included_for_next_renewal: true
notes: 'Farm A'
meta:
total: 1
properties:
success:
type: boolean
example: true
data:
type: array
example:
- id: uuid
phone: '+1 202-555-0123'
service: Telegram
active_till: '2026-03-12T12:00:00+00:00'
is_included_for_next_renewal: true
notes: 'Farm A'
items:
type: object
properties:
id:
type: string
example: uuid
phone:
type: string
example: '+1 202-555-0123'
service:
type: string
example: Telegram
active_till:
type: string
example: '2026-03-12T12:00:00+00:00'
is_included_for_next_renewal:
type: boolean
example: true
notes:
type: string
example: 'Farm A'
meta:
type: object
properties:
total:
type: integer
example: 1
tags:
- API
'/api/numbers/{rent_id}/wake-up':
post:
summary: 'Wake up a rented number'
operationId: wakeUpARentedNumber
description: ''
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
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
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Wake up request sent.'
data:
type: object
properties:
rent_id:
type: string
example: uuid
status:
type: string
example: in_queue
active_from:
type: string
example: '2026-03-11T12:00:00+00:00'
active_till:
type: string
example: '2026-03-12T12:00:00+00:00'
wake_from:
type: string
example: '2026-03-11T12:03:00+00:00'
wake_till:
type: string
example: '2026-03-11T12:08:00+00:00'
online_till:
type: string
example: '2026-03-12T12:00:00+00:00'
wakeup_time_left_seconds:
type: integer
example: 480
online_time_left_seconds:
type: integer
example: 86400
can_wake_up:
type: boolean
example: false
422:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: 'The rental has already ended.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'The rental has already ended.'
tags:
- API
parameters:
-
in: path
name: rent_id
description: 'Rent UUID.'
example: 9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f
required: true
schema:
type: string
'/api/numbers/{rent_id}/messages':
get:
summary: 'Get SMS messages for a rent'
operationId: getSMSMessagesForARent
description: ''
parameters:
-
in: query
name: limit
description: 'Number of records (max 100).'
example: null
required: false
schema:
type: integer
description: 'Number of records (max 100).'
example: null
-
in: query
name: before_id
description: 'Return messages older than the message with this id. Pass meta.next_before_id from the previous response to get the next page.'
example: null
required: false
schema:
type: string
description: 'Return messages older than the message with this id. Pass meta.next_before_id from the previous response to get the next page.'
example: null
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
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
properties:
success:
type: boolean
example: true
data:
type: array
example:
- 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'
items:
type: object
properties:
id:
type: string
example: uuid
from:
type: string
example: '+18001234567'
to:
type: string
example: '+1 202-555-0123'
body:
type: string
example: 'Your verification code is 123456'
code:
type: string
example: '123456'
received_at:
type: string
example: '2026-03-11T12:00:00+00:00'
meta:
type: object
properties:
next_before_id:
type: string
example: uuid
count:
type: integer
example: 1
tags:
- API
parameters:
-
in: path
name: rent_id
description: 'Rent UUID.'
example: 9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f
required: true
schema:
type: string
'/api/numbers/{rent_id}/notes':
get:
summary: 'Get notes for a rented number'
operationId: getNotesForARentedNumber
description: ''
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
data:
rent_id: uuid
notes: 'Call customer after activation'
properties:
success:
type: boolean
example: true
data:
type: object
properties:
rent_id:
type: string
example: uuid
notes:
type: string
example: 'Call customer after activation'
tags:
- API
put:
summary: 'Update notes for a rented number'
operationId: updateNotesForARentedNumber
description: 'Replaces the current note.'
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
message: 'Notes updated successfully.'
data:
rent_id: uuid
notes: 'Call customer after activation'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Notes updated successfully.'
data:
type: object
properties:
rent_id:
type: string
example: uuid
notes:
type: string
example: 'Call customer after activation'
422:
description: 'Validation failed'
content:
application/json:
schema:
type: object
example:
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.'
properties:
message:
type: string
example: 'The notes field must contain plain text only. HTML is not allowed.'
errors:
type: object
properties:
notes:
type: array
example:
- 'The notes field must contain plain text only. HTML is not allowed.'
items:
type: string
tags:
- API
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
notes:
type: string
description: 'Plain-text note, max 1000 characters. HTML is rejected. Send null to clear the note.'
example: 'Call customer after activation'
required:
- notes
parameters:
-
in: path
name: rent_id
description: 'Rent UUID.'
example: 9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f
required: true
schema:
type: string
'/api/numbers/{rent_id}/status':
get:
summary: 'Get number queue/wakeup/online status'
operationId: getNumberQueuewakeuponlineStatus
description: ''
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
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
properties:
success:
type: boolean
example: true
data:
type: object
properties:
rent_id:
type: string
example: uuid
status:
type: string
example: active
active_from:
type: string
example: '2026-03-11T12:00:00+00:00'
active_till:
type: string
example: '2026-03-12T12:00:00+00:00'
wake_from:
type: string
example: '2026-03-11T12:00:00+00:00'
wake_till:
type: string
example: '2026-03-11T12:05:00+00:00'
online_till:
type: string
example: '2026-03-12T12:00:00+00:00'
wakeup_time_left_seconds:
type: integer
example: 120
online_time_left_seconds:
type: integer
example: 86220
can_wake_up:
type: boolean
example: false
tags:
- API
parameters:
-
in: path
name: rent_id
description: 'Rent UUID.'
example: 9d3f8f6a-1b2c-4d5e-8f90-1a2b3c4d5e6f
required: true
schema:
type: string