Retrieve Licensee

GET/v1/keys/{key}/licensees/{licensee}

Returns a licensee by its sl_ key. A cancelled or unknown licensee returns 404.

Path parameters

key string

API Key

The API Key. Begins ak_.

Example ak_test

licensee string

Licensee Key

Uniquely identifies a licensee.

Example sl_hk71kco54zGSGvF9eXXrvvnMOLLNh

Query parameters

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

Response

result is the licensee object, including metadata like when it was created and current daily lookup statistics.

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

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/sl_ijoiqsxeQgXW2gkiE0X94?user_token=uk_secret

curl

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

JavaScript

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

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

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

Python

# pip install ideal-postcodes
from ideal_postcodes import IdealPostcodes

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

Ruby

require "net/http"
require "json"

uri = URI("https://api.ideal-postcodes.co.uk/v1/keys/ak_test/licensees/sl_ijoiqsxeQgXW2gkiE0X94")
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/sl_ijoiqsxeQgXW2gkiE0X94?" .
  http_build_query([
    "user_token" => "uk_secret",
  ])
);
$result = json_decode($response, true)["result"];

Response

200 OK

{
  "result": {
    "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"
    }
  },
  "code": 2000,
  "message": "Success"
}