---
title: "Reserve Number"
method: POST
path: "/v1/demo/reserve"
tags: ["Demo Numbers", "Demo Numbers"]
---

# Reserve Number

`POST /v1/demo/reserve`

## Request

- Base URL: `https://api.call2me.app`
- URL: `https://api.call2me.app/v1/demo/reserve`
- Auth: HTTP bearer

Reserve a demo number for 15 minutes.

Atomic flow:
  1. Verify eligibility (one-per-lifetime)
  2. Lock a pool row with SELECT ... FOR UPDATE SKIP LOCKED
  3. Insert demo_reservations row
  4. Mark pool row as 'reserved'
  5. Insert phone_numbers row pointing to user+agent
  6. All inside a transaction — rollback on any failure

## Request body

- ReserveRequest: Reserve a demo number.
  - `agent_id` string, nullable: Agent to bind the number to. If omitted, user can bind later.

## Response `200`

Successful Response

- ReservationInfo: Reservation detail shown to user.
  - `reservation_id` string, required
  - `phone_number` string, required
  - `country_code` string, required
  - `display_name` string, required
  - `agent_id` string, nullable, required
  - `reserved_at` string, date-time, required
  - `expires_at` string, date-time, required
  - `minutes_remaining` integer, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/call2me/apis/call2me-api.md) · [All operations](https://skmtc.dev/call2me/apis/call2me-api/llms.txt) · [OpenAPI document](https://skmtc.dev/call2me/apis/call2me-api/revisions/3951f9b7e47d?raw)