Skip to main content

Sublicensing

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

/v1/autocomplete/addresses?api_key=ak_test

now becomes...

/v1/autocomplete/addresses?api_key=sk_i98n29d8dj3K

Billing​

Due to the way data must be licensed with upstream vendors, each Licensee 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 the first 100 lookups 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 for another 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.