Phone Numbers

Provide phone number verification and temporary number rental services through the Ping API. Use these endpoints to list available services, create verification orders, rent temporary numbers, and manage ongoing rentals.

The phone number order model

The phone number order model represents a verification order or rental created through the platform. Verification orders provide a one-time code from a specific service, while rentals give access to a temporary phone number that receives all incoming SMS messages for a set duration.

Properties

Name
public_id
Type
string
Description
Unique identifier for the order or rental.
Name
service_id
Type
string
Description
The service this order is associated with (e.g., a specific platform or app).
Name
type
Type
string
Description
Order type: verification or rental.
Name
phone_number
Type
string
Description
The allocated phone number in E.164 format.
Name
capability
Type
string
Description
How the code or messages are received: sms or voice.
Name
status
Type
string
Description
Current status: pending, active, completed, cancelled, expired.
Name
code
Type
string
Description
The verification code received (verification orders only). Null until received.
Name
messages
Type
array
Description
Array of received SMS messages (rental orders only).
Name
cost
Type
number
Description
Cost of the order in USD.
Name
expires_at
Type
timestamp
Description
When the order or rental expires.
Name
created_at
Type
timestamp
Description
Timestamp of when the order was created.

GET/v1/nonvoip/services

List available services

Retrieve a list of available phone number services. Filter by service type, country, or search by name. Use this endpoint to show your users what services are available before they create an order.

Required headers

Name
X-Ping-Api-Key
Type
string
Description
Your API key with nonvoip permission.

Optional parameters

Name
service_type
Type
string
Description
Filter by type: verification or rental.
Name
country_code
Type
string
Description
Filter by country code (e.g., US, GB, ZA).
Name
search
Type
string
Description
Search services by name (e.g., WhatsApp, Telegram).
Name
skip
Type
integer
Description
Number of records to skip (default: 0).
Name
limit
Type
integer
Description
Maximum number of records to return (default: 50, max: 100).

Rate limit

60 requests per minute.

Request

GET

/v1/nonvoip/services

curl -G https://api.ping.co.zw/v1/nonvoip/services \
  -H "X-Ping-Api-Key: pk_live_your_api_key" \
  -d service_type=verification \
  -d country_code=US \
  -d limit=10

Response

{
  "result": "success",
  "services": [
    {
      "public_id": "svc_abc123def456",
      "name": "WhatsApp",
      "country_code": "US",
      "type": "verification",
      "capabilities": ["sms", "voice"],
      "cost": 0.50,
      "currency": "USD",
      "available": true
    },
    {
      "public_id": "svc_ghi789jkl012",
      "name": "Telegram",
      "country_code": "US",
      "type": "verification",
      "capabilities": ["sms"],
      "cost": 0.35,
      "currency": "USD",
      "available": true
    }
  ],
  "total": 2,
  "skip": 0,
  "limit": 10
}

GET/v1/nonvoip/services/:publicId

Get service details

Retrieve detailed information about a specific phone number service, including pricing, availability, and supported capabilities.

Required headers

Name
X-Ping-Api-Key
Type
string
Description
Your API key with nonvoip permission.

Path parameters

Name
publicId
Type
string
Description
The unique identifier of the service.

Rate limit

60 requests per minute.

Request

GET

/v1/nonvoip/services/svc_abc123def456

curl https://api.ping.co.zw/v1/nonvoip/services/svc_abc123def456 \
  -H "X-Ping-Api-Key: pk_live_your_api_key"

Response

{
  "result": "success",
  "service": {
    "public_id": "svc_abc123def456",
    "name": "WhatsApp",
    "country_code": "US",
    "type": "verification",
    "capabilities": ["sms", "voice"],
    "cost": 0.50,
    "currency": "USD",
    "available": true,
    "estimated_wait_seconds": 30,
    "success_rate": 0.95
  }
}

POST/v1/nonvoip/orders/create

Create a verification order

Create a new phone number verification order. This allocates a temporary phone number and begins waiting for the verification code from the target service. Poll the order status to retrieve the code once it arrives.

Required headers

Name
X-Ping-Api-Key
Type
string
Description
Your API key with nonvoip permission.
Name
Content-Type
Type
string
Description
Must be application/json.

Required attributes

Name
serviceId
Type
string
Description
The public ID of the service to verify against (from the services list).

Optional attributes

Name
capability
Type
string
Description
How to receive the code: sms (default) or voice.

Rate limit

30 requests per minute.

Request

POST

/v1/nonvoip/orders/create

curl -X POST https://api.ping.co.zw/v1/nonvoip/orders/create \
  -H "X-Ping-Api-Key: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "svc_abc123def456",
    "capability": "sms"
  }'

Response

{
  "result": "success",
  "message": "Verification order created",
  "verification": {
    "public_id": "ord_mno345pqr678",
    "service_id": "svc_abc123def456",
    "phone_number": "+12025551234",
    "capability": "sms",
    "status": "pending",
    "code": null,
    "cost": 0.50,
    "currency": "USD",
    "expires_at": "2026-04-04T12:30:00Z",
    "created_at": "2026-04-04T12:15:00Z"
  }
}

GET/v1/nonvoip/orders/:publicId/poll

Poll verification status

Poll an existing verification order to check if the code has been received. Continue polling at reasonable intervals (every 3-5 seconds) until the code arrives or the order expires.

Required headers

Name
X-Ping-Api-Key
Type
string
Description
Your API key with nonvoip permission.

Path parameters

Name
publicId
Type
string
Description
The unique identifier of the verification order.

Rate limit

120 requests per minute.

Request

GET

/v1/nonvoip/orders/ord_mno345pqr678/poll

curl https://api.ping.co.zw/v1/nonvoip/orders/ord_mno345pqr678/poll \
  -H "X-Ping-Api-Key: pk_live_your_api_key"

Response (pending)

{
  "result": "success",
  "verification": {
    "public_id": "ord_mno345pqr678",
    "phone_number": "+12025551234",
    "status": "pending",
    "code": null,
    "expires_at": "2026-04-04T12:30:00Z"
  }
}

Response (completed)

{
  "result": "success",
  "verification": {
    "public_id": "ord_mno345pqr678",
    "phone_number": "+12025551234",
    "status": "completed",
    "code": "482910",
    "received_at": "2026-04-04T12:16:23Z",
    "expires_at": "2026-04-04T12:30:00Z"
  }
}

POST/v1/nonvoip/orders/:publicId/cancel

Cancel a verification

Cancel a pending verification order. This stops waiting for the verification code and may issue a partial refund depending on the service and timing. Orders that have already received a code cannot be cancelled.

Required headers

Name
X-Ping-Api-Key
Type
string
Description
Your API key with nonvoip permission.

Path parameters

Name
publicId
Type
string
Description
The unique identifier of the verification order to cancel.

Rate limit

30 requests per minute.

Request

POST

/v1/nonvoip/orders/ord_mno345pqr678/cancel

curl -X POST https://api.ping.co.zw/v1/nonvoip/orders/ord_mno345pqr678/cancel \
  -H "X-Ping-Api-Key: pk_live_your_api_key"

Response

{
  "result": "success",
  "message": "Verification order cancelled",
  "verification": {
    "public_id": "ord_mno345pqr678",
    "status": "cancelled",
    "refund": {
      "amount": 0.50,
      "currency": "USD"
    }
  }
}

POST/v1/nonvoip/rentals/create

Create a number rental

Create a new phone number rental. This allocates a temporary phone number for the specified duration. All incoming SMS messages to this number will be collected and can be retrieved via the messages endpoint.

Required headers

Name
X-Ping-Api-Key
Type
string
Description
Your API key with nonvoip permission.
Name
Content-Type
Type
string
Description
Must be application/json.

Required attributes

Name
serviceId
Type
string
Description
The public ID of the service to rent a number for.
Name
days
Type
integer
Description
Number of days for the rental (minimum: 1, maximum: 30).

Rate limit

30 requests per minute.

Request

POST

/v1/nonvoip/rentals/create

curl -X POST https://api.ping.co.zw/v1/nonvoip/rentals/create \
  -H "X-Ping-Api-Key: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "svc_ghi789jkl012",
    "days": 7
  }'

Response

{
  "result": "success",
  "message": "Number rental created",
  "rental": {
    "public_id": "rnt_stu901vwx234",
    "service_id": "svc_ghi789jkl012",
    "phone_number": "+447911123456",
    "status": "active",
    "days": 7,
    "cost": 3.50,
    "currency": "USD",
    "messages_count": 0,
    "expires_at": "2026-04-11T12:15:00Z",
    "created_at": "2026-04-04T12:15:00Z"
  }
}

GET/v1/nonvoip/rentals/:publicId/messages

Get rental messages

Retrieve all SMS messages received by a rented phone number. Messages are returned in reverse chronological order (newest first). Poll this endpoint to check for new incoming messages.

Required headers

Name
X-Ping-Api-Key
Type
string
Description
Your API key with nonvoip permission.

Path parameters

Name
publicId
Type
string
Description
The unique identifier of the rental.

Rate limit

120 requests per minute.

Request

GET

/v1/nonvoip/rentals/rnt_stu901vwx234/messages

curl https://api.ping.co.zw/v1/nonvoip/rentals/rnt_stu901vwx234/messages \
  -H "X-Ping-Api-Key: pk_live_your_api_key"

Response

{
  "result": "success",
  "messages": [
    {
      "id": "msg_yza567bcd890",
      "from": "+15551234567",
      "text": "Your verification code is 839201",
      "received_at": "2026-04-04T14:22:10Z"
    },
    {
      "id": "msg_efg123hij456",
      "from": "+15559876543",
      "text": "Welcome to the service. Reply STOP to unsubscribe.",
      "received_at": "2026-04-04T13:10:45Z"
    }
  ],
  "total": 2
}

POST/v1/nonvoip/rentals/:publicId/extend

Extend a rental

Extend an active phone number rental by additional days. The extension is added to the current expiry date. The rental must still be active (not expired or cancelled) to be extended.

Required headers

Name
X-Ping-Api-Key
Type
string
Description
Your API key with nonvoip permission.
Name
Content-Type
Type
string
Description
Must be application/json.

Path parameters

Name
publicId
Type
string
Description
The unique identifier of the rental to extend.

Required attributes

Name
days
Type
integer
Description
Number of additional days to add to the rental (minimum: 1, maximum: 30).

Rate limit

30 requests per minute.

Request

POST

/v1/nonvoip/rentals/rnt_stu901vwx234/extend

curl -X POST https://api.ping.co.zw/v1/nonvoip/rentals/rnt_stu901vwx234/extend \
  -H "X-Ping-Api-Key: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "days": 3
  }'

Response

{
  "result": "success",
  "message": "Rental extended successfully",
  "rental": {
    "public_id": "rnt_stu901vwx234",
    "phone_number": "+447911123456",
    "status": "active",
    "days_added": 3,
    "total_days": 10,
    "extension_cost": 1.50,
    "currency": "USD",
    "expires_at": "2026-04-14T12:15:00Z"
  }
}

POST/v1/nonvoip/rentals/:publicId/cancel

Cancel a rental

Cancel an active phone number rental. The phone number is released immediately and no further messages will be received. A prorated refund may be issued for remaining unused days depending on the service terms.

Required headers

Name
X-Ping-Api-Key
Type
string
Description
Your API key with nonvoip permission.

Path parameters

Name
publicId
Type
string
Description
The unique identifier of the rental to cancel.

Rate limit

30 requests per minute.

Request

POST

/v1/nonvoip/rentals/rnt_stu901vwx234/cancel

curl -X POST https://api.ping.co.zw/v1/nonvoip/rentals/rnt_stu901vwx234/cancel \
  -H "X-Ping-Api-Key: pk_live_your_api_key"

Response

{
  "result": "success",
  "message": "Rental cancelled",
  "rental": {
    "public_id": "rnt_stu901vwx234",
    "status": "cancelled",
    "refund": {
      "amount": 2.00,
      "currency": "USD",
      "days_remaining": 4
    }
  }
}