Skip to main content

Reserve a Number

Agent Skill

Automate this endpoint with an AI agent using the 2chat-numbers skill:

npx skills add 2ChatCo/agent-skills -s 2chat-numbers

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.

API costโ€‹

1API credit

Each call to this endpoint deducts 1 API credit from your plan's API credit pool.

Parametersโ€‹

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

FieldTypeRequiredDescription
group_idstringYesThe group ID from the Search Number Groups endpoint
numberstringNoA 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 --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"
}'

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"
}
}
}
FieldDescription
reservation_details.uuidReservation UUID โ€” use this to cancel the reservation if needed
reservation_details.numberThe reserved phone number
reservation_details.created_atWhen the reservation was created
reservation_details.expires_atWhen 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"
}