Reserve a Number

Reserve a phone number before purchasing it. Reservations expire after a set period, so make sure to complete the purchase before the reservation expires.

Endpoint

POST https://api.p.2chat.io/open/numbers/reservations

Authentication

Include your API key in the X-User-API-Key header. Learn more about authentication.

Parameters

These parameters should be sent as JSON payload in the request body.

Field	Type	Required	Description
group_id	string	Yes	The group ID from the Search Number Groups endpoint
number	string	No	A specific number to reserve (from the Available Numbers endpoint)

tip

If you don't specify a number, a random available number from the group will be reserved for you.

Invocation

cURL

curl --location --request POST 'https://api.p.2chat.io/open/numbers/reservations' \
--header 'Content-Type: application/json' \
--header 'X-User-API-Key: your_api_key_here' \
--data '{
    "group_id": "abc-123",
    "number": "+12135551234"
}'

Python

import requests

url = "https://api.p.2chat.io/open/numbers/reservations"
headers = {
    "Content-Type": "application/json",
    "X-User-API-Key": "your_api_key_here"
}
payload = {
    "group_id": "abc-123",
    "number": "+12135551234"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

JavaScript

const axios = require('axios');

const response = await axios.post('https://api.p.2chat.io/open/numbers/reservations', {
    group_id: 'abc-123',
    number: '+12135551234'
}, {
    headers: {
        'Content-Type': 'application/json',
        'X-User-API-Key': 'your_api_key_here'
    }
});

console.log(response.data);

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.p.2chat.io/open/numbers/reservations',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode([
      'group_id' => 'abc-123',
      'number' => '+12135551234'
  ]),
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'X-User-API-Key: your_api_key_here'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response

Success (HTTP 201 Created)

{
    "success": true,
    "data": {
        "reservation_details": {
            "uuid": "reservation-uuid-here",
            "number": "+12135551234",
            "created_at": "2024-01-15T10:30:00Z",
            "expires_at": "2024-01-15T11:30:00Z"
        }
    }
}

Field	Description
reservation_details.uuid	Reservation UUID — use this to cancel the reservation if needed
reservation_details.number	The reserved phone number
reservation_details.created_at	When the reservation was created
reservation_details.expires_at	When the reservation will expire

caution

Reservations expire automatically. Make sure to purchase your reserved numbers before the expiration time.

Error

{
    "success": false,
    "error": true,
    "error_message": "Description of what went wrong"
}