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: '' parameters: [] responses: 200: description: '' content: application/json: schema: type: object example: success: true data: - name: Telegram 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 - name: WhatsApp 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: - name: Telegram 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 - name: WhatsApp 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: name: type: string example: Telegram 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/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 available services' operationId: getAvailableServices description: '' 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 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 items: type: object properties: id: type: string example: uuid name: type: string example: Telegram 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 available rent plans' operationId: getAvailableRentPlans description: '' 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 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_monthly_supported: false 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_monthly_supported: false 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_monthly_supported: type: boolean example: false 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: 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 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 800 123 4567' 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 transition_options: [] 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 800 123 4567' 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 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 800 123 4567' 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 transition_options: type: array example: [] 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 800 123 4567' 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 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 800 123 4567' 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 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: 'Preferred area code.' example: null required: - plan_id '/api/rents/{rent_id}/transition': post: summary: 'Transition rent to a longer plan' operationId: transitionRentToALongerPlan description: '' 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: 'Current rent plan must be daily for this transition endpoint.' properties: success: type: boolean example: false message: type: string example: 'Current rent plan must be daily for this transition endpoint.' tags: - API requestBody: required: true content: application/json: schema: type: object properties: plan_id: type: string description: 'Target plan UUID (1/3/6/12 months).' 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 for monthly tariffs' operationId: toggleAutoRenewalForMonthlyTariffs description: '' 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: 'Auto renewal can be toggled only for monthly 1/3/6/12 plans.' properties: success: type: boolean example: false message: type: string example: 'Auto renewal can be toggled only for monthly 1/3/6/12 plans.' 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. Значение поля value должно быть корректным UUID.' example: null required: false schema: type: string description: 'Filter by service UUID. Значение поля value должно быть корректным UUID.' example: null nullable: true - in: query name: phone description: 'Phone search. Количество символов в значении поля value не может превышать 32.' example: null required: false schema: type: string description: 'Phone search. Количество символов в значении поля value не может превышать 32.' example: null nullable: true - in: query name: per_page description: 'Pagination size (max 100). Значение поля value должно быть не меньше 1. Значение поля value не может быть больше 100.' example: null required: false schema: type: integer description: 'Pagination size (max 100). Значение поля value должно быть не меньше 1. Значение поля value не может быть больше 100.' example: null nullable: true 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 800 123 4567' from: '+18001234567' to: '+18009876543' 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 800 123 4567' from: '+18001234567' to: '+18009876543' 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 800 123 4567' from: type: string example: '+18001234567' to: type: string example: '+18009876543' 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: '' 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 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 800 123 4567' from: '+18001234567' to: '+18009876543' 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 800 123 4567' from: '+18001234567' to: '+18009876543' 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 800 123 4567' from: type: string example: '+18001234567' to: type: string example: '+18009876543' 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/{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.' properties: success: type: boolean example: true message: type: string example: 'Wake up request sent.' 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: 'Fetch messages with id less than this UUID.' example: null required: false schema: type: string description: 'Fetch messages with id less than this UUID.' example: null responses: 200: description: '' content: application/json: schema: type: object example: success: true data: - id: uuid from: '+18001234567' to: '+18009876543' 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: '+18009876543' 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: '+18009876543' 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}/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-11T12:35:00+00:00' wakeup_time_left_seconds: 120 online_time_left_seconds: 1800 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-11T12:35:00+00:00' wakeup_time_left_seconds: type: integer example: 120 online_time_left_seconds: type: integer example: 1800 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