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

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 the Authorization: Bearer uk_... header.

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

      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

      • 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

    • 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

  • 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": "BR8 7RE",
        "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
}