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 sub-licensing.

Path parameters

key string

API Key

The API Key to retrieve. 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

Private User Token

A secret key used for sensitive operations on your account and API Keys.

Your user token can be retrieved and managed from your accounts page.

Typically begins uk_...

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[] optional

    • 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

      ID1 1QD

    • whitelist string[]

      A list of allowed URLs. An empty list means that whitelisting is disabled

    • daily object

      • count number

        The number lookups performed by the licensee on the day represented b licesees.daily.updatedAt

        Format

        int32

        Example

        232

      • updatedAt string

        The timestamp when the limit was last used.

        Example

        2016-08-05T16:43:28.865Z

    • 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 sk_.

      Example

      sl_ijoiqsxeQgXW2gkiE0X94

    • createdAt string

      Timestamp for when the licensee was created

      Example

      2016-01-21T17:14:49.971Z

  • hasMore boolean optional

    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

const response = await fetch(
  'https://api.ideal-postcodes.co.uk/v1/keys/ak_test/licensees?' +
  new URLSearchParams({
    user_token: 'uk_secret',
  })
);

const { result } = await response.json();

Python

import requests

response = requests.get(
    "https://api.ideal-postcodes.co.uk/v1/keys/ak_test/licensees",
    params={
        "user_token": "uk_secret",
    },
)
result = response.json()["result"]

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": [
      {
        "name": "Qwerty Widgets Limited",
        "address": "12 High Street, Manchester",
        "postcode": "ID1 1QD",
        "whitelist": [
          "https://www.example.com"
        ],
        "daily": {
          "count": 232,
          "updatedAt": "2016-08-05T16:43:28.865Z"
        },
        "id": "56a11209ebe230380bf104c3",
        "key": "sl_ijoiqsxeQgXW2gkiE0X94",
        "createdAt": "2016-01-21T17:14:49.971Z"
      }
    ],
    "hasMore": true
  },
  "message": "Success",
  "code": 2000
}