Method
Translation Update
Update an existing DDI's destination, add features like hunting and voicemail, extend a TTL, or release the number. Any parameter you omit is left untouched — so this is also how you layer features on top of a basic Translation Request.
Endpoint
GET https://api.numbergroup.com/translationupdateWhen to use it
- Change where an allocated DDI sends calls.
- Add hunting across multiple destinations.
- Set a missed-call alert or send unanswered calls to voicemail.
- Extend the lifetime of a temporary DDI.
- Release a DDI back to the available pool (
delete=1).
The translation must already exist. To set up features on a brand-new number, call Translation Request first with a basic destination, then call Translation Update.
Example
https://api.numbergroup.com/translationupdate
?api_key=xxxyyy
&ddi=448001230987
&translation=4412340012345,4419080087123
&translation_mode=even
&call_failure_mode=EMVCEMAIL
&alert_address=help@numbergroup.comThis points 0800 1230987 at two destinations, distributes calls between them randomly, and sends unanswered calls to voicemail with an alert to help@numbergroup.com.
Parameters
| Parameter | Required | Description |
|---|---|---|
| api_key | Yes | Your API key. |
| ddi | Yes | The DDI to update, in E.164 form. |
| translation | No | New destination(s). Comma-separated for multiple destinations. |
| translation_mode | No | Hunting strategy when multiple destinations are given. inturn (try each in order), together (ring all at once) or even (like inturn but the order is randomised per call). |
| call_failure_mode | No | What to do when no destination answers. NONE, EMALERT (email a missed-call alert), or EMVCEMAIL (voicemail). |
| alert_address | No | Email address for EMALERT / EMVCEMAIL. |
| ring_timer | No | Seconds to ring each destination before moving on or alerting. |
| ttl | No | Extend the DDI lifetime by this many days. |
| name | No | Sets the name field shown on selfcare. |
| delete | No | Pass delete=1 to remove the translation and release the DDI. |
| format | No | xml or json. Defaults to JSON. |
Successful response
<?xml version="1.0"?>
<translationupdate>
<status type="success" reason=""/>
<translation>
<ddi>448001230987</ddi>
<ddi_type>01</ddi_type>
<translates_to>4412340012345,4419080087123</translates_to>
</translation>
</translationupdate>Pattern: layer features onto a new number
- Call Translation Request with a single destination.
- Call Translation Update with the same DDI and the features you want.
- To change just one thing later, send only that parameter — everything else stays as it was.
Pattern: release a temporary DDI early
https://api.numbergroup.com/translationupdate
?api_key=xxxyyy
&ddi=448441234567
&delete=1The DDI stops working immediately and goes back into the available pool, so you only carry numbers as long as you actually need them.
See also
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.