{
  "openapi": "3.0.3",
  "info": {
    "title": "NonVoipUsNumber API",
    "version": "2026-06-06",
    "description": "API for account balance, product availability, number ordering, SMS retrieval, renewals, rejections, reuse, and callback delivery. All API endpoints accept JSON request bodies and form posts. External API clients authenticate by sending email and password in the request body.",
    "contact": {
      "name": "NonVoipUsNumber",
      "url": "https://nonvoipusnumber.com/manager/api-docs"
    }
  },
  "servers": [
    {
      "url": "https://nonvoipusnumber.com/manager",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Human-readable API documentation",
    "url": "https://nonvoipusnumber.com/manager/api-docs"
  },
  "tags": [
    {
      "name": "Account",
      "description": "Balance and account-level operations."
    },
    {
      "name": "Products",
      "description": "Product IDs, pricing, and stock."
    },
    {
      "name": "Orders",
      "description": "Create new number orders."
    },
    {
      "name": "Country Wise",
      "description": "Country-specific product and order endpoints."
    },
    {
      "name": "Order Actions",
      "description": "Reuse, activate, reject, renew, and read SMS for existing orders."
    },
    {
      "name": "Callbacks",
      "description": "Callback URL setup and webhook payload examples."
    }
  ],
  "components": {
    "schemas": {
      "AuthFields": {
        "type": "object",
        "required": [
          "email",
          "password"
        ],
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "description": "Account email address.",
            "example": "user@example.com"
          },
          "password": {
            "type": "string",
            "format": "password",
            "description": "Account password.",
            "example": "your_password"
          }
        }
      },
      "ApiError": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "error"
          },
          "message": {
            "type": "string",
            "example": "Wrong Auth"
          }
        }
      },
      "BalanceRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AuthFields"
          }
        ]
      },
      "BalanceResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "balance": {
            "type": "string",
            "description": "Account balance with two decimal places.",
            "example": "50.00"
          }
        }
      },
      "Product": {
        "type": "object",
        "properties": {
          "product_id": {
            "type": "integer",
            "description": "Public product ID to use for ordering.",
            "example": 10000086
          },
          "name": {
            "type": "string",
            "example": "Instagram"
          },
          "price": {
            "type": "string",
            "description": "For 10-minute products, this is the current expected route price.",
            "example": "0.36"
          },
          "available": {
            "type": "integer",
            "example": 6841
          },
          "category": {
            "type": "string",
            "example": "10-minutes"
          }
        }
      },
      "ProductsRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AuthFields"
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "description": "Alias for product_id.",
                "example": 10000086
              },
              "product_id": {
                "type": "integer",
                "example": 10000086
              },
              "type": {
                "type": "string",
                "enum": [
                  "short_term",
                  "long_term",
                  "one_day",
                  "3days"
                ],
                "example": "short_term"
              },
              "grouped": {
                "type": "boolean",
                "description": "Return products grouped as 10-minutes, 30-days, 1-day, and legacy categories.",
                "example": true
              }
            }
          }
        ]
      },
      "ProductsResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "message": {
            "oneOf": [
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Product"
                }
              },
              {
                "type": "object",
                "additionalProperties": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Product"
                  }
                }
              }
            ]
          }
        }
      },
      "OrderRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AuthFields"
          },
          {
            "type": "object",
            "properties": {
              "product_id": {
                "type": "integer",
                "description": "Product ID returned by /api/products.",
                "example": 10000086
              },
              "product_ids": {
                "type": "array",
                "description": "30-days only. Order multiple services at once on the same number. Maximum 5 services.",
                "items": {
                  "type": "integer"
                },
                "example": [
                  9044,
                  8555
                ]
              },
              "auction": {
                "type": "integer",
                "minimum": 10,
                "maximum": 2000,
                "description": "Short-term premium bid percentage. Use this after receiving Premium_Available, or when intentionally bidding.",
                "example": 20
              },
              "accepted_max_price": {
                "type": "number",
                "format": "float",
                "description": "10-minute confirmation cap. Use after Price_Change_Required, or send proactively if a higher route price is acceptable. Actual debit equals the route price used, not necessarily this cap.",
                "example": 1.7
              }
            }
          }
        ]
      },
      "ShortOrder": {
        "type": "object",
        "properties": {
          "order_id": {
            "type": "integer",
            "example": 146185
          },
          "status": {
            "type": "string",
            "example": "Reserved"
          },
          "number": {
            "type": "string",
            "example": "16095550123"
          },
          "service": {
            "type": "string",
            "example": "Instagram"
          },
          "expiration": {
            "type": "integer",
            "description": "Seconds until expiration.",
            "example": 900
          },
          "type": {
            "type": "string",
            "example": "short_term"
          }
        }
      },
      "OrderSuccessResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "message": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ShortOrder"
            }
          }
        }
      },
      "PremiumAvailableResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "info"
          },
          "message": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "info": {
                  "type": "string",
                  "example": "Premium_Available"
                },
                "recommended_bid": {
                  "type": "integer",
                  "example": 20
                }
              }
            }
          }
        }
      },
      "PriceChangeRequiredResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "info"
          },
          "message": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "info": {
                  "type": "string",
                  "example": "Price_Change_Required"
                },
                "quoted_price": {
                  "type": "number",
                  "format": "float",
                  "example": 0.3
                },
                "allowed_price": {
                  "type": "number",
                  "format": "float",
                  "example": 0.39
                },
                "available_price": {
                  "type": "number",
                  "format": "float",
                  "example": 1.7
                }
              }
            }
          }
        }
      },
      "CountryProduct": {
        "type": "object",
        "properties": {
          "product_id": {
            "type": "integer",
            "example": 501
          },
          "name": {
            "type": "string",
            "example": "Telegram"
          },
          "country": {
            "type": "string",
            "example": "United States"
          },
          "price": {
            "type": "string",
            "example": "0.45"
          },
          "available": {
            "type": "integer",
            "example": 120
          }
        }
      },
      "CountryOrderRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AuthFields"
          },
          {
            "type": "object",
            "required": [
              "product_id"
            ],
            "properties": {
              "product_id": {
                "type": "integer",
                "description": "Country-wise product ID returned by /api/country/products.",
                "example": 501
              }
            }
          }
        ]
      },
      "OrderLookupRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AuthFields"
          },
          {
            "type": "object",
            "properties": {
              "order_id": {
                "type": "string",
                "description": "Preferred identifier for order actions.",
                "example": "146185"
              },
              "service": {
                "type": "string",
                "description": "Service name from the original API response. Use with number when order_id is not available.",
                "example": "Instagram"
              },
              "number": {
                "type": "string",
                "description": "Phone number from the original API response. Use with service when order_id is not available.",
                "example": "16095170503"
              }
            }
          }
        ]
      },
      "RenewRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/OrderLookupRequest"
          },
          {
            "type": "object",
            "properties": {
              "duration": {
                "type": "string",
                "description": "Optional renewal duration.",
                "example": "30d"
              }
            }
          }
        ]
      },
      "SaveCallbackUrlRequest": {
        "type": "object",
        "required": [
          "url",
          "userId"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "HTTPS endpoint that will receive callback payloads.",
            "example": "https://example.com/callback"
          },
          "userId": {
            "type": "integer",
            "description": "User ID for the account whose callback URL should be updated.",
            "example": 1234
          }
        }
      },
      "SmsResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "number": {
            "type": "string",
            "example": "16095170503"
          },
          "service": {
            "type": "string",
            "example": "Instagram"
          },
          "sms": {
            "type": "string",
            "example": "Your Instagram OTP is 545"
          },
          "pin": {
            "type": "string",
            "example": "545"
          },
          "type": {
            "type": "string",
            "example": "short_term"
          }
        }
      },
      "IncomingMessageWebhook": {
        "type": "object",
        "properties": {
          "event": {
            "type": "string",
            "example": "incoming_message"
          },
          "message": {
            "type": "object",
            "properties": {
              "order_id": {
                "type": "integer",
                "example": 454303
              },
              "number": {
                "type": "string",
                "example": "16095170503"
              },
              "service": {
                "type": "string",
                "example": "Instagram"
              },
              "sender": {
                "type": "string",
                "example": "8843"
              },
              "sms": {
                "type": "string",
                "example": "Your Instagram OTP is 545"
              },
              "code": {
                "type": "string",
                "example": "545"
              },
              "type": {
                "type": "string",
                "example": "str"
              }
            }
          }
        }
      }
    },
    "requestBodies": {
      "AuthOnly": {
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/AuthFields"
            },
            "example": {
              "email": "user@example.com",
              "password": "your_password"
            }
          },
          "application/x-www-form-urlencoded": {
            "schema": {
              "$ref": "#/components/schemas/AuthFields"
            }
          },
          "multipart/form-data": {
            "schema": {
              "$ref": "#/components/schemas/AuthFields"
            }
          }
        }
      }
    },
    "responses": {
      "Error": {
        "description": "Error response",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            },
            "examples": {
              "wrongAuth": {
                "value": {
                  "status": "error",
                  "message": "Wrong Auth"
                }
              },
              "insufficientBalance": {
                "value": {
                  "status": "error",
                  "message": "Insufficient balance."
                }
              }
            }
          }
        }
      },
      "RateLimit": {
        "description": "Rate limit exceeded",
        "headers": {
          "X-RateLimit-Limit": {
            "schema": {
              "type": "integer"
            },
            "description": "Per-minute request limit."
          },
          "X-RateLimit-Remaining": {
            "schema": {
              "type": "integer"
            },
            "description": "Requests left in the current minute."
          },
          "X-RateLimit-Reset": {
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "UTC timestamp when the current window resets."
          }
        },
        "content": {
          "application/json": {
            "example": {
              "status": "error",
              "message": "Rate limit exceeded. Please try again later.",
              "limit": 500,
              "retryAfter": 45
            }
          }
        }
      }
    }
  },
  "paths": {
    "/api/balance": {
      "post": {
        "tags": [
          "Account"
        ],
        "summary": "Get account balance",
        "description": "Returns the current account balance. Balance is returned as a string with two decimal places.",
        "requestBody": {
          "$ref": "#/components/requestBodies/AuthOnly"
        },
        "responses": {
          "200": {
            "description": "Balance returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BalanceResponse"
                },
                "example": {
                  "status": "success",
                  "balance": "50.00"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimit"
          }
        }
      }
    },
    "/api/products": {
      "post": {
        "tags": [
          "Products"
        ],
        "summary": "List products, pricing, and stock",
        "description": "Use returned product_id values for ordering. 10-minute product IDs are stable public IDs. The listed 10-minute price is the current expected route price. If a higher-priced route is needed, /api/order may return Price_Change_Required.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProductsRequest"
              },
              "examples": {
                "grouped": {
                  "summary": "Grouped products",
                  "value": {
                    "email": "user@example.com",
                    "password": "your_password",
                    "grouped": true
                  }
                },
                "shortTerm": {
                  "summary": "Short-term products only",
                  "value": {
                    "email": "user@example.com",
                    "password": "your_password",
                    "type": "short_term"
                  }
                }
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/ProductsRequest"
              }
            },
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/ProductsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Products returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductsResponse"
                },
                "examples": {
                  "grouped": {
                    "value": {
                      "status": "success",
                      "message": {
                        "10-minutes": [
                          {
                            "product_id": 10000086,
                            "name": "Instagram",
                            "price": "0.36",
                            "available": 6841
                          }
                        ],
                        "30-days": [
                          {
                            "product_id": 9044,
                            "name": "WhatsApp",
                            "price": "2.00",
                            "available": 100
                          }
                        ],
                        "1-day": [
                          {
                            "product_id": 9441,
                            "name": "Telegram",
                            "price": "1.25",
                            "available": 100
                          }
                        ]
                      }
                    }
                  },
                  "list": {
                    "value": {
                      "status": "success",
                      "message": [
                        {
                          "product_id": 10000086,
                          "name": "Instagram",
                          "price": "0.36",
                          "available": 6841,
                          "category": "10-minutes"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimit"
          }
        }
      }
    },
    "/api/order": {
      "post": {
        "tags": [
          "Orders"
        ],
        "summary": "Place a USA order",
        "description": "Create a 10-minute, 30-days, 1-day, or legacy 3-days order using product_id from /api/products. For 10-minute products, the actual debit is the price of the route that supplies the number. If the available route is more than 30% above the shown product price, the API returns Price_Change_Required; retry with accepted_max_price to confirm your maximum accepted price.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrderRequest"
              },
              "examples": {
                "shortTerm": {
                  "summary": "Short-term order",
                  "value": {
                    "email": "user@example.com",
                    "password": "your_password",
                    "product_id": 10000086
                  }
                },
                "premiumRetry": {
                  "summary": "Retry with recommended premium bid",
                  "value": {
                    "email": "user@example.com",
                    "password": "your_password",
                    "product_id": 10000086,
                    "auction": 20
                  }
                },
                "priceAcceptedRetry": {
                  "summary": "Retry after Price_Change_Required",
                  "value": {
                    "email": "user@example.com",
                    "password": "your_password",
                    "product_id": 10000086,
                    "accepted_max_price": 1.7
                  }
                },
                "multi30Days": {
                  "summary": "30-days multi-service order",
                  "value": {
                    "email": "user@example.com",
                    "password": "your_password",
                    "product_ids": [
                      9044,
                      8555
                    ]
                  }
                }
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/OrderRequest"
              }
            },
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/OrderRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Order result",
            "content": {
              "application/json": {
                "examples": {
                  "shortTermSuccess": {
                    "value": {
                      "status": "success",
                      "message": [
                        {
                          "order_id": 146185,
                          "status": "Reserved",
                          "number": "16095550123",
                          "service": "Instagram",
                          "expiration": 900,
                          "type": "short_term"
                        }
                      ]
                    }
                  },
                  "premiumAvailable": {
                    "value": {
                      "status": "info",
                      "message": [
                        {
                          "info": "Premium_Available",
                          "recommended_bid": 20
                        }
                      ]
                    }
                  },
                  "priceChangeRequired": {
                    "value": {
                      "status": "info",
                      "message": [
                        {
                          "info": "Price_Change_Required",
                          "quoted_price": 0.3,
                          "allowed_price": 0.39,
                          "available_price": 1.7
                        }
                      ]
                    }
                  },
                  "longTermOrOneDay": {
                    "value": {
                      "status": "success",
                      "message": [
                        {
                          "order_id": 146187,
                          "status": "Active",
                          "number": "16095550123",
                          "service": "PayPal",
                          "type": "long_term",
                          "expires": "2100-12-31 23:59:59"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimit"
          }
        }
      }
    },
    "/api/country/products": {
      "post": {
        "tags": [
          "Country Wise"
        ],
        "summary": "List country-wise products",
        "description": "Returns products available through the country-wise inventory.",
        "requestBody": {
          "$ref": "#/components/requestBodies/AuthOnly"
        },
        "responses": {
          "200": {
            "description": "Country products returned",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "message": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CountryProduct"
                      }
                    }
                  }
                },
                "example": {
                  "status": "success",
                  "message": [
                    {
                      "product_id": 501,
                      "name": "Telegram",
                      "country": "United States",
                      "price": "0.45",
                      "available": 120
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimit"
          }
        }
      }
    },
    "/api/country/order": {
      "post": {
        "tags": [
          "Country Wise"
        ],
        "summary": "Place a country-wise order",
        "description": "Create an order using a country-wise product_id from /api/country/products.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CountryOrderRequest"
              },
              "example": {
                "email": "user@example.com",
                "password": "your_password",
                "product_id": 501
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/CountryOrderRequest"
              }
            },
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/CountryOrderRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Country order result",
            "content": {
              "application/json": {
                "example": {
                  "status": "success",
                  "message": {
                    "order_id": "sb_102030",
                    "status": "Reserved",
                    "number": "16095550123",
                    "service": "tg",
                    "country": "US",
                    "expiration": 300,
                    "expires_at": "2026-05-17 00:00:00",
                    "cost": "0.45"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimit"
          }
        }
      }
    },
    "/api/reuse": {
      "post": {
        "tags": [
          "Order Actions"
        ],
        "summary": "Reuse a short-term number",
        "description": "Reuse an existing short-term number. order_id is the safest identifier. If order_id is not available, send service and number from the original API response.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrderLookupRequest"
              },
              "example": {
                "email": "user@example.com",
                "password": "your_password",
                "order_id": "35749684"
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/OrderLookupRequest"
              }
            },
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/OrderLookupRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reuse result",
            "content": {
              "application/json": {
                "example": {
                  "status": "success",
                  "message": [
                    {
                      "order_id": 35749684,
                      "status": "Reserved",
                      "number": "16095170503",
                      "service": "Instagram",
                      "till_expiration": 900,
                      "type": "short_term"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimit"
          }
        }
      }
    },
    "/api/activate": {
      "post": {
        "tags": [
          "Order Actions"
        ],
        "summary": "Activate a long-term or 3-days number",
        "description": "Activate an eligible long-term, 1-day, or 3-days number. Use order_id when available.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrderLookupRequest"
              },
              "example": {
                "email": "user@example.com",
                "password": "your_password",
                "order_id": "146187"
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/OrderLookupRequest"
              }
            },
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/OrderLookupRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Activation result",
            "content": {
              "application/json": {
                "example": {
                  "status": "success",
                  "message": [
                    {
                      "online_status": "online",
                      "end_on": "2026-05-17 07:35:46",
                      "timezone": "UTC"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimit"
          }
        }
      }
    },
    "/api/reject": {
      "post": {
        "tags": [
          "Order Actions"
        ],
        "summary": "Reject a number before receiving SMS",
        "description": "Reject a reserved number before receiving SMS. Use order_id when available.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrderLookupRequest"
              },
              "example": {
                "email": "user@example.com",
                "password": "your_password",
                "order_id": "146185"
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/OrderLookupRequest"
              }
            },
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/OrderLookupRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reject result",
            "content": {
              "application/json": {
                "example": {
                  "status": "success",
                  "message": "The rental for Instagram 16095170503 has been stopped and refunded."
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimit"
          }
        }
      }
    },
    "/api/renew": {
      "post": {
        "tags": [
          "Order Actions"
        ],
        "summary": "Renew a rented number",
        "description": "Renew a rented number. Use order_id when available.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RenewRequest"
              },
              "example": {
                "email": "user@example.com",
                "password": "your_password",
                "order_id": "146187",
                "duration": "30d"
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/RenewRequest"
              }
            },
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/RenewRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Renewal result",
            "content": {
              "application/json": {
                "example": {
                  "status": "success",
                  "expiration": "2100-12-31 23:59:59"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimit"
          }
        }
      }
    },
    "/api/getsms": {
      "post": {
        "tags": [
          "Order Actions"
        ],
        "summary": "Get latest SMS",
        "description": "Fetch the latest SMS for an order. Use order_id when available.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrderLookupRequest"
              },
              "example": {
                "email": "user@example.com",
                "password": "your_password",
                "order_id": "146185"
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/OrderLookupRequest"
              }
            },
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/OrderLookupRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SMS result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SmsResponse"
                },
                "example": {
                  "status": "success",
                  "number": "16095170503",
                  "service": "Instagram",
                  "sms": "Your Instagram OTP is 545",
                  "pin": "545",
                  "type": "short_term"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimit"
          }
        }
      }
    },
    "/api/saveurl": {
      "post": {
        "tags": [
          "Callbacks"
        ],
        "summary": "Save callback URL",
        "description": "Save the callback URL for a user account. The callback URL receives incoming SMS and premium bid event payloads.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SaveCallbackUrlRequest"
              },
              "example": {
                "url": "https://example.com/callback",
                "userId": 1234
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/SaveCallbackUrlRequest"
              }
            },
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/SaveCallbackUrlRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Callback URL saved",
            "content": {
              "application/json": {
                "example": {
                  "status": "success",
                  "message": "Callback URL saved successfully"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/RateLimit"
          }
        }
      }
    }
  },
  "x-webhooks": {
    "incoming_message": {
      "post": {
        "summary": "Incoming SMS callback",
        "description": "Payload sent to the saved callback URL when an SMS arrives.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IncomingMessageWebhook"
              },
              "example": {
                "event": "incoming_message",
                "message": {
                  "order_id": 454303,
                  "number": "16095170503",
                  "service": "Instagram",
                  "sender": "8843",
                  "sms": "Your Instagram OTP is 545",
                  "code": "545",
                  "type": "str"
                }
              }
            }
          }
        }
      }
    },
    "auction_wining": {
      "post": {
        "summary": "Premium bid winning callback",
        "description": "Payload sent to the saved callback URL when a premium bid wins and a number is assigned.",
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "event": "auction_wining",
                "message": [
                  {
                    "order_id": 4545,
                    "number": "16095170503",
                    "service": "GMail",
                    "expiration": 900
                  }
                ]
              }
            }
          }
        }
      }
    }
  },
  "x-ai-instructions": {
    "preferred_docs": "Read this OpenAPI document first, then use https://nonvoipusnumber.com/manager/api-docs for human examples.",
    "authentication": "Send email and password in every API request body unless using the logged-in Swagger UI.",
    "request_formats": [
      "application/json",
      "application/x-www-form-urlencoded",
      "multipart/form-data"
    ],
    "ordering_notes": [
      "Always call /api/products first and order using returned product_id values.",
      "For 10-minute products, if /api/order returns Price_Change_Required, show the user the available_price and retry with accepted_max_price only after the user accepts.",
      "For Premium_Available, retry the same product_id with auction set to the recommended_bid if the user accepts premium bidding.",
      "For order actions, prefer order_id over service plus number."
    ]
  }
}