{ "openapi": "3.0.0", "info": { "title": "Quackr API", "version": "1.0.0", "description": "Comprehensive API for temporary phone number rental, SMS verification, per-service dedicated numbers, and virtual card management. Purchase phone numbers from multiple countries, receive SMS messages, manage account balance, check inventory availability, configure webhook notifications for real-time SMS delivery, rent per-service numbers for specific platforms (WhatsApp, Telegram, etc.), and create/manage virtual credit cards.\n\n## Common Properties\n\n### Duration Values\nThe `duration` field is used across multiple endpoints and accepts the following values:\n\n| Value | Duration |\n|-------|----------|\n| `halfDay` | 12 hours |\n| `oneDay` | 24 hours |\n| `oneWeek` | 7 days |\n| `oneMonth` | 30 days |\n| `sixMonths` | 180 days |\n| `twelveMonths` | 365 days |\n\n### Locale Values\nThe `locale` field specifies the country for phone numbers:\n\n| Code | Country |\n|------|----------|\n| `US` | United States |\n| `UK` | United Kingdom |\n| `NL` | Netherlands |\n| `HK` | Hong Kong |\n| `AU` | Australia |\n| `CA` | Canada |\n| `FI` | Finland |\n| `DE` | Germany |\n| `ES` | Spain |\n| `LT` | Lithuania |\n| `MX` | Mexico |\n| `IL` | Israel |\n| `PL` | Poland |\n| `IT` | Italy |\n| `AT` | Austria |\n| `SI` | Slovenia |\n| `CH` | Switzerland |\n| `BE` | Belgium |" }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" } } }, "security": [ { "ApiKeyAuth": [] } ], "paths": { "/purchase": { "post": { "summary": "Purchase phone numbers", "description": "Purchase one or more phone numbers for a specified duration and locale. Only certain locales support bulk quantities - please contact support if you need more info.", "tags": [ "Phone Numbers (Unlimited)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "duration", "locale" ], "properties": { "duration": { "type": "string", "enum": [ "halfDay", "oneDay", "oneWeek", "oneMonth", "sixMonths", "twelveMonths" ], "example": "oneWeek" }, "locale": { "type": "string", "example": "US" }, "quantity": { "type": "integer", "minimum": 1, "example": 2 }, "carrier": { "type": "string", "enum": ["US1", "US2"], "description": "(US locale only) Select a specific carrier.", "example": "US1" }, "receiveCalls": { "type": "boolean", "description": "(US locale only) Enable the number to receive voice calls. Incoming calls will be transcribed and delivered as SMS messages to your stored messages.", "example": false }, "autoRenew": { "type": "boolean", "description": "Automatically renew the number before it expires, using the same duration.", "example": false } } } } } }, "responses": { "200": { "description": "Successfully purchased phone numbers", "content": { "application/json": { "schema": { "type": "object", "properties": { "phoneNumbers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 12345 }, "number": { "type": "string", "example": "1258747889" } } }, "example": [ { "id": 12345, "number": "1258747889" }, { "id": 12346, "number": "1258746891" } ] }, "duration": { "type": "string", "nullable": true, "example": "1 week" }, "price": { "type": "string", "example": "25.98" }, "locale": { "type": "string", "example": "US" }, "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" } } } } } } } } }, "/renew": { "post": { "summary": "Renew an existing phone number", "description": "Extend the rental period for an existing phone number. For custom time extensions that don't match these presets (like 2 weeks), you would make multiple API requests with the appropriate preset. For example, extending for 2 weeks would require submitting the oneWeek API request twice. Each extension request incrementally adds to the existing rental time period rather than resetting or replacing it.", "tags": [ "Phone Numbers (Unlimited)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "duration", "phoneNumber" ], "properties": { "duration": { "type": "string", "enum": [ "halfDay", "oneDay", "oneWeek", "oneMonth", "sixMonths", "twelveMonths" ], "example": "oneWeek" }, "phoneNumber": { "type": "string", "example": "447366085728" }, "locale": { "type": "string", "description": "Optional locale override. Useful when countries share the same mobile prefix (e.g. US and CA both use +1).", "example": "CA" }, "autoRenew": { "type": "boolean", "description": "Automatically renew the number before it expires, using the same duration.", "example": false } } } } } }, "responses": { "200": { "description": "Successfully renewed phone number", "content": { "application/json": { "schema": { "type": "object", "properties": { "phoneNumbers": { "type": "array", "items": { "type": "string" }, "example": [ "447366085728" ] }, "id": { "type": "string", "example": "447366085728" }, "rentalEndDate": { "type": "number", "example": 1733918884113 }, "price": { "type": "number", "format": "float", "example": 12.99 }, "locale": { "type": "string", "example": "UK" }, "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Invalid phone number format" } } } } } } } } }, "/cancel": { "post": { "summary": "Cancel a phone number rental", "description": "Cancel a recently purchased phone number and receive a refund. Numbers can only be cancelled within 120 minutes / 2 hours of purchase and must not have received any SMS messages.", "tags": [ "Phone Numbers (Unlimited)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phoneNumber" ], "properties": { "phoneNumber": { "type": "string", "description": "The phone number to cancel (with or without + prefix)", "example": "447366085728" } } } } } }, "responses": { "200": { "description": "Successfully cancelled the phone number", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Cancellation not allowed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Number is older than 20 minutes and cannot be cancelled" } } }, "examples": { "tooOld": { "summary": "Number too old", "value": { "success": false, "error": "Number is older than 20 minutes and cannot be cancelled" } }, "hasMessages": { "summary": "Number received SMS", "value": { "success": false, "error": "Number has received SMS and cannot be cancelled" } }, "alreadyCancelled": { "summary": "Already cancelled", "value": { "success": false, "error": "Number has already been cancelled" } } } } } }, "404": { "description": "Number not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Number does not exist or is not assigned to your account" } } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Missing or Incorrect API Key" } } } } } } } } }, "/balance": { "get": { "summary": "Get account balance", "description": "Retrieve the current balance and currency for the account", "tags": [ "Account" ], "responses": { "200": { "description": "Successfully retrieved balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "balance": { "type": "number", "example": 50 }, "currency": { "type": "string", "example": "USD" } } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Invalid API key" } } } } } } } } }, "/pricing": { "get": { "summary": "Get pricing for a country", "description": "Retrieve pricing information for all durations for a specific country. Returns user-specific pricing if custom price overrides are configured, otherwise returns standard pricing.", "tags": [ "Phone Numbers (Unlimited)" ], "parameters": [ { "in": "query", "name": "locale", "required": true, "schema": { "type": "string" }, "example": "US", "description": "Country code for phone numbers (e.g., US, UK, DE)" }, { "in": "query", "name": "carrier", "required": false, "schema": { "type": "string", "enum": ["US1", "US2"] }, "example": "US1", "description": "(US and UK locale only) Get carrier-specific pricing if configured" } ], "responses": { "200": { "description": "Successfully retrieved pricing", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "locale": { "type": "string", "example": "US" }, "currency": { "type": "string", "example": "USD" }, "pricing": { "type": "object", "properties": { "halfDay": { "type": "string", "example": "2.99" }, "oneDay": { "type": "string", "example": "4.99" }, "oneWeek": { "type": "string", "example": "14.99" }, "oneMonth": { "type": "string", "example": "19.99" }, "sixMonths": { "type": "string", "example": "99.99" }, "twelveMonths": { "type": "string", "example": "139.99" } } } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" } } }, "examples": { "missingLocale": { "summary": "Missing locale", "value": { "success": false, "error": "Missing locale parameter" } }, "invalidLocale": { "summary": "Invalid locale", "value": { "success": false, "error": "Invalid locale" } }, "invalidCarrier": { "summary": "Invalid carrier", "value": { "success": false, "error": "Invalid carrier" } } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Missing or Incorrect API Key" } } } } } } } } }, "/receive-sms": { "post": { "summary": "Receive SMS messages", "description": "Retrieve SMS messages for a specific phone number", "tags": [ "Phone Numbers (Unlimited)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["phoneNumber"], "properties": { "phoneNumber": { "type": "string", "example": "447366087973" } } } } } }, "responses": { "200": { "description": "Successfully retrieved messages", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "sender": { "type": "string", "example": "quackr" }, "received": { "type": "number", "example": 1733359011883 }, "message": { "type": "string", "example": "quackr SMS status test: 447366087973. Please Ignore." } } } } } } } } } } }, "400": { "description": "Invalid phone number format", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Invalid phone number format" } } } } } } } } }, "/active-numbers": { "get": { "summary": "Get active phone numbers", "description": "Retrieve currently active/rented phone numbers for the account with optional pagination", "tags": [ "Phone Numbers (Unlimited)" ], "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000 }, "example": 100, "description": "Maximum number of results to return. If not specified, returns all numbers efficiently." } ], "responses": { "200": { "description": "Successfully retrieved active numbers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "activeNumbers": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "example": "UK" }, "nickname": { "type": "string", "example": "telegram acc 1" }, "number": { "type": "string", "example": "447366085728" }, "rentalStartDate": { "type": "number", "example": 1640995200000 }, "rentalEndDate": { "type": "number", "example": 1733918884113 } } } } } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Invalid API key" } } } } } } } } }, "/recent-numbers": { "get": { "summary": "Get recently purchased phone numbers", "description": "Returns numbers assigned to your account in the last N minutes (newest first), plus a count of any orders still being provisioned. Designed for high-frequency buyers polling for fresh purchases. Async carriers (e.g. some US carriers) may take a few minutes to provision a number after order — those orders show up in `pending.count` until the number is assigned.", "tags": [ "Phone Numbers (Unlimited)" ], "parameters": [ { "in": "query", "name": "lastMinutes", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1440, "default": 60 }, "example": 60, "description": "Window size in minutes (max 1440 / 24h). Defaults to 60." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 500 }, "example": 100, "description": "Maximum number of assigned numbers to return (max 500). Defaults to 500." } ], "responses": { "200": { "description": "Successfully retrieved recent numbers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "windowMinutes": { "type": "integer", "example": 60, "description": "The window size that was applied to this query." }, "activeNumbers": { "type": "array", "description": "Numbers assigned within the window, sorted newest first.", "items": { "type": "object", "properties": { "locale": { "type": "string", "example": "US" }, "number": { "type": "string", "example": "13057872101" }, "nickname": { "type": "string", "example": "telegram acc 1" }, "rentalStartDate": { "type": "number", "example": 1714400000000 }, "rentalEndDate": { "type": "number", "example": 1717078400000 } } } }, "pending": { "type": "object", "description": "Orders still being provisioned. Includes ALL outstanding orders regardless of the time window, so a stuck order is visible even on a short window.", "properties": { "count": { "type": "integer", "example": 3, "description": "How many ordered numbers are still pending assignment." } } } } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Invalid API key" } } } } } } } } }, "/nickname": { "get": { "summary": "Get nickname for a phone number", "description": "Retrieve the nickname associated with a specific phone number", "tags": ["Phone Numbers (Unlimited)"], "parameters": [ { "in": "query", "name": "phoneNumber", "required": true, "schema": { "type": "string" }, "example": "447366087973", "description": "Phone number to get nickname for" } ], "responses": { "200": { "description": "Successfully retrieved nickname", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "phoneNumber": { "type": "string", "example": "447366087973" }, "nickname": { "type": "string", "example": "My Telegram Account" } } } } } }, "400": { "description": "Invalid phone number format", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Invalid phone number format" } } } } } } } }, "post": { "summary": "Set nickname for a phone number", "description": "Set or update the nickname for a specific phone number", "tags": ["Phone Numbers (Unlimited)"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["phoneNumber", "nickname"], "properties": { "phoneNumber": { "type": "string", "example": "447366087973" }, "nickname": { "type": "string", "example": "My Telegram Account", "maxLength": 100, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9 ]+$" } } } } } }, "responses": { "200": { "description": "Successfully set nickname", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "phoneNumber": { "type": "string", "example": "447366087973" }, "nickname": { "type": "string", "example": "My Telegram Account" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Invalid nickname format. Must be alphanumeric and max 100 characters." } } } } } } } } }, "/inventory": { "get": { "summary": "Get inventory information", "description": "Retrieve available phone number inventory information for a specified locale and duration", "tags": ["Inventory"], "parameters": [ { "in": "query", "name": "locale", "required": true, "schema": { "type": "string" }, "example": "US", "description": "Country code for phone numbers" }, { "in": "query", "name": "duration", "required": true, "schema": { "type": "string", "enum": ["halfDay", "oneDay", "oneWeek", "oneMonth", "sixMonths", "twelveMonths"] }, "example": "sixMonths", "description": "Duration period for phone number rental" }, { "in": "query", "name": "carrier", "required": false, "schema": { "type": "string", "enum": ["US1", "US2"] }, "example": "US1", "description": "(US locale only) Get inventory for a specific carrier" } ], "responses": { "200": { "description": "Successfully retrieved inventory information", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "inventory": { "type": "integer", "example": 20 }, "locale": { "type": "string", "example": "US" }, "duration": { "type": "string", "example": "sixMonths" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Invalid locale or duration specified" } } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Invalid API key" } } } } } } } } }, "/number": { "get": { "summary": "Get specific number details", "description": "Retrieve details for a specific phone number owned by the user", "tags": ["Phone Numbers (Unlimited)"], "parameters": [ { "in": "query", "name": "phoneNumber", "required": true, "schema": { "type": "string" }, "example": "447366087973", "description": "Phone number to get details for" } ], "responses": { "200": { "description": "Successfully retrieved number details", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "number": { "type": "object", "properties": { "locale": { "type": "string", "example": "UK" }, "number": { "type": "string", "example": "447366087973" }, "nickname": { "type": "string", "example": "My Test Number" }, "rentalStartDate": { "type": "number", "example": 1640995200000 }, "rentalEndDate": { "type": "number", "example": 1641081600000 } } } } } } } }, "404": { "description": "Number not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Number not found or not assigned to your account" } } } } } } } } }, "/expiring-numbers": { "get": { "summary": "Get numbers expiring soon", "description": "Retrieve phone numbers that are expiring within the next 24 hours", "tags": ["Phone Numbers (Unlimited)"], "responses": { "200": { "description": "Successfully retrieved expiring numbers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "expiringNumbers": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "example": "US" }, "number": { "type": "string", "example": "12345678901" }, "nickname": { "type": "string", "example": "My Test Number" }, "rentalStartDate": { "type": "number", "example": 1640995200000 }, "rentalEndDate": { "type": "number", "example": 1641081600000 }, "minutesRemaining": { "type": "number", "example": 1080 } } } }, "count": { "type": "number", "example": 2 } } } } } } } } }, "/webhook": { "get": { "summary": "Get webhook URL", "description": "Retrieve the current webhook URL for receiving SMS notifications", "tags": ["Webhooks"], "responses": { "200": { "description": "Successfully retrieved webhook URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "webhookUrl": { "type": "string", "example": "https://example.com/webhook" } } } } } } } }, "post": { "summary": "Set webhook URL", "description": "Set or update the webhook URL for receiving SMS notifications. When an SMS is received, your webhook will receive a POST request with the payload format shown in the response examples.", "tags": ["Webhooks"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["webhookUrl"], "properties": { "webhookUrl": { "type": "string", "format": "uri", "example": "https://example.com/webhook", "maxLength": 300, "pattern": "^https://" } } } } } }, "responses": { "200": { "description": "Successfully set webhook URL. When SMS messages are received, your webhook endpoint will receive POST requests with the following payload structure:", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } }, "examples": { "success_response": { "summary": "Successful webhook setup", "value": { "success": true } }, "webhook_payload": { "summary": "Example webhook payload your endpoint will receive", "description": "This is the format of POST requests sent to your webhook URL when SMS messages are received", "value": { "event": "EVENT.WEBHOOK", "data": { "sender": "0018333022004", "received": 1744987577783, "message": "BulkSMS.com covers over 1200 networks worldwide, including yours!", "recipient": "19498470744" }, "timestamp": 1744987580733 } } } } } }, "400": { "description": "Invalid webhook URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Please enter a valid webhook URL" } } } } } } } } }, "/cards": { "post": { "summary": "Create a virtual card", "description": "Create a new virtual credit card. The card amount is deducted from your account balance. Cards are created instantly and can be used immediately for online purchases.", "tags": ["Virtual Cards"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name", "amount"], "properties": { "name": { "type": "string", "description": "Display name for the card", "example": "Shopping Card" }, "amount": { "type": "number", "description": "Initial balance to load onto the card (USD)", "minimum": 1, "example": 50 }, "walletType": { "type": "string", "enum": ["none", "apple", "google"], "default": "none", "description": "Wallet compatibility for the card" } } } } } }, "responses": { "201": { "description": "Card created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Card created successfully" }, "data": { "type": "object", "properties": { "id": { "type": "string", "example": "card_abc123xyz" }, "status": { "type": "string", "enum": ["active", "frozen", "deactivated"], "example": "active" }, "balance": { "type": "number", "example": 50 }, "cardNumber": { "type": "string", "example": "4111111111111111" }, "cvv": { "type": "string", "example": "123" }, "expiryMonth": { "type": "string", "example": "12" }, "expiryYear": { "type": "string", "example": "2027" }, "cardholderName": { "type": "string", "example": "QUACKR USER" }, "cardType": { "type": "string", "example": "VISA" }, "hasApplePay": { "type": "boolean", "example": false }, "hasGooglePay": { "type": "boolean", "example": false } } } } } } } }, "400": { "description": "Invalid request or insufficient balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Insufficient balance" } } } } } } } }, "get": { "summary": "List all cards", "description": "Retrieve all virtual cards associated with your account", "tags": ["Virtual Cards"], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 50 }, "description": "Maximum number of cards to return" } ], "responses": { "200": { "description": "Successfully retrieved cards", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "card_abc123xyz" }, "cardName": { "type": "string", "example": "Shopping Card" }, "status": { "type": "string", "enum": ["active", "frozen", "deactivated"], "example": "active" }, "balance": { "type": "number", "example": 45.50 }, "last4": { "type": "string", "example": "1111" }, "expiryMonth": { "type": "string", "example": "12" }, "expiryYear": { "type": "string", "example": "2027" }, "cardType": { "type": "string", "example": "VISA" }, "hasApplePay": { "type": "boolean", "example": false }, "hasGooglePay": { "type": "boolean", "example": false }, "createdAt": { "type": "number", "example": 1704067200000 } } } }, "count": { "type": "integer", "example": 3 } } } } } } } } }, "/cards/{id}": { "get": { "summary": "Get card details", "description": "Retrieve full details for a specific card including sensitive card information", "tags": ["Virtual Cards"], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Card ID" } ], "responses": { "200": { "description": "Successfully retrieved card details", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "example": "card_abc123xyz" }, "cardName": { "type": "string", "example": "Shopping Card" }, "balance": { "type": "number", "example": 45.50 }, "status": { "type": "string", "example": "active" }, "currency": { "type": "string", "example": "USD" }, "cardNumber": { "type": "string", "example": "4111111111111111" }, "cvv": { "type": "string", "example": "123" }, "expiryMonth": { "type": "string", "example": "12" }, "expiryYear": { "type": "string", "example": "2027" }, "cardholderName": { "type": "string", "example": "QUACKR USER" }, "cardType": { "type": "string", "example": "VISA" }, "hasApplePay": { "type": "boolean", "example": false }, "hasGooglePay": { "type": "boolean", "example": false }, "createdAt": { "type": "number", "example": 1704067200000 } } } } } } } }, "404": { "description": "Card not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Card not found" } } } } } } } } }, "/cards/{id}/freeze": { "post": { "summary": "Freeze a card", "description": "Temporarily freeze a card to prevent any transactions. Optionally transfer the remaining balance back to your account.", "tags": ["Virtual Cards"], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Card ID" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "transferBalance": { "type": "boolean", "default": false, "description": "If true, transfers remaining card balance back to account before freezing" } } } } } }, "responses": { "200": { "description": "Card frozen successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Card frozen successfully" } } } } } } } } }, "/cards/{id}/activate": { "post": { "summary": "Activate a frozen card", "description": "Reactivate a previously frozen card to allow transactions again", "tags": ["Virtual Cards"], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Card ID" } ], "responses": { "200": { "description": "Card activated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Card activated successfully" } } } } } } } } }, "/cards/{id}/transactions": { "get": { "summary": "Get card transactions", "description": "Retrieve transaction history for a specific card", "tags": ["Virtual Cards"], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Card ID" }, { "in": "query", "name": "type", "schema": { "type": "string", "enum": ["debit", "credit", "load", "unload"] }, "description": "Filter by transaction type" }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": ["pending", "completed", "failed", "reversed"] }, "description": "Filter by transaction status" }, { "in": "query", "name": "startDate", "schema": { "type": "integer" }, "description": "Filter transactions after this timestamp (milliseconds)" }, { "in": "query", "name": "endDate", "schema": { "type": "integer" }, "description": "Filter transactions before this timestamp (milliseconds)" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 50 }, "description": "Maximum number of transactions to return" } ], "responses": { "200": { "description": "Successfully retrieved transactions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "txn_123abc" }, "cardId": { "type": "string", "example": "card_abc123xyz" }, "amount": { "type": "number", "example": 9.99 }, "currency": { "type": "string", "example": "USD" }, "type": { "type": "string", "enum": ["debit", "credit", "load", "unload"], "example": "debit" }, "status": { "type": "string", "enum": ["pending", "completed", "failed", "reversed"], "example": "completed" }, "description": { "type": "string", "example": "Purchase at Amazon.com" }, "merchantName": { "type": "string", "example": "Amazon" }, "timestamp": { "type": "number", "example": 1704153600000 } } } }, "count": { "type": "integer", "example": 5 } } } } } } } } }, "/cards/{id}/balance": { "get": { "summary": "Get card balance", "description": "Retrieve the current balance of a specific card", "tags": ["Virtual Cards"], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Card ID" } ], "responses": { "200": { "description": "Successfully retrieved balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "cardId": { "type": "string", "example": "card_abc123xyz" }, "available": { "type": "number", "example": 45.50 }, "pending": { "type": "number", "example": 0 }, "currency": { "type": "string", "example": "USD" } } } } } } } } } } }, "/cards/load": { "post": { "summary": "Load funds onto a card", "description": "Add funds from your account balance onto an existing virtual card", "tags": ["Virtual Cards"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["cardId", "amount"], "properties": { "cardId": { "type": "string", "description": "The ID of the card to load", "example": "card_abc123xyz" }, "amount": { "type": "number", "description": "Amount to load (USD)", "minimum": 0.01, "example": 25 } } } } } }, "responses": { "200": { "description": "Card loaded successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Card loaded successfully" }, "data": { "type": "object", "description": "Transaction details from the load operation" } } } } } }, "400": { "description": "Invalid request or insufficient balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Insufficient balance. Required: $25, Available: $10" } } } } } } } } }, "/cards/unload": { "post": { "summary": "Unload funds from a card", "description": "Withdraw funds from a virtual card back to your account balance", "tags": ["Virtual Cards"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["cardId", "amount"], "properties": { "cardId": { "type": "string", "description": "The ID of the card to unload", "example": "card_abc123xyz" }, "amount": { "type": "number", "description": "Amount to unload (USD)", "minimum": 0.01, "example": 10 } } } } } }, "responses": { "200": { "description": "Card unloaded successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Card unloaded successfully" }, "data": { "type": "object", "description": "Transaction details from the unload operation" } } } } } }, "400": { "description": "Invalid request or insufficient card balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Insufficient card balance" } } } } } } } } }, "/per-service/services": { "get": { "summary": "Get per-service number services and pricing", "description": "Retrieve available services (e.g. WhatsApp, Telegram, Google) with pricing for a specific locale. Per-service numbers are dedicated to receiving SMS from a single service for long-term use. Pricing is returned per duration (oneWeek, oneMonth, sixMonths, twelveMonths).", "tags": ["Per-Service Numbers"], "parameters": [ { "in": "query", "name": "locale", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{2}$" }, "example": "US", "description": "Country code (e.g. US, UK, AU)" } ], "responses": { "200": { "description": "Successfully retrieved services with pricing", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "locale": { "type": "string", "example": "US" }, "services": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Service slug identifier", "example": "wa" }, "name": { "type": "string", "example": "WhatsApp" }, "pricing": { "type": "object", "properties": { "oneWeek": { "type": "string", "example": "2.75" }, "oneMonth": { "type": "string", "example": "4.50" }, "sixMonths": { "type": "string", "example": "13.50" }, "twelveMonths": { "type": "string", "example": "27.00" } } } } } } } } } } }, "400": { "description": "Missing or invalid locale", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Missing required field: locale" } } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Missing or Incorrect API Key" } } } } } } } } }, "/per-service/purchase": { "post": { "summary": "Purchase a per-service number", "description": "Purchase a dedicated phone number for receiving SMS from a specific service (e.g. WhatsApp, Telegram). The number is exclusively assigned to you for the chosen service and duration. Cost is deducted from your account balance.", "tags": ["Per-Service Numbers"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["locale", "service", "duration"], "properties": { "locale": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Country code (e.g. US, UK, AU)", "example": "US" }, "service": { "type": "string", "description": "Service slug from the /per-service/services endpoint", "example": "wa" }, "duration": { "type": "string", "enum": ["oneWeek", "oneMonth", "sixMonths", "twelveMonths"], "example": "oneMonth" } } } } } }, "responses": { "200": { "description": "Successfully purchased per-service number", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "rental": { "type": "object", "properties": { "rentId": { "type": "string", "description": "Unique rental identifier (used for renewals and message retrieval)", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "phoneNumber": { "type": "string", "example": "12025551234" }, "service": { "type": "string", "example": "wa" }, "serviceName": { "type": "string", "example": "WhatsApp" }, "locale": { "type": "string", "example": "US" }, "rentalStartDate": { "type": "number", "example": 1709251200000 }, "rentalEndDate": { "type": "number", "example": 1711843200000 }, "price": { "type": "string", "example": "4.50" } } } } } } } }, "400": { "description": "Invalid request, service not found, insufficient balance, or no availability", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" } } }, "examples": { "insufficientBalance": { "summary": "Insufficient balance", "value": { "success": false, "error": "Insufficient balance. Required: $4.50, Available: $2.00" } }, "noAvailability": { "summary": "No numbers available", "value": { "success": false, "error": "No numbers available for this locale" } }, "serviceNotFound": { "summary": "Service not found", "value": { "success": false, "error": "Service not found" } } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Missing or Incorrect API Key" } } } } } } } } }, "/per-service/renew": { "post": { "summary": "Renew a per-service rental", "description": "Extend the rental period for an existing per-service number. The new duration is added to the current expiry date. Cost is deducted from your account balance.", "tags": ["Per-Service Numbers"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["rentId", "duration"], "properties": { "rentId": { "type": "string", "description": "The rental ID returned from the purchase endpoint", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "duration": { "type": "string", "enum": ["oneWeek", "oneMonth", "sixMonths", "twelveMonths"], "example": "oneMonth" } } } } } }, "responses": { "200": { "description": "Successfully renewed rental", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "rental": { "type": "object", "properties": { "rentId": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "phoneNumber": { "type": "string", "example": "12025551234" }, "service": { "type": "string", "example": "wa" }, "serviceName": { "type": "string", "example": "WhatsApp" }, "locale": { "type": "string", "example": "US" }, "rentalEndDate": { "type": "number", "description": "Updated expiry timestamp (milliseconds)", "example": 1714435200000 } } } } } } } }, "400": { "description": "Invalid request or insufficient balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Insufficient balance. Required: $4.50, Available: $2.00" } } } } } }, "404": { "description": "Rental not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Rental not found" } } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Missing or Incorrect API Key" } } } } } } } } }, "/per-service/rentals": { "get": { "summary": "Get active per-service rentals", "description": "Retrieve all active per-service number rentals for your account", "tags": ["Per-Service Numbers"], "responses": { "200": { "description": "Successfully retrieved rentals", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "rentals": { "type": "array", "items": { "type": "object", "properties": { "rentId": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "phoneNumber": { "type": "string", "example": "12025551234" }, "service": { "type": "string", "example": "wa" }, "serviceName": { "type": "string", "example": "WhatsApp" }, "locale": { "type": "string", "example": "US" }, "rentalStartDate": { "type": "number", "example": 1709251200000 }, "rentalEndDate": { "type": "number", "example": 1711843200000 }, "status": { "type": "string", "enum": ["Rented"], "example": "Rented" }, "messageCount": { "type": "integer", "description": "Number of SMS messages received", "example": 3 }, "nickname": { "type": "string", "nullable": true, "example": "My WhatsApp" } } } } } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Missing or Incorrect API Key" } } } } } } } } }, "/per-service/messages": { "get": { "summary": "Get messages for a per-service rental", "description": "Retrieve all SMS messages received for a specific per-service rental", "tags": ["Per-Service Numbers"], "parameters": [ { "in": "query", "name": "rentId", "required": true, "schema": { "type": "string" }, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "description": "The rental ID to get messages for" } ], "responses": { "200": { "description": "Successfully retrieved messages", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "messages": { "type": "array", "items": { "type": "object", "properties": { "sender": { "type": "string", "example": "12345" }, "message": { "type": "string", "example": "Your WhatsApp code is 123-456" }, "timestamp": { "type": "number", "example": 1709337600000 } } } } } } } } }, "400": { "description": "Missing rentId parameter", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Missing rentId" } } } } } }, "404": { "description": "Rental not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Rental not found" } } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Missing or Incorrect API Key" } } } } } } } } } }, "tags": [ { "name": "Phone Numbers (Unlimited)", "description": "Operations for purchasing, managing, and receiving SMS on unlimited phone numbers. Includes pricing, inventory, nicknames, and number management." }, { "name": "Per-Service Numbers", "description": "Operations for purchasing and managing per-service dedicated phone numbers. Each number is exclusively assigned to receive SMS from a single service (e.g. WhatsApp, Telegram, Google) for long-term use. Available durations: oneWeek, oneMonth, sixMonths, twelveMonths." }, { "name": "Account", "description": "Operations for managing account details and balance" }, { "name": "Inventory", "description": "Operations for checking phone number availability and inventory" }, { "name": "Webhooks", "description": "Operations for managing webhook URLs for SMS notifications" }, { "name": "Virtual Cards", "description": "Operations for creating and managing virtual credit cards. Cards are funded from your account balance and can be used for online purchases." } ], "servers": [ { "url": "https://api.quackr.io", "description": "quackr api server" } ] }