---
title: "Reserve numbers to close the search-vs-order race"
method: POST
path: "/api/call-tracking/numbers/reserve"
tags: ["Call Tracking"]
---

# Reserve numbers to close the search-vs-order race

`POST /api/call-tracking/numbers/reserve`

Reserve a list of phone numbers via Telnyx so the user has a window to
confirm purchase without losing them to other Telnyx customers.

Telnyx's available_phone_numbers index is non-authoritative — numbers can
be listed there yet rejected at order time. This endpoint calls
POST /v2/number_reservations to hold the numbers for ~60s (extendable
once), making the subsequent purchase deterministic.

Body: {"phone_numbers": ["+351...", "+351..."]}

Returns:
    {
        "reservation_id": str,
        "status": "pending"|"success"|"failure",
        "expires_at": ISO timestamp,
        "phone_numbers": [
            {"phone_number": "+351...", "status": "success"|"failure"},
            ...
        ]
    }

Numbers with status="failure" should be excluded from the upcoming order
and the user prompted to pick replacements.

## Headers

- `x-api-token` string, nullable

## Request body

- object

## Response `200`

Successful Response

- object

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/multigest/apis/multigest-protected-api.md) · [All operations](https://skmtc.dev/multigest/apis/multigest-protected-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/multigest/multigest-protected-api/revisions/8492136eefc5/schema)