Skip to main content


Ideal Postcodes now provides Sublicensing Keys. Sublicensing Keys allow you to license multiple organisations or individuals under the same key. All managed, controlled and billed to you under the same account.

Previously, all keys could only be used by the named Licensee (the individual or organisation) tied to the Ideal Postcodes account. Now, you may create multiple alternate Licensees under a single Key. From there, you may query the API remembering to include a Licensee key to charge a lookup to a particular Licensee.

Sublicensing Keys are ideal for platform vendors, who provide services to multiple clients who in turn each have their own users.

How it Works#

To acquire a Sublicensing Key and start querying addressing data for your clients, you will need to:

  • Enquire with us to create a Sublicensing Key
  • Create a Licensee on your Sublicensing Key for each of your clients
  • Perform requests against the API as usual, only now you must supply the Licensee key corresponding to the relevant client

Getting a Key#

If you'd like a key please get in contact with us and we will convert one of your existing keys into a Sublicensing Key. This key will not require a prepaid balance to operate and will carry an embedded limit on the number of requests you can make per day.

Creating a Licensee#

You may create a Licensee on a key using the API directly or via the dashboard. The information we require is your Licensee's individual or organisation name and their address. Your Licensees will also need to agree to Royal Mail's terms of use when you acquire them, this can be done by including the terms of use in your own terms.

Querying the API#

For methods that yield Royal Mail data and incur a lookup cost (e.g. /v1/postcodes/ and /v1/addresses/), you will need to provide a Licensee key as well as the API key. Each Licensee created will automatically receive a random key which you will use to identify their account.

For instance, a postcode lookup...

now becomes...


Lookups will be charged at the standard rate of 2p + VAT per lookup in blocks of 100 lookups at a time. You will be billed on a monthly basis via direct debit based on your usage of the API.

Due to current licensing rules, each of your Licensees must procure 100 lookups ahead of any request.

In practice, what this means is that we will round up your client's usage of our API to the nearest 100 lookups. So for example, if in month 1, your client consumes 60 lookups, you will be billed for £2 + VAT for that month. If in month 2, your client consumes another 30 (90 in total), you will be billed nothing for that month. If in month 3, your client consumes another 20 (110 in total) you will be billed another £2 + VAT for that month.

Monitoring Usage#

The /keys/:key/usage and/keys/:key/lookups have been updated to accept a Licensee in the query string should you wish to gauge usage by each of your Licensees.

Updating Licensee Information#

Should your Licensees update their addressing information, you can use the Licensees API to update their information. If you wish to change the organisation name, you will need to get in contact with us.