PVADeals API

Build powerful SMS verification solutions with our non-VoIP phone number API. Get access to real carrier phone numbers for account verification across hundreds of services.

Base URL https://prod-v3.pvadeals.com

Introduction

The PVADeals API provides programmatic access to our SMS verification service. Use it to purchase phone numbers, receive SMS codes, and manage your verification workflow.

📱

Non-VoIP Numbers

Real carrier phone numbers that work with services that block VoIP.

⚡

Instant Delivery

SMS codes typically arrive within seconds of being sent.

📥

Postman Collection

Download our ready-to-use API collection to get started quickly.

Download JSON

Authentication

All API requests require authentication using your API key. Include it in the Authorization header with the Bearer prefix.

Request Header

Authorization: Bearer API-xxxxx...

🔑

Getting Your API Key

Sign up at https://app.pvadeals.com/ to get your API key. Once registered, navigate to Settings → API Keys to generate or view your API key.

Example Request with Authentication

cURL

curl -X GET "https://prod-v3.pvadeals.com/v3/api/balance" \
  -H "Authorization: Bearer API-xxxxx..."

Quick Start

Follow this typical integration flow to purchase a number and receive an SMS verification code.

Get Services

→

Purchase Number

→

Use Number

→

Receive Webhook

→

Complete

Step 1: Get Available Services

cURL

curl -X GET "https://prod-v3.pvadeals.com/v3/api/services/all" \
  -H "Authorization: Bearer API-xxxxx..."

Step 2: Purchase a Number

cURL

curl -X POST "https://prod-v3.pvadeals.com/v3/api/purchase" \
  -H "Authorization: Bearer API-xxxxx..." \
  -H "Content-Type: application/json" \
  -d '{"services": [{"serviceId": "697139f7fe5460ddc2f27214"}]}'

Step 3: Receive SMS via Webhook

Configure your webhook URL in the dashboard. When an SMS arrives, you'll receive a POST request with the verification code.

Rate Limits

To ensure fair usage and system stability, the API enforces the following rate limits:

Limit Type	Limit	Window	Notes
API Requests	100 requests	60 seconds (rolling)	Per API key

Rate Limit Response

429 Response

{"message": "API Rate limit exceeded. Maximum 100 requests per minute.", "status": 429, "retryAfter": 60}

Error Handling

The API uses standard HTTP status codes to indicate success or failure of requests.

Status Code	Meaning	Common Causes
200 OK	Success	Request completed successfully
400 Bad Request	Invalid Request	Missing required fields, invalid JSON
401 Unauthorized	Authentication Failed	Missing or invalid API key
404 Not Found	Resource Not Found	Request ID or Service ID doesn't exist
422 Unprocessable	Business Rule Violation	Flag/Reuse not allowed for this request
429 Too Many Requests	Rate Limit Exceeded	Too many requests, wait and retry

Error Response Format

Error Response

{"success": false, "message": "Unauthorized Access! Invalid API key", "status": 401}

Get Balance

Retrieve your current account balance and credit information.

GET/v3/api/balance

Example Request

cURL

curl -X GET "https://prod-v3.pvadeals.com/v3/api/balance" \
  -H "Authorization: Bearer API-xxxxx..."

Response

200 OK

{"success": true, "data": {"credits": 100.00}, "message": "Balance retrieved successfully"}

Get All Services

Retrieve a list of all available services for SMS verification.

GET/v3/api/services/all

Example Request

cURL

curl -X GET "https://prod-v3.pvadeals.com/v3/api/services/all" \
  -H "Authorization: Bearer API-xxxxx..."

Response

200 OK

{"success": true, "data": {"services": [{"_id": "697139f4fe5460ddc2f271e9", "name": "3Fun", "country": "USA", "price": 0.1}, {"_id": "697139f7fe5460ddc2f27214", "name": "Airbnb", "country": "USA", "price": 0.2}]}}

Response Fields

_idstringService ID (use this for purchase)

namestringService/website name

countrystringCountry (USA)

pricenumberPrice per number in USD

STR - Purchase Number

Purchase one or more phone numbers for SMS verification. Numbers are available for 20 minutes.

POST/v3/api/purchase

Request Body

📦 Request Body

services*arrayArray of service objects to purchase

└ serviceId*stringService ID from /services/all endpoint

Example Request

cURL

curl -X POST "https://prod-v3.pvadeals.com/v3/api/purchase" \
  -H "Authorization: Bearer API-xxxxx..." \
  -H "Content-Type: application/json" \
  -d '{"services": [{"serviceId": "697139f7fe5460ddc2f27214"}]}'

Response

200 OK

{
  "success": true,
  "data": {
    "requests": [{
      "_id": "697a90d25ef1873ef44f48bc",
      "serviceName": "Airbnb",
      "serviceId": "697139f7fe5460ddc2f27214",
      "number": "+13130001234",
      "status": "RESERVED",
      "country": "US",
      "amount": 0.2,
      "numberType": "STR",
      "allowFlag": true,
      "allowReuse": false,
      "reuseCounter": 0,
      "endTime": "2026-01-28T23:02:26.292Z",
      "createdAt": "2026-01-28T22:42:26.452Z"
    }]
  },
  "message": "Numbers purchased successfully"
}

📨

Webhook Notification

A number_purchased webhook event will be sent to your configured webhook URL after a successful purchase.

STR - Flag Number

Flag a number to cancel it and receive a refund (if eligible). Only available when allowFlag: true.

POST/v3/api/flag/{id}

Path Parameters

Parameter	Type	Description
id*	string	The service request ID to flag

Example Request

cURL

curl -X POST "https://prod-v3.pvadeals.com/v3/api/flag/697a90d25ef1873ef44f48bc" \
  -H "Authorization: Bearer API-xxxxx..."

Response

200 OK

{"success": true, "data": true, "message": "Number flagged successfully"}

⚠️

Flag Availability

Check the allowFlag field before attempting to flag. If allowFlag: false, the request will return a 422 error.

STR - Reuse Number

Reuse a previously purchased number to receive additional SMS codes. Only available when allowReuse: true.

POST/v3/api/reuse/{id}

Path Parameters

Parameter	Type	Description
id*	string	The service request ID to reuse

Example Request

cURL

curl -X POST "https://prod-v3.pvadeals.com/v3/api/reuse/697a90d25ef1873ef44f48bc" \
  -H "Authorization: Bearer API-xxxxx..."

Response

200 OK

{
  "success": true,
  "data": {
    "_id": "697a90d25ef1873ef44f48bc",
    "serviceName": "Airbnb",
    "serviceId": "697139f7fe5460ddc2f27214",
    "number": "+13130001234",
    "status": "RESERVED",
    "country": "US",
    "amount": 0,
    "numberType": "STR",
    "allowFlag": false,
    "allowReuse": true,
    "reuseCounter": 2,
    "endTime": "2026-01-28T23:07:17.000Z"
  },
  "message": "Number reused successfully"
}

⚠️

Reuse

Reuse is time-limited and not guaranteed for all numbers. In some cases, additional charges may apply.

LTR - Purchase Number

Purchase a long-term rental phone number for extended verification needs.

POST/v3/api/purchase-ltr

Request Body

📦 Request Body

duration*numberRental duration in days (3 or 30)

serviceId*stringService ID from /services/all endpoint

Example Request

cURL

curl -X POST "https://prod-v3.pvadeals.com/v3/api/purchase-ltr" \
  -H "Authorization: Bearer API-xxxxx..." \
  -H "Content-Type: application/json" \
  -d '{"duration": 3, "serviceId": "697139f4fe5460ddc2f271db"}'

Response

200 OK

{
  "success": true,
  "data": {
    "_id": "6985cc7b9ecd8f1260b47a39",
    "serviceName": "2RedBeans",
    "serviceId": "697139f4fe5460ddc2f271db",
    "number": "+13130001234",
    "status": "RESERVED",
    "country": "US",
    "amount": 0.7,
    "endTime": "2026-02-09T11:11:55.324Z",
    "allowFlag": true,
    "autoRenewEnable": false,
    "numberType": "LTR",
    "createdAt": "2026-02-06T11:11:55.354Z",
    "updatedAt": "2026-02-06T11:11:55.384Z"
  },
  "message": "LTR number purchased successfully"
}

Duration Options

Duration	Price	Description
3	$0.70	3-day rental
30	$2.25	30-day rental

LTR - Flag Number

Flag a LTR number to cancel it and receive a refund (if eligible). Only available when allowFlag: true.

POST/v3/api/flag/{id}

Path Parameters

Parameter	Type	Description
id*	string	The LTR request ID to flag

Example Request

cURL

curl -X POST "https://prod-v3.pvadeals.com/v3/api/flag/6985cc7b9ecd8f1260b47a39" \
  -H "Authorization: Bearer API-xxxxx..."

Response

200 OK

{"success": true, "data": true, "message": "Number flagged successfully"}

⚠️

Flag Availability

Check the allowFlag field before attempting to flag. If allowFlag: false, the request will return a 422 error.

LTR - Renew Number

Toggle auto-renew for a LTR number. The same endpoint enables or disables auto-renewal.

POST/v3/api/renew-ltr/{id}

Path Parameters

Parameter	Type	Description
id*	string	The LTR request ID to toggle auto-renew

Example Request

cURL

curl -X POST "https://prod-v3.pvadeals.com/v3/api/renew-ltr/6985ce2e9ecd8f1260b47a7e" \
  -H "Authorization: Bearer API-xxxxx..."

Response

200 OK

{
  "success": true,
  "data": {
    "_id": "6985ce2e9ecd8f1260b47a7e",
    "serviceName": "2RedBeans",
    "serviceId": "697139f4fe5460ddc2f271db",
    "number": "+13130001234",
    "status": "RESERVED",
    "country": "US",
    "amount": 0.7,
    "endTime": "2026-02-09T11:19:10.769Z",
    "allowFlag": true,
    "autoRenewEnable": true,
    "numberType": "LTR",
    "createdAt": "2026-02-06T11:19:10.795Z",
    "updatedAt": "2026-02-06T11:19:16.699Z"
  },
  "message": "Auto-renew enabled successfully"
}

🔄

Auto-Renew Toggle

Call this endpoint again to disable auto-renew. Response message will change to "Auto-renew disabled successfully".

LTR - Purchase All Service Number

Purchase a 28-day LTR number that can receive SMS from any service - not restricted to a single website.

POST/v3/api/purchase-ltr

Request Body

📦 Request Body

duration*number28 (fixed for all service)

serviceId*stringALL_SERVICES

Example Request

cURL

curl -X POST "https://prod-v3.pvadeals.com/v3/api/purchase-ltr" \
  -H "Authorization: Bearer API-xxxxx..." \
  -H "Content-Type: application/json" \
  -d '{"duration": 28, "serviceId": "ALL_SERVICES"}'

Response

200 OK

{
  "success": true,
  "data": {
    "_id": "6985d496e49f9312f4cc934e",
    "serviceName": "ALL_SERVICES",
    "serviceId": "ALL_SERVICES",
    "number": "+13130001234",
    "status": "RESERVED",
    "country": "US",
    "amount": 15.99,
    "endTime": "2026-03-06T11:11:55.324Z",
    "allowFlag": false,
    "autoRenewEnable": false,
    "numberType": "LTR",
    "createdAt": "2026-02-06T11:11:55.354Z",
    "updatedAt": "2026-02-06T11:11:55.384Z"
  },
  "message": "LTR number purchased successfully"
}

List Service Requests

Get a paginated list of your service requests (purchased numbers) using cursor-based pagination. Returns both STR and LTR requests.

GET/v3/api/requests

Query Parameters

Parameter	Type	Default	Description
first	number	20	Number of items to fetch
after	string	-	Cursor for forward pagination
before	string	-	Cursor for backward pagination
orderField	string	_id	Field to sort by
orderBy	string	desc	Sort order: asc or desc

Example Request

cURL

curl -X GET "https://prod-v3.pvadeals.com/v3/api/requests?first=20&orderBy=desc" \
  -H "Authorization: Bearer API-xxxxx..."

Response

200 OK

{
  "success": true,
  "data": {
    "data": {
      "edges": [{
        "cursor": "Njk3YTkwZDI1ZWYxODczZWY0NGY0OGJj",
        "node": {
          "_id": "697a90d25ef1873ef44f48bc",
          "serviceName": "Airbnb",
          "serviceId": "697139f7fe5460ddc2f27214",
          "number": "+13130001234",
          "status": "COMPLETED",
          "country": "US",
          "amount": 0.2,
          "numberType": "STR",
          "allowFlag": false,
          "allowReuse": true,
          "reuseCounter": 0,
          "endTime": "2026-01-28T23:02:26.292Z",
          "createdAt": "2026-01-28T22:42:26.452Z"
        }
      }]
    }
  }
}

Get Service Request

Get detailed information about a specific service request by its ID. Works for both STR and LTR requests.

GET/v3/api/request/{id}

Path Parameters

Parameter	Type	Description
id*	string	The service request ID

Example Request

cURL

curl -X GET "https://prod-v3.pvadeals.com/v3/api/request/697a90d25ef1873ef44f48bc" \
  -H "Authorization: Bearer API-xxxxx..."

Response

200 OK

{
  "success": true,
  "data": {
    "_id": "697a90d25ef1873ef44f48bc",
    "serviceName": "Airbnb",
    "serviceId": "697139f7fe5460ddc2f27214",
    "number": "+13130001234",
    "status": "COMPLETED",
    "country": "US",
    "amount": 0.2,
    "numberType": "STR",
    "allowFlag": false,
    "allowReuse": true,
    "reuseCounter": 0,
    "messageCounter": 15,
    "endTime": "2026-01-28T23:02:26.292Z",
    "createdAt": "2026-01-28T22:42:26.452Z",
    "updatedAt": "2026-01-28T22:57:35.016Z"
  },
  "message": "Service request retrieved successfully"
}

Status Values

Status	Description
RESERVED	Number purchased, waiting for SMS
COMPLETED	SMS received successfully
FLAGGED	Number was flagged/cancelled
TIMEOUT	Number expired without receiving SMS

Webhooks

Configure a webhook URL in your dashboard to receive real-time notifications about events.

🔄

Webhook Retry Policy

Webhooks are retried up to 5 times with a 5-second delay between each attempt if delivery fails.

sms_received

Triggered when an SMS is received on a purchased number.

Webhook Payload

{"event": "sms_received", "timestamp": "2026-01-28T22:57:35.001Z", "requestId": "697a90d25ef1873ef44f48bc", "serviceId": "697139f7fe5460ddc2f27214", "number": "+13130001234", "message": "Your Airbnb verification code is 2200."}

number_purchased

Triggered when a number is successfully purchased.

Webhook Payload

{"event": "number_purchased", "timestamp": "2026-01-28T22:42:26.452Z", "requestId": "697a90d25ef1873ef44f48bc", "serviceId": "697139f7fe5460ddc2f27214", "number": "+13130001234", "message": ""}

number_flagged

Triggered when a number is flagged/cancelled.

Webhook Payload

{"event": "number_flagged", "timestamp": "2026-01-28T22:42:25.673Z", "requestId": "697a8d4f8130528198e0c0eb", "serviceId": "697a8d4f8130528198e0c0f4", "number": "+13130001234", "message": ""}

number_reused

Triggered when a number is reused.

Webhook Payload

{"event": "number_reused", "timestamp": "2026-01-28T21:50:36.765Z", "requestId": "697a82bf27787d2db20a29a0", "serviceId": "697a82c127787d2db20a29a6", "number": "+13130001234", "message": ""}

Webhook Payload Fields

eventstringEvent type (sms_received, number_purchased, etc.)

timestampstringISO 8601 timestamp of the event

requestIdstringOrdered number's request ID

serviceIdstringWebsite name's service ID

numberstringThe phone number

messagestringSMS content (only for sms_received)