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

Example uk_B59ScW1p1HHouf1VqclEPZUx

Response

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

• result Licensee

  • 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

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

const response = await fetch(
  'https://api.ideal-postcodes.co.uk/v1/keys/ak_test/licensees/sl_ijoiqsxeQgXW2gkiE0X94?' +
  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/sl_ijoiqsxeQgXW2gkiE0X94",
    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/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": {
    "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"
  },
  "code": 2000,
  "message": "Success"
}