NumberGroup API

What you can do with it

• Temporary or permanent DDI allocation for sales pages, auctions and listings.
• Automated number diversions for out-of-hours support rotas.
• Number search and reservation for distribution partners or referral sites.
• Programmatic access to Call Detail Records for third-party billing, reporting or attribution.
• Dynamic number insertion (DNI) for paid-search campaigns — see the call-tracking recipe.

Base URL and transport

Every call is an HTTPS GET to api.numbergroup.com with query-string parameters. Responses come back in the body of the HTTP response in either JSON or XML — pick with &format=json or &format=xml. JSON is the default for everything except the CDR feed, which is JSON only for efficiency reasons.

https://api.numbergroup.com/<method>?api_key=...&format=json&...

The server presents NumberGroup's wildcard TLS certificate. Your client should validate it like any other HTTPS endpoint.

Authentication

Every call carries an api_key query parameter. There's no MD5 challenge, no OAuth dance, no bearer token — just the key. The key identifies both the caller and the account that owns any resources the call touches.

The first time a new source IP issues a call against a given key, the API accepts it and adds the host to the record of known callers, then emails the account contact so you can spot it. If you receive a new-host alert you don't recognise, mail help@numbergroup.com and we'll rotate the key.

Status, success and failure

Every response carries a status object (JSON) or <status> element (XML) with a type of success or fail. On failure, a reason string tells you what went wrong. Always check status.type before reading the rest of the body.

// success
{"translation":{"ddi":"08000588026", ...},"status":{"type":"success","reason":""}}

// failure
{"status":{"type":"fail","reason":"Invalid API key specified"}}

Transaction limits

• Default limit is 1,000 transactions per day per API key. Tell us if you need more.
• CDR Feed calls don't count against the daily limit.
• Suspicious activity from an IP can result in that IP being blocked. The failure reason will say so.

Methods

Recipes

• Build dynamic number insertion (DNI) for paid search — pool numbers, reserve, allocate, swap on the page, report from the CDR feed.

An evolving API

This API is an evolving feature of the NumberGroup network. Suggestions for additional methods or parameters are welcome — drop a line to help@numbergroup.com with what you're trying to build and we'll see what we can do.