Sublicensing

Ideal Postcodes now provides Sublicensed Keys. Sublicensed 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.

Sublicensed 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 Sublicensed Key and start querying addressing data for your clients, you will need to:

  • Enquire with us to create a Sublicensed Key
  • Create a licensee on your Sublicensed Key for each of your clients
  • Perform requests against the API as usual, only now you must also supply an additional 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 Sublicensed 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 licensees 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...

https://api.ideal-postcodes.co.uk/v1/postcodes/ID11QD?api_key=iddqd

now becomes...

https://api.ideal-postcodes.co.uk/v1/postcodes/ID11QD?api_key=iddqd&licensee=sk_i98n29d8dj3K

Billing

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 querystring 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.