{"openapi":"3.1.0","info":{"title":"SMSZ API","version":"2026-07-01","summary":"Programmatic access to SMSZ virtual numbers.","description":"Buy single-use numbers for SMS verification, rent numbers long term, and receive incoming messages as webhooks.\n\nAuthenticate with `Authorization: Bearer smsz_live_...`. Generate a key from your account menu at https://www.smsz.net.\n\nAll amounts are USD. All timestamps are ISO 8601 in UTC. Purchases are charged against your account balance.","contact":{"name":"SMSZ Support","email":"support@smsz.net","url":"https://www.smsz.net/contact"},"termsOfService":"https://www.smsz.net/terms-of-use"},"servers":[{"url":"https://www.smsz.net/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Account"},{"name":"Catalogue"},{"name":"Activations"},{"name":"Rentals"},{"name":"Webhooks"}],"paths":{"/ping":{"get":{"operationId":"ping","summary":"Verify your API key","description":"Confirms a key is valid and reports which account and scopes it carries. Make this your first call when setting up an integration.","tags":["Account"],"security":[{"bearerAuth":["account:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"object":"ping","ok":true,"api_version":"2026-07-01","account_email":"you@example.com","key_name":"Production server","scopes":["account:read","activations:write"]}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/account":{"get":{"operationId":"getAccount","summary":"Retrieve your account","description":"Returns your current balance and how many activations and rentals are live.","tags":["Account"],"security":[{"bearerAuth":["account:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"object":"account","id":"cmg7w1a2b0000l208ff11aaaa","email":"you@example.com","username":null,"balance":42.75,"currency":"USD","created_at":"2026-01-04T08:00:00.000Z","active_activations":1,"active_rentals":2}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/transactions":{"get":{"operationId":"listTransactions","summary":"List transactions","description":"Your ledger: purchases, refunds and deposits, newest first.","tags":["Account"],"security":[{"bearerAuth":["account:read"]}],"parameters":[{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["deposit","withdrawal","sms_purchase","number_rental","refund"]},"description":"Filter by transaction type."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","completed","failed","cancelled"]},"description":"Filter by status."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":25,"maximum":100},"description":"Page size, 1-100."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0},"description":"Rows to skip."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"object":"list","data":[{"id":"cmg7xd4u90008l208p7q1rstu","object":"transaction","type":"sms_purchase","status":"completed","amount":-0.62,"currency":"USD","description":"SMS purchase for telegram (US)","created_at":"2026-07-24T10:15:03.000Z"}],"has_more":false,"total":1}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/countries":{"get":{"operationId":"listCountries","summary":"List countries","description":"Every country we sell numbers in. Use `code` when creating an activation.","tags":["Catalogue"],"security":[{"bearerAuth":["activations:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"object":"list","data":[{"code":"US","name":"United States","full_name":"United States of America","slug":"united-states","phone_code":"+1","continent":"north_america"}],"has_more":false,"total":1}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/services":{"get":{"operationId":"listServices","summary":"List services","description":"Every service you can verify. Use `slug` when creating an activation.","tags":["Catalogue"],"security":[{"bearerAuth":["activations:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"object":"list","data":[{"slug":"telegram","name":"Telegram","full_name":"Telegram Messenger","popular":true}],"has_more":false,"total":1}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pricing/activations":{"get":{"operationId":"listActivationPricing","summary":"Live activation prices","description":"Current prices and stock, queried live from our providers. You must pass `country`, `service`, or both — an unfiltered sweep would price every country against every service.","tags":["Catalogue"],"security":[{"bearerAuth":["activations:read"]}],"parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string"},"description":"Country code, slug or name, e.g. `US`."},{"name":"service","in":"query","required":false,"schema":{"type":"string"},"description":"Service slug, e.g. `telegram`."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"object":"list","data":[{"country":"US","country_name":"United States","service":"telegram","service_name":"Telegram","price":0.62,"currency":"USD","available":418,"success_rate":92}],"has_more":false,"total":1}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pricing/rentals":{"get":{"operationId":"listRentalPricing","summary":"Live rental offers","description":"Purchasable long-term rental offers. Pass an offer’s `offer_id` straight to `POST /rentals` — it is an opaque, short-lived token that carries everything needed to fill the order.","tags":["Catalogue"],"security":[{"bearerAuth":["rentals:read"]}],"parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by ISO country code."},{"name":"days","in":"query","required":false,"schema":{"type":"integer"},"description":"Filter by rental length in days."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"object":"list","data":[{"offer_id":"o1.Xn9pQ2s.7Kd1fA.k3mZq0vR8tYw","country":"GB","country_name":"United Kingdom","duration_days":30,"price":14.5,"currency":"USD","available":62}],"has_more":false,"total":1}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/activations":{"post":{"operationId":"createActivation","summary":"Buy an activation","description":"Buys a number for one verification and debits your balance. If the provider cannot fill the order, nothing is charged. Poll `/activations/{id}/messages` for the code, or subscribe to `activation.message.received`.","tags":["Activations"],"security":[{"bearerAuth":["activations:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"A unique string (a UUID works well) that makes this request safe to retry. Retrying with the same key replays the original response instead of buying again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["country","service"],"properties":{"country":{"type":"string","description":"Country code, slug or name, e.g. `US`."},"service":{"type":"string","description":"Service slug, e.g. `telegram`."},"operator":{"type":"string","description":"Optional operator. Omit to let us pick the cheapest available."}}},"example":{"country":"US","service":"telegram"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"id":"cmg7x2k9a0001l208hq3v7bqz","object":"activation","status":"pending","phone_number":"+12025550147","country":"US","country_name":"United States","service":"telegram","service_name":"Telegram","operator":"any","price":0.62,"currency":"USD","created_at":"2026-07-24T10:15:03.000Z","expires_at":"2026-07-24T10:30:03.000Z","messages":[]}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listActivations","summary":"List activations","description":"Your activations, newest first, each with any messages received.","tags":["Activations"],"security":[{"bearerAuth":["activations:read"]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","completed","cancelled","expired","refunded"]},"description":"Filter by status."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":25,"maximum":100},"description":"Page size, 1-100."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0},"description":"Rows to skip."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"object":"list","data":[{"id":"cmg7x2k9a0001l208hq3v7bqz","object":"activation","status":"pending","phone_number":"+12025550147","country":"US","country_name":"United States","service":"telegram","service_name":"Telegram","operator":"any","price":0.62,"currency":"USD","created_at":"2026-07-24T10:15:03.000Z","expires_at":"2026-07-24T10:30:03.000Z","messages":[]}],"has_more":false,"total":1}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/activations/{id}":{"get":{"operationId":"getActivation","summary":"Retrieve an activation","description":"One activation and its messages.","tags":["Activations"],"security":[{"bearerAuth":["activations:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Activation id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"id":"cmg7x2k9a0001l208hq3v7bqz","object":"activation","status":"pending","phone_number":"+12025550147","country":"US","country_name":"United States","service":"telegram","service_name":"Telegram","operator":"any","price":0.62,"currency":"USD","created_at":"2026-07-24T10:15:03.000Z","expires_at":"2026-07-24T10:30:03.000Z","messages":[]}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/activations/{id}/messages":{"get":{"operationId":"listActivationMessages","summary":"Poll for the code","description":"Asks the provider directly, so a message that has not reached us by webhook yet still appears. Poll every 3-5 seconds; webhooks are the better integration if you can host an endpoint.","tags":["Activations"],"security":[{"bearerAuth":["activations:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Activation id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"object":"list","data":[{"id":"cmg7xb1s70006l208r9y2mnop","object":"message","sender":"Telegram","text":"Telegram code 51284","code":"51284","received_at":"2026-07-24T10:16:44.000Z"}],"has_more":false,"total":1}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/activations/{id}/cancel":{"post":{"operationId":"cancelActivation","summary":"Cancel an activation","description":"Cancels an unused activation and refunds it. Once a message has arrived the activation has delivered what it was bought for, so the cancellation succeeds with `refund_amount: 0`.","tags":["Activations"],"security":[{"bearerAuth":["activations:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Activation id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"id":"cmg7x2k9a0001l208hq3v7bqz","object":"activation","status":"refunded","phone_number":"+12025550147","country":"US","country_name":"United States","service":"telegram","service_name":"Telegram","operator":"any","price":0.62,"currency":"USD","created_at":"2026-07-24T10:15:03.000Z","expires_at":"2026-07-24T10:30:03.000Z","messages":[],"refund_amount":0.62,"refund_reason":"Full refund - No SMS received"}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/activations/{id}/finish":{"post":{"operationId":"finishActivation","summary":"Finish an activation","description":"Closes an activation once you have used the code, releasing the number back to the provider. If no message ever arrived, finishing also refunds the purchase.","tags":["Activations"],"security":[{"bearerAuth":["activations:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Activation id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"id":"cmg7x2k9a0001l208hq3v7bqz","object":"activation","status":"completed","phone_number":"+12025550147","country":"US","country_name":"United States","service":"telegram","service_name":"Telegram","operator":"any","price":0.62,"currency":"USD","created_at":"2026-07-24T10:15:03.000Z","expires_at":"2026-07-24T10:30:03.000Z","messages":[],"refund_amount":0}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rentals":{"post":{"operationId":"createRental","summary":"Order a rental","description":"Rents a number for days or months. Take an `offer_id` from `GET /pricing/rentals` and pass it back — the offer already fixes the country, length and price.","tags":["Rentals"],"security":[{"bearerAuth":["rentals:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"A unique string (a UUID works well) that makes this request safe to retry. Retrying with the same key replays the original response instead of buying again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["offer_id"],"properties":{"offer_id":{"type":"string","description":"The `offer_id` from `GET /pricing/rentals`. Offers expire after 30 minutes — fetch a fresh one if yours is rejected."},"service":{"type":"string","description":"Optional. Rent one service on the number instead of the whole number, which is cheaper."},"auto_renew":{"type":"boolean","description":"Optional. Renew automatically at expiry, where the offer supports it."}}},"example":{"offer_id":"o1.Xn9pQ2s.7Kd1fA.k3mZq0vR8tYw"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"id":"cmg7x9p2r0004l208d1w4kzab","object":"rental","status":"active","phone_number":"+447700900123","country":"GB","country_name":"United Kingdom","service":"full","service_name":"Full Rent","nickname":null,"auto_renew":false,"price":14.5,"currency":"USD","created_at":"2026-07-24T10:20:11.000Z","expires_at":"2026-08-23T10:20:11.000Z","messages":[]}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listRentals","summary":"List rentals","description":"Your long-term rentals, newest first.","tags":["Rentals"],"security":[{"bearerAuth":["rentals:read"]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","active","expired","cancelled","refunded"]},"description":"Filter by status."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":25,"maximum":100},"description":"Page size, 1-100."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0},"description":"Rows to skip."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"object":"list","data":[{"id":"cmg7x9p2r0004l208d1w4kzab","object":"rental","status":"active","phone_number":"+447700900123","country":"GB","country_name":"United Kingdom","service":"full","service_name":"Full Rent","nickname":null,"auto_renew":false,"price":14.5,"currency":"USD","created_at":"2026-07-24T10:20:11.000Z","expires_at":"2026-08-23T10:20:11.000Z","messages":[]}],"has_more":false,"total":1}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rentals/{id}":{"get":{"operationId":"getRental","summary":"Retrieve a rental","description":"One rental and its messages.","tags":["Rentals"],"security":[{"bearerAuth":["rentals:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Rental id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"id":"cmg7x9p2r0004l208d1w4kzab","object":"rental","status":"active","phone_number":"+447700900123","country":"GB","country_name":"United Kingdom","service":"full","service_name":"Full Rent","nickname":null,"auto_renew":false,"price":14.5,"currency":"USD","created_at":"2026-07-24T10:20:11.000Z","expires_at":"2026-08-23T10:20:11.000Z","messages":[]}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rentals/{id}/messages":{"get":{"operationId":"listRentalMessages","summary":"List rental messages","description":"Every message received on the rental, newest first. Polls the provider before answering.","tags":["Rentals"],"security":[{"bearerAuth":["rentals:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Rental id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"object":"list","data":[{"id":"cmg7xb1s70006l208r9y2mnop","object":"message","sender":"Telegram","text":"Telegram code 51284","code":"51284","received_at":"2026-07-24T10:16:44.000Z"}],"has_more":false,"total":1}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rentals/{id}/extend":{"post":{"operationId":"extendRental","summary":"Extend a rental","description":"Adds time to a live rental and charges your balance. Expired rentals cannot be extended — order a new one.","tags":["Rentals"],"security":[{"bearerAuth":["rentals:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Rental id."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"A unique string (a UUID works well) that makes this request safe to retry. Retrying with the same key replays the original response instead of buying again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["days"],"properties":{"days":{"type":"integer","description":"Days to add, 1-365."},"auto_renew":{"type":"boolean","description":"Optional. Renew automatically at expiry, where the rental supports it."}}},"example":{"days":30}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"id":"cmg7x9p2r0004l208d1w4kzab","object":"rental","status":"active","phone_number":"+447700900123","country":"GB","country_name":"United Kingdom","service":"full","service_name":"Full Rent","nickname":null,"auto_renew":false,"price":14.5,"currency":"USD","created_at":"2026-07-24T10:20:11.000Z","expires_at":"2026-08-23T10:20:11.000Z","messages":[],"extended_hours":720,"amount_charged":14.5}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rentals/{id}/cancel":{"post":{"operationId":"cancelRental","summary":"Cancel a rental","description":"Cancels and refunds a rental. Only possible within 120 minutes of purchase and only if no message has been received — that is the window our providers give us.","tags":["Rentals"],"security":[{"bearerAuth":["rentals:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Rental id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"id":"cmg7x9p2r0004l208d1w4kzab","object":"rental","status":"refunded","phone_number":"+447700900123","country":"GB","country_name":"United Kingdom","service":"full","service_name":"Full Rent","nickname":null,"auto_renew":false,"price":14.5,"currency":"USD","created_at":"2026-07-24T10:20:11.000Z","expires_at":"2026-08-23T10:20:11.000Z","messages":[],"refund_amount":14.5,"refund_reason":"Full refund - No SMS received"}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/endpoints":{"post":{"operationId":"createWebhookEndpoint","summary":"Create a webhook endpoint","description":"Registers an HTTPS URL to receive events. The response contains the signing `secret` — this is the only time it is returned, so store it now.","tags":["Webhooks"],"security":[{"bearerAuth":["webhooks:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"HTTPS URL to deliver to. Must be publicly reachable."},"events":{"type":"array","description":"Event types to subscribe to. Defaults to `[\"*\"]` (everything)."},"description":{"type":"string","description":"Optional label, up to 160 characters."}}},"example":{"url":"https://example.com/hooks/smsz","events":["activation.message.received","rental.message.received"],"description":"Production listener"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"id":"cmg7xf7w1000al208z3a5vwxy","object":"webhook_endpoint","url":"https://example.com/hooks/smsz","description":"Production listener","events":["activation.message.received","rental.message.received"],"status":"active","api_version":"2026-07-01","secret":"whsec_p9Qk…","created_at":"2026-07-24T10:30:00.000Z","last_success_at":null,"last_error_at":null,"last_error":null}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listWebhookEndpoints","summary":"List webhook endpoints","description":"Your configured endpoints. Secrets are never included.","tags":["Webhooks"],"security":[{"bearerAuth":["webhooks:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"object":"list","data":[],"has_more":false,"total":0}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/endpoints/{id}":{"get":{"operationId":"getWebhookEndpoint","summary":"Retrieve a webhook endpoint","description":"One endpoint, including when it last succeeded or failed.","tags":["Webhooks"],"security":[{"bearerAuth":["webhooks:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Endpoint id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateWebhookEndpoint","summary":"Update a webhook endpoint","description":"Change the URL, subscriptions or description. Send `status: \"active\"` to re-enable an endpoint we disabled after repeated failures — this also resets its failure counter.","tags":["Webhooks"],"security":[{"bearerAuth":["webhooks:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Endpoint id."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"url":{"type":"string","description":"New HTTPS URL."},"events":{"type":"array","description":"Replacement subscription list."},"description":{"type":"string","description":"New label."},"status":{"type":"string","description":"Enable or disable the endpoint.","enum":["active","disabled"]}}},"example":{"events":["*"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteWebhookEndpoint","summary":"Delete a webhook endpoint","description":"Removes the endpoint and any deliveries still queued for it.","tags":["Webhooks"],"security":[{"bearerAuth":["webhooks:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Endpoint id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"id":"cmg7xf7w1000al208z3a5vwxy","object":"webhook_endpoint","deleted":true}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/endpoints/{id}/test":{"post":{"operationId":"testWebhookEndpoint","summary":"Send a test event","description":"Delivers a real, correctly signed event with obviously fake data, and reports exactly what your endpoint answered. Use it to verify signature checking before going live.","tags":["Webhooks"],"security":[{"bearerAuth":["webhooks:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Endpoint id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"object":"webhook_test","endpoint_id":"cmg7xf7w1000al208z3a5vwxy","delivered":true,"response_status":200,"duration_ms":143,"error":null}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/deliveries":{"get":{"operationId":"listWebhookDeliveries","summary":"List deliveries","description":"What was sent, what your endpoint answered, how many attempts it took and when the next retry is due. Start here when events are not arriving.","tags":["Webhooks"],"security":[{"bearerAuth":["webhooks:read"]}],"parameters":[{"name":"endpoint_id","in":"query","required":false,"schema":{"type":"string"},"description":"Filter to one endpoint."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","succeeded","failed"]},"description":"Filter by delivery status."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":25,"maximum":100},"description":"Page size, 1-100."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0},"description":"Rows to skip."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events":{"get":{"operationId":"listEvents","summary":"List events","description":"Every event on your account, whether or not you have a webhook endpoint. Poll this with `after` set to the last event id you processed if you cannot host an endpoint. Retained for 30 days.","tags":["Webhooks"],"security":[{"bearerAuth":["webhooks:read"]}],"parameters":[{"name":"type","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by event type."},{"name":"object_id","in":"query","required":false,"schema":{"type":"string"},"description":"Filter to one activation or rental."},{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"Return only events after this event id."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":25,"maximum":100},"description":"Page size, 1-100."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0},"description":"Rows to skip."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your API key, sent as `Authorization: Bearer smsz_live_...`."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Coarse error class."},"code":{"type":"string","description":"Machine-readable reason.","enum":["missing_api_key","invalid_api_key","expired_api_key","revoked_api_key","insufficient_scope","ip_not_allowed","account_blocked","invalid_body","missing_parameter","invalid_parameter","insufficient_balance","resource_not_found","number_unavailable","not_cancellable","not_extendable","resource_conflict","idempotency_request_in_progress","idempotency_key_reused","rate_limit_exceeded","internal_error","provider_rejected","provider_unavailable"]},"message":{"type":"string","description":"Human-readable explanation."},"param":{"type":"string","description":"The offending request field, when applicable."},"doc_url":{"type":"string"},"request_id":{"type":"string","description":"Quote this when contacting support."}},"required":["type","code","message","request_id"]}}}}},"x-scopes":["account:read","activations:read","activations:write","rentals:read","rentals:write","webhooks:read","webhooks:write"],"x-webhooks":{"signature_header":"SMSZ-Signature","signature_format":"t=<unix seconds>,v1=<hex hmac-sha256 of \"{timestamp}.{body}\">","max_attempts":8,"retry_schedule_seconds":[10,30,120,600,1800,7200,21600,43200],"events":[{"type":"activation.created","description":"An activation was purchased and its number is ready to receive SMS."},{"type":"activation.message.received","description":"An SMS arrived on an activation. The extracted verification code is in `data.messages[0].code` when one could be parsed."},{"type":"activation.completed","description":"An activation was marked finished and will receive no further messages."},{"type":"activation.cancelled","description":"An activation was cancelled before use and the balance was refunded."},{"type":"activation.expired","description":"An activation reached its expiry window without receiving an SMS."},{"type":"activation.refunded","description":"The balance for an activation was returned to the account."},{"type":"rental.created","description":"A long-term rental was ordered. It may still be provisioning."},{"type":"rental.activated","description":"A rental finished provisioning and is now live."},{"type":"rental.message.received","description":"An SMS arrived on a rental number."},{"type":"rental.extended","description":"A rental was extended and its expiry moved forward."},{"type":"rental.expiring","description":"A rental expires within 24 hours."},{"type":"rental.expired","description":"A rental reached the end of its period and stopped receiving messages."},{"type":"rental.cancelled","description":"A rental was cancelled."},{"type":"balance.updated","description":"The account balance changed."}]}}