{"openapi":"3.1.0","info":{"title":"CodeySMS API","version":"1","description":"Order one-time phone numbers and rental numbers, and read the SMS codes they receive. Amounts are in EUR, timestamps in UTC. Authenticate with an API key as a Bearer token. Errors are application/problem+json (RFC 9457) with a stable `code` field."},"servers":[{"url":"https://www.codeysms.com/api/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API key from your account, e.g. csk_..."}},"schemas":{"Money":{"type":"object","properties":{"amount":{"type":"string","example":"0.50"},"amount_minor":{"type":"integer","example":50},"currency":{"type":"string","example":"EUR"}}},"Problem":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string","example":"insufficient_balance"},"detail":{"type":"string"},"retryable":{"type":"boolean"}}},"Message":{"type":"object","properties":{"object":{"const":"message"},"sender":{"type":["string","null"]},"text":{"type":"string"},"code":{"type":["string","null"],"description":"Extracted verification code, if one was found."},"received_at":{"type":"string","format":"date-time"}}},"Order":{"type":"object","properties":{"object":{"const":"order"},"id":{"type":"integer"},"status":{"enum":["pending","completed","cancelled","expired"]},"website":{"type":"string","example":"myshop.com"},"country":{"enum":["NL","BE","DE"]},"phone_number":{"type":"string","example":"+31612345678"},"phone_number_local":{"type":"string","example":"0612345678"},"price":{"$ref":"#/components/schemas/Money"},"reusable":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"closed_at":{"type":["string","null"],"format":"date-time"},"code":{"type":["string","null"]},"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}}}},"Rental":{"type":"object","properties":{"object":{"const":"rental"},"id":{"type":"integer"},"status":{"enum":["active","ended"]},"country":{"enum":["NL","BE","DE"]},"phone_number":{"type":"string"},"phone_number_local":{"type":"string"},"plan":{"enum":["m1","m3","m6","m12"]},"months":{"type":"integer"},"price":{"$ref":"#/components/schemas/Money"},"auto_renew":{"type":"boolean"},"started_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"ended_at":{"type":["string","null"],"format":"date-time"}}}}},"paths":{"/account":{"get":{"summary":"Your account and balance","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"account"},"email":{"type":"string"},"balance":{"$ref":"#/components/schemas/Money"},"open_orders":{"type":"integer"}}}}}},"401":{"description":"No or invalid key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/countries":{"get":{"summary":"Countries and whether a number is available","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}}}}}}}}}},"/prices":{"get":{"summary":"Current prices","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/orders":{"get":{"summary":"List your orders, newest first (cursor pagination)","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"enum":["pending","completed","cancelled","expired"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"pagination":{"type":"object"}}}}}}}},"post":{"summary":"Order a one-time number for a website","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["website","country"],"properties":{"website":{"type":"string","example":"myshop.com"},"country":{"enum":["NL","BE","DE"]},"max_price":{"type":"string","example":"0.60","description":"Refuse the order if the price is higher (EUR)."}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"402":{"description":"insufficient_balance","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"out_of_stock or concurrent_order_limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"validation_failed, invalid_website, website_blocked, country_not_supported or price_above_maximum","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/orders/{id}":{"get":{"summary":"One order","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"404":{"description":"order_not_found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/orders/{id}/messages":{"get":{"summary":"Messages of an order (poll until data is non-empty)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"order_id":{"type":"integer"},"order_status":{"type":"string"}}}}}}}}},"/orders/{id}/cancel":{"post":{"summary":"Cancel an open order (money back)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"409":{"description":"order_not_open","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/orders/{id}/reuse":{"post":{"summary":"Order the same number again for the same website (half price)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"409":{"description":"number_unavailable or number_busy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"order_not_completed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/rentals":{"get":{"summary":"Your rentals","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Rental"}}}}}}}}},"post":{"summary":"Rent a number","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["plan","country"],"properties":{"plan":{"enum":["m1","m3","m6","m12"]},"country":{"enum":["NL","BE","DE"]},"auto_renew":{"type":"boolean","default":true}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rental"}}}},"402":{"description":"insufficient_balance","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"out_of_stock","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"invalid_plan","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/rentals/{id}":{"get":{"summary":"One rental","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rental"}}}},"404":{"description":"rental_not_found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/rentals/{id}/messages":{"get":{"summary":"Messages received on a rental (newest first, last 100)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"rental_id":{"type":"integer"}}}}}}}}},"/rentals/{id}/auto-renew":{"post":{"summary":"Turn auto-renewal on or off","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rental"}}}}}}}}}