openapi: 3.0.3 info: title: 'GotSMS API Documentation' description: 'REST API documentation.' version: 1.0.0 servers: - url: 'https://app.gotsms.com' 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/area-codes: get: summary: 'Get area codes on sale' operationId: getAreaCodesOnSale description: '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.' parameters: - in: query name: plan_id description: 'Plan UUID from GET /api/rents/plans. Must be a valid UUID.' example: 4b1e7c2a-8f3d-4a6b-9c0e-5d2f1a7b3c8e required: true schema: type: string description: 'Plan UUID from GET /api/rents/plans. Must be a valid UUID.' example: 4b1e7c2a-8f3d-4a6b-9c0e-5d2f1a7b3c8e - in: query name: cellular_carrier_id description: 'Only area codes with numbers of this cellular carrier (see GET /api/carriers). Must be a valid UUID.' example: null required: false schema: type: string description: 'Only area codes with numbers of this cellular carrier (see GET /api/carriers). Must be a valid UUID.' example: null nullable: true responses: 200: description: '' content: application/json: schema: type: object example: 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 properties: success: type: boolean example: true data: type: array example: - state: California area_codes: - area_code: '213' city: 'Los Angeles' carriers: - 'AT&T' - T-Mobile - area_code: '415' city: null carriers: - Verizon items: type: object properties: state: type: string example: California area_codes: type: array example: - area_code: '213' city: 'Los Angeles' carriers: - 'AT&T' - T-Mobile - area_code: '415' city: null carriers: - Verizon items: type: object properties: area_code: type: string example: '213' city: type: string example: 'Los Angeles' carriers: type: array example: - 'AT&T' - T-Mobile items: type: string 422: description: '' content: application/json: schema: type: object example: success: false message: 'This tariff is not available for rent.' properties: success: type: boolean example: false message: type: string example: 'This tariff is not available for rent.' 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 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 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 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 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 is_archived: 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 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: [] 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 is_archived: 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: 4b1e7c2a-8f3d-4a6b-9c0e-5d2f1a7b3c8e area_code: type: string description: 'Area code the number must have. The request fails when no such number is available.' example: null state: type: string description: 'US state the number must be from, for example California: a number with any area code of that state is rented. The states and area codes on sale for a plan are returned by GET /api/rents/area-codes. Cannot be combined with area_code. The request fails when no such number is available.' 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.' example: 7c2d9e4f-3a1b-4c5d-8e6f-0a9b8c7d6e5f 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 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 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 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: [] 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 is_archived: 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.' example: 4b1e7c2a-8f3d-4a6b-9c0e-5d2f1a7b3c8e 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 state: type: string description: 'US state the number must be from, for example California: a number with any area code of that state is rented. The states and area codes on sale for a plan are returned by GET /api/rents/area-codes. Cannot be combined with area_code. The request fails when no such number is available. Must not be greater than 64 characters.' 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.' 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: 4b1e7c2a-8f3d-4a6b-9c0e-5d2f1a7b3c8e 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}/prepay': post: summary: 'Pay ahead for a rent' operationId: payAheadForARent description: "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." parameters: [] responses: 200: description: '' content: application/json: schema: type: object example: success: true message: 'The number is paid ahead.' data: id: uuid status: active active_till: '2026-12-23T12:00:00+00:00' properties: success: type: boolean example: true message: type: string example: 'The number is paid ahead.' data: type: object properties: id: type: string example: uuid status: type: string example: active active_till: type: string example: '2026-12-23T12:00:00+00:00' 422: description: '' content: application/json: schema: type: object example: success: false message: 'Not enough balance to pay ahead.' properties: success: type: boolean example: false message: type: string example: 'Not enough balance to pay ahead.' tags: - API requestBody: required: true content: application/json: schema: type: object properties: periods: type: integer description: "How many periods of the rent's current plan to pay for, from 1 to 30. Together they may reach at most one year past the time already paid for. Must be at least 1. Must not be greater than 30." example: 3 required: - periods 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/rents/{rent_id}/archive': post: summary: 'Archive rent' operationId: archiveRent description: '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.' parameters: [] responses: 200: description: '' content: application/json: schema: type: object example: 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 properties: success: type: boolean example: true message: type: string example: 'The number has been moved to the archive.' data: type: object properties: id: type: string example: uuid status: type: string example: active is_included_for_next_renewal: type: boolean example: false is_archived: type: boolean example: true 422: description: '' content: application/json: schema: type: object example: success: false message: 'This number cannot be moved to the archive.' properties: success: type: boolean example: false message: type: string example: 'This number cannot be moved to the archive.' 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}/unarchive': post: summary: 'Unarchive rent' operationId: unarchiveRent description: '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.' parameters: [] responses: 200: description: '' content: application/json: schema: type: object example: 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 properties: success: type: boolean example: true message: type: string example: 'The number is back among the active ones.' data: type: object properties: id: type: string example: uuid status: type: string example: active is_included_for_next_renewal: type: boolean example: false is_archived: type: boolean example: false 422: description: '' content: application/json: schema: type: object example: success: false message: 'This number is not in the archive.' properties: success: type: boolean example: false message: type: string example: 'This number is not in the archive.' 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}/transfer': post: summary: 'Transfer a rent to another account' operationId: transferARentToAnotherAccount description: '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.' parameters: [] responses: 200: description: '' content: application/json: schema: type: object example: success: true message: 'Rent transferred successfully.' properties: success: type: boolean example: true message: type: string example: 'Rent transferred successfully.' 403: description: '' content: application/json: schema: type: object example: success: false message: 'Number transfer through the API is turned off. Turn it on in the API settings of your account.' properties: success: type: boolean example: false message: type: string example: 'Number transfer through the API is turned off. Turn it on in the API settings of your account.' 422: description: '' content: application/json: schema: type: object example: success: false message: 'The secret phrase is incorrect.' properties: success: type: boolean example: false message: type: string example: 'The secret phrase is incorrect.' tags: - API requestBody: required: true content: application/json: schema: type: object properties: email: type: string description: 'Email of the GotSMS account that receives the number. It must already be registered. Must be a valid email address. Must not be greater than 255 characters.' example: recipient@example.com secret: type: string description: 'The transfer secret phrase from the API settings of your account. It is shown once, when number transfer through the API is turned on or the phrase is replaced. Must not be greater than 255 characters.' example: q7Vd2LxN9pRt4KwZ8mHc3JsB6fYa1UeG5nTb0XiQ2oLv7DkE required: - email - secret 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 is_archived: false 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 is_archived: false 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 is_archived: type: boolean example: false 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 /api/webhook: get: summary: 'Get webhook settings' operationId: getWebhookSettings description: 'Returns `data: null` while no webhook is set up.' parameters: [] responses: 200: description: '' content: application/json: schema: type: object example: 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' properties: success: type: boolean example: true data: type: object properties: url: type: string example: 'https://example.com/gotsms/webhook' events: type: array example: - message.received - rent.online items: type: string is_enabled: type: boolean example: true disabled_at: type: string example: null nullable: true secret: type: string example: whsec_... created_at: type: string example: '2026-03-11T12:00:00+00:00' updated_at: type: string example: '2026-03-11T12:00:00+00:00' tags: - API put: summary: 'Set up or update the webhook' operationId: setUpOrUpdateTheWebhook description: '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.' parameters: [] responses: 200: description: '' content: application/json: schema: type: object example: 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' properties: success: type: boolean example: true message: type: string example: 'Webhook saved.' data: type: object properties: url: type: string example: 'https://example.com/gotsms/webhook' events: type: array example: - message.received - rent.online items: type: string is_enabled: type: boolean example: true disabled_at: type: string example: null nullable: true secret: type: string example: whsec_... created_at: type: string example: '2026-03-11T12:00:00+00:00' updated_at: type: string example: '2026-03-11T12:00:00+00:00' 422: description: 'Validation failed' content: application/json: schema: type: object example: message: 'The URL must start with http:// or https://.' errors: url: - 'The URL must start with http:// or https://.' properties: message: type: string example: 'The URL must start with http:// or https://.' errors: type: object properties: url: type: array example: - 'The URL must start with http:// or https://.' items: type: string tags: - API requestBody: required: true content: application/json: schema: type: object properties: url: type: string description: 'Address on your server that receives the events: https:// or http://, port 80, 443 or 1025-65535. Must not be greater than 2048 characters.' example: 'https://example.com/gotsms/webhook' events: type: array description: 'Event name.' example: - message.received items: type: string enum: - message.received - rent.online - rent.renewed - rent.renewal_failed - rent.ended is_enabled: type: boolean description: 'Set to false to pause deliveries without deleting the webhook. Defaults to true.' example: true required: - url - events delete: summary: 'Delete the webhook' operationId: deleteTheWebhook description: 'Stops all deliveries, including retries that are still scheduled.' parameters: [] responses: 200: description: '' content: application/json: schema: type: object example: success: true message: 'Webhook deleted.' properties: success: type: boolean example: true message: type: string example: 'Webhook deleted.' tags: - API /api/webhook/secret: post: summary: 'Generate a new webhook secret' operationId: generateANewWebhookSecret description: 'The previous secret stops working at once: requests are signed with the new one from now on, retries included.' parameters: [] responses: 200: description: '' content: application/json: schema: type: object example: 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' properties: success: type: boolean example: true message: type: string example: 'Webhook secret regenerated.' data: type: object properties: url: type: string example: 'https://example.com/gotsms/webhook' events: type: array example: - message.received - rent.online items: type: string is_enabled: type: boolean example: true disabled_at: type: string example: null nullable: true secret: type: string example: whsec_... created_at: type: string example: '2026-03-11T12:00:00+00:00' updated_at: type: string example: '2026-03-11T12:00:00+00:00' 404: description: 'No webhook is set up' content: application/json: schema: type: object example: success: false message: 'No webhook is set up for this account.' properties: success: type: boolean example: false message: type: string example: 'No webhook is set up for this account.' tags: - API /api/webhook/test: post: summary: 'Send a test event' operationId: sendATestEvent description: 'Sends one `webhook.test` event right away, without retries, and returns how your server answered. Works while the webhook is paused too.' parameters: [] responses: 200: description: '' content: application/json: schema: type: object example: 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 properties: success: type: boolean example: true data: type: object properties: id: type: string example: uuid event: type: string example: webhook.test status: type: string example: delivered attempts: type: integer example: 1 response_status: type: integer example: 200 error: type: string example: null nullable: true duration_ms: type: integer example: 184 created_at: type: string example: '2026-03-11T12:00:00+00:00' delivered_at: type: string example: '2026-03-11T12:00:00+00:00' next_attempt_at: type: string example: null nullable: true 404: description: 'No webhook is set up' content: application/json: schema: type: object example: success: false message: 'No webhook is set up for this account.' properties: success: type: boolean example: false message: type: string example: 'No webhook is set up for this account.' tags: - API /api/webhook/deliveries: get: summary: 'List webhook deliveries' operationId: listWebhookDeliveries description: '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.' parameters: [] responses: 200: description: '' content: application/json: schema: type: object example: 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' properties: success: type: boolean example: true data: type: array example: - 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' items: type: object properties: id: type: string example: uuid event: type: string example: message.received status: type: string example: pending attempts: type: integer example: 2 response_status: type: integer example: 503 error: type: string example: http_error duration_ms: type: integer example: 87 created_at: type: string example: '2026-03-11T12:00:00+00:00' delivered_at: type: string example: null nullable: true next_attempt_at: type: string example: '2026-03-11T12:06:00+00:00' tags: - API