Method

Translation Request

Allocate a DDI to the account that owns your API key and set its translation in a single call. Use it to grab the next available 0800, pin a specific number, or hand out a 30-day temporary DDI for a listing.

Endpoint

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

How you can request a DDI

The next available DDI of a given type (for example 0800).
The next available DDI of a type and subtype (for example 01 with subtype 01908).
A specific DDI, either previously reserved via the Reservations method or one you happen to know is unallocated.

Every call must include a translation destination. If you need richer behaviour (hunting, voicemail, missed-call alerts), issue the basic request first then follow up with Translation Update.

Example

https://api.numbergroup.com/translationrequest
  ?api_key=xxxyyy
  &ddi_type=01
  &ddi_subtype=01908
  &translation=4412340012345
  &ttl=30

Destination formats

The translation parameter is URL-encoded and may take one of the following shapes.

E.164             translation=441234945001
SIP host only     translation=sip:sip.myserver.com
Full SIP URI      translation=sip:1001@sip.mypbx.com
NumberGroup trunk translation=trunk:T-M00123456-001
Media stream      translation=stream:mp3.myiceserver.com/stream.mp3

E.164 — fully international, no leading zero or plus.
SIP host only — NumberGroup adds the DDI as the user part of the URI automatically.
Full SIP URI — NumberGroup sends the INVITE as-is.
Trunk — a trunk ID registered with NumberGroup. Useful if you have a PBX with us.
Stream — any media stream reachable from the public Internet (Shoutcast and similar).

Parameters

Parameter	Required	Description
api_key	Yes	Your API key. Identifies caller and account.
ddi_type	Yes	The number type — `01`, `03`, `0800`, `0844`, etc.
translation	Yes	Destination for incoming calls (see formats above).
ddi_subtype	No	For `ddi_type=01`, the area code you want, e.g. `01234`.
ddi	No	Specific E.164 to allocate, instead of letting the API pick one.
ttl	No	If set, the DDI is only allocated for this many days, then returned to the pool.
name	No	Sets the name field shown on selfcare.
format	No	`xml` or `json`. Defaults to JSON.

Successful response

<?xml version="1.0"?>
<translationrequest>
  <status type="success" reason=""/>
  <translation>
    <ddi>08444109713</ddi>
    <ddi_type>0844</ddi_type>
    <translates_to>447779263488</translates_to>
    <expires>2010-08-30 01:08:17</expires>
  </translation>
</translationrequest>

Fields returned

ddi — the allocated DDI in human-readable form.
ddi_type — the range it came from.
translates_to — your destination, normalised to the platform format.
expires — UTC time the allocation expires. Only present if ttl was supplied.

Failure reasons

On failure, status.type will be fail and reason will be one of:

IP Address Blocked (a.b.c.d) — your source IP has been blocked for suspicious activity.
No API key specified / Invalid API key specified.
No translation specified.
No DDI or DDI Type specified — at least one is required.
Invalid TTL — couldn't parse as days.
Exceeded allowed transaction limits — you've hit your daily or monthly cap.
Invalid ddi type.
Specified subtype does not exist — the subtype isn't in the given DDI type group.
Cannot allocate requested DDI — the number doesn't exist, or is reserved to another key.
Internal account error — contact support.
Invalid translation address — the destination couldn't be parsed.
Unsupported translation destination — typically a PSTN destination that isn't billable on your account.
DDI type or DDI does not match DDI type requested — the combination conflicts with our records.

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