Method

Reservations

Search for available DDIs without allocating them. Up to 20 numbers come back per call, held against your session so no other caller sees them. Reserve the ones you want for 24 hours, then promote to a real allocation with Translation Request.

Endpoint

GET https://api.numbergroup.com/reservations

The session_id contract

The first call returns a session_id. You must include that session_id on every follow-up call that touches DDIs from the same search — reserving them, or eventually allocating them via Translation Request. Treat it like a per-user shopping basket; keep it for the lifetime of that visitor.

Two phases of the call

1. Search the pool

https://api.numbergroup.com/reservations
  ?api_key=xxxyyy
  &ddi_type=01
  &ddi_subtype=01234

Response (XML shown; JSON has the same shape):

<?xml version="1.0"?>
<reservations>
  <status type="success" reason=""/>
  <session_id value="nu4ko7a4sc"/>
  <ddi_list>
    <ddi_item>
      <ddi>441234945002</ddi>
      <display_as>01234945002</display_as>
    </ddi_item>
    <ddi_item>
      <ddi>441234945005</ddi>
      <display_as>01234945005</display_as>
    </ddi_item>
    ... up to 20 DDIs
  </ddi_list>
</reservations>

Each ddi_item gives you the E.164 form (for further API calls) and a display_as string formatted for humans. Every DDI in the list is held for 10 minutes while the user picks.

2. Reserve a specific DDI

https://api.numbergroup.com/reservations
  ?api_key=xxxyyy
  &ddi=441234945132
  &session_id=nu4ko7a4sc
  &reserve

Response:

<?xml version="1.0"?>
<reservations>
  <status type="success" reason="DDI Reserved"/>
</reservations>

That DDI is now yours for 24 hours. Reissue the same call to extend by another 24 hours. When the user is ready, promote to a live allocation:

https://api.numbergroup.com/translationrequest
  ?api_key=xxxyyy
  &ddi=441234945132
  &translation=sip:user@sip.mydomain.com

Parameters

Parameter	Required	Description
api_key	Yes	Your API key.
ddi_type	Yes	The number type — `01`, `03`, `0800`, etc.
ddi_subtype	No	For `ddi_type=01`, the area code, e.g. `01234`.
ddi_limit	No	Limit the number of DDIs returned (max 20).
session_id	No	Required on any follow-up that refers to DDIs from a previous search — reservations and allocations both need it.
ddi	No	The DDI to reserve. Pair with `reserve`.
reserve	No	Presence-only flag (`&reserve`) — reserves the `ddi` against your `session_id`.
clear	No	Releases any DDIs previously reserved against the given session_id back to the pool.
cherish_band	No	Restricts the search to a specific cherished number band — for premium / memorable numbers. Omit for the standard pool.
format	No	`xml` or `json`. Defaults to JSON.

Lifetimes

Search results — held for 10 minutes against your session.
Explicit reservation — held for 24 hours; reissue the reserve call to extend another 24 hours.
clear — returns everything held against that session_id immediately.

Cherished number bands

Pass cherish_band to pull numbers from a memorable-number band. Use it when you're building a numbers picker that should offer premium / repeating-digit DDIs instead of whatever the next-available pool gives back. Members get cherished numbers included; resold to non-Members at our published rates.

Need an API key?

We don't have a self-serve signup for API keys — drop us a line and we'll set you up. Tell us roughly what you're building so we can recommend the right transaction limit.

Request an API key →help@numbergroup.com