List Licensees

GET/v1/keys/{key}/licensees

Returns a key's licensees, oldest first, up to 100 per request. The list omits cancelled licensees. The key must be enabled for sublicensing.

Path parameters

key string

API Key

The API Key. Begins ak_.

Example ak_test

Query parameters

starting_after integer optional

ID of the licensee after which to list results

Format int32

user_token string optional

Management Key

A secret key used to manage your account and API Keys. It was previously called the user token.

Your management key can be retrieved and managed from your accounts page.

Typically begins uk_. Prefer sending it in the Authorization header as Bearer uk_... instead of this query parameter. The Authorization: user_token="uk_..." header also works.

Example uk_B59ScW1p1HHouf1VqclEPZUx

limit integer optional

Limit

Specifies the maximum number of records to retrieve.

By default the limit is 10. Requesting a larger result set adds latency.

Format int32Default 10Example 5

query string optional

Filter results by licensee name. Can be shortened to q=

Response

result is an object containing a paginated list of licensees and a flag indicating whether more results are available.

• result object

  List of licensees

  • licensees Licensee[]

    • id string

      An immutable ID provided for every licensee. Primarily used for paginated list requests.

      Example

      56a11209ebe230380bf104c3

    • key string

      Uniquely identifies a licensee for a key.

      Required to perform paid lookups for a specific licensee. Typically begins sl_.

      Example

      sl_ijoiqsxeQgXW2gkiE0X94

    • createdAt string

      Timestamp for when the licensee was created

      Example

      2016-01-21T17:14:49.971Z

    • name string

      Licensee individual or organisation name

      Example

      Qwerty Widgets Limited

    • address string

      Licensee's first, second and third line address as well as post town concatenated by commas

      Example

      12 High Street, Manchester

    • postcode string

      Licensee's postcode

      Example

      BR8 7RE

    • whitelist string[]

      A list of allowed URLs. An empty list disables the check.

      A request is allowed when its Origin or Referer header matches an entry. Use one of these formats:

      • https://www.example.com allows one site. Scheme and host must match
      • *.example.com allows the domain and all its subdomains
    • daily object

      • limit number

        The maximum number of lookups this licensee can perform in a day. null indicates the limit is not active

        Format

        int32

        Example

        10000

      • count number

        The number of lookups performed by the licensee on the day represented by licensees.daily.updatedAt

        Format

        int32

        Example

        232

      • updatedAt string

        The timestamp when the limit was last used.

        Example

        2016-08-05T16:43:28.865Z

  • hasMore boolean

    Returns true if there are more licensees listed after the maximum number of results as implied by limit

The result sits inside the standard { result, code, message } envelope, see the API reference for the wrapper format.

Request

URL

https://api.ideal-postcodes.co.uk/v1/keys/ak_test/licensees?user_token=uk_secret

curl

curl -G 'https://api.ideal-postcodes.co.uk/v1/keys/ak_test/licensees' \
  -d 'user_token=uk_secret'

JavaScript

import { createIdpcClient, listLicensees } from '@ideal-postcodes/sdk';

const client = createIdpcClient({ apiKey: 'ak_test', userToken: 'uk_secret' });

const { data } = await listLicensees({
  client,
  path: { key: 'ak_test' },
});

Python

# pip install ideal-postcodes
from ideal_postcodes import IdealPostcodes

with IdealPostcodes("ak_test") as client:
    result = client.list_licensees("ak_test", user_token="uk_secret")

Ruby

require "net/http"
require "json"

uri = URI("https://api.ideal-postcodes.co.uk/v1/keys/ak_test/licensees")
uri.query = URI.encode_www_form(user_token: "uk_secret")
result = JSON.parse(Net::HTTP.get(uri))["result"]

PHP

<?php
$response = file_get_contents(
  "https://api.ideal-postcodes.co.uk/v1/keys/ak_test/licensees?" .
  http_build_query([
    "user_token" => "uk_secret",
  ])
);
$result = json_decode($response, true)["result"];

Response

200 OK

{
  "result": {
    "licensees": [
      {
        "id": "56a11209ebe230380bf104c3",
        "key": "sl_ijoiqsxeQgXW2gkiE0X94",
        "createdAt": "2016-01-21T17:14:49.971Z",
        "name": "Qwerty Widgets Limited",
        "address": "12 High Street, Manchester",
        "postcode": "BR8 7RE",
        "whitelist": [
          "https://www.example.com"
        ],
        "daily": {
          "limit": 10000,
          "count": 232,
          "updatedAt": "2016-08-05T16:43:28.865Z"
        }
      }
    ],
    "hasMore": true
  },
  "message": "Success",
  "code": 2000
}