{"openapi":"3.1.0","info":{"title":"VirtualSMSNumbers API","version":"1.4.0","summary":"Virtual numbers for SMS verification in 190+ countries.","description":"Buy a temporary phone number, receive the verification SMS on it, then release it. Activations that never receive a message are refunded automatically and in full. Authenticate with an API key created in the dashboard.","contact":{"name":"VirtualSMSNumbers Support","email":"support@virtualsmsnumbers.com","url":"https://virtualsmsnumbers.com/en/contact"},"termsOfService":"https://virtualsmsnumbers.com/en/legal/terms","license":{"name":"Proprietary","identifier":"LicenseRef-Proprietary"}},"servers":[{"url":"https://virtualsmsnumbers.com/api/v1","description":"Production"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"tags":[{"name":"Activations","description":"One-time verification numbers."},{"name":"Rentals","description":"Numbers kept for hours to months."},{"name":"Catalogue","description":"Countries, services, live prices."},{"name":"Account","description":"Balance and account metadata."}],"paths":{"/activations":{"post":{"tags":["Activations"],"operationId":"buyNumber","summary":"Buy a number","description":"Reserves a number for the given service. If `country` is omitted the cheapest country with stock is used. Send an `Idempotency-Key` header to make retries safe.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Replaying the same key within 24 h returns the original activation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyRequest"},"examples":{"cheapest":{"summary":"Cheapest country","value":{"service":"telegram"}},"specific":{"summary":"Specific country with a price ceiling","value":{"service":"whatsapp","country":"PT","max_price_cents":25}}}}}},"responses":{"201":{"description":"Number reserved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Activation"}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"409":{"$ref":"#/components/responses/NoStock"},"422":{"$ref":"#/components/responses/Invalid"}}},"get":{"tags":["Activations"],"operationId":"listActivations","summary":"List activations","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["active","waiting","completed","cancelled","expired"]}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":5,"maximum":100,"default":20}}],"responses":{"200":{"description":"A page of activations","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Activation"}},"total":{"type":"integer"}}}}}}}}},"/activations/{id}":{"get":{"tags":["Activations"],"operationId":"getActivation","summary":"Read an activation, optionally long-polling for the code","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"wait","in":"query","schema":{"type":"integer","minimum":0,"maximum":300,"default":0},"description":"Seconds to hold the connection open until a message arrives. Preferred over polling in a loop."}],"responses":{"200":{"description":"Current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Activation"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/activations/{id}/complete":{"post":{"tags":["Activations"],"operationId":"completeActivation","summary":"Close an activation after using the code","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Closed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Activation"}}}}}}},"/activations/{id}/cancel":{"post":{"tags":["Activations"],"operationId":"cancelActivation","summary":"Cancel and refund an activation that received nothing","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelled and refunded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Activation"}}}},"409":{"description":"A message was already delivered — complete it instead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/activations/{id}/resend":{"post":{"tags":["Activations"],"operationId":"requestAnotherSms","summary":"Ask for another SMS on the same number","description":"Billed at 30 % of the original price. Only available on multi-SMS activations.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Listening again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Activation"}}}}}}},"/rentals":{"get":{"tags":["Rentals"],"operationId":"listRentals","summary":"List rentals","responses":{"200":{"description":"Rentals"}}},"post":{"tags":["Rentals"],"operationId":"createRental","summary":"Rent a number for a fixed window","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["country","duration_hours"],"properties":{"country":{"type":"string","minLength":2,"maxLength":2},"service":{"type":"string","description":"Omit or use 'any' for a full rental."},"duration_hours":{"type":"integer","enum":[4,12,24,72,168,720,2160,4320,8760]},"auto_renew":{"type":"boolean","default":false}}}}}},"responses":{"201":{"description":"Rented"},"402":{"$ref":"#/components/responses/PaymentRequired"}}}},"/prices":{"get":{"tags":["Catalogue"],"operationId":"listPrices","summary":"Live prices and stock","security":[],"parameters":[{"name":"service","in":"query","schema":{"type":"string"}},{"name":"country","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","default":100,"maximum":200}}],"responses":{"200":{"description":"Price rows"}}}},"/countries":{"get":{"tags":["Catalogue"],"operationId":"listCountries","summary":"All countries","security":[],"responses":{"200":{"description":"Countries"}}}},"/services":{"get":{"tags":["Catalogue"],"operationId":"listServices","summary":"All services","security":[],"responses":{"200":{"description":"Services"}}}},"/balance":{"get":{"tags":["Account"],"operationId":"getBalance","summary":"Remaining prepaid balance","responses":{"200":{"description":"Balance","content":{"application/json":{"schema":{"type":"object","properties":{"balance_cents":{"type":"integer"},"currency":{"type":"string","const":"EUR"},"can_purchase":{"type":"boolean"}}}}}}}}},"/me":{"get":{"tags":["Account"],"operationId":"getAccount","summary":"Account metadata","responses":{"200":{"description":"Account"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authorization: Bearer vsn_live_..."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Api-Key"}},"schemas":{"BuyRequest":{"type":"object","properties":{"service":{"type":"string","description":"Service slug or short code."},"service_id":{"type":"integer"},"country":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2."},"country_id":{"type":"integer"},"max_price_cents":{"type":"integer","minimum":1},"allow_multiple_sms":{"type":"boolean","default":false}},"anyOf":[{"required":["service"]},{"required":["service_id"]}]},"Message":{"type":"object","properties":{"id":{"type":"string"},"sender":{"type":["string","null"]},"text":{"type":"string"},"code":{"type":["string","null"]},"received_at":{"type":"string","format":"date-time"}}},"Activation":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"activation"},"status":{"type":"string","enum":["pending","waiting","code_received","completed","cancelled","expired","refunded","banned"]},"phone_number":{"type":"string","description":"E.164 without the leading plus."},"country":{"type":"string"},"service":{"type":"string"},"price_cents":{"type":"integer"},"currency":{"type":"string","const":"EUR"},"code":{"type":["string","null"]},"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}},"responses":{"Invalid":{"description":"Request body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NoStock":{"description":"No operator has stock for this combination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PaymentRequired":{"description":"Balance too low, or the mandatory first top-up has not been made","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}