Create Licensee

POST/v1/keys/{key}/licensees

Creates a licensee on a key and returns it with its generated sl_ key. 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

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

Request body

Submit a JSON object with the licensee details:

• body LicenseeEditable

  Licensee object which can be defined by user

  • name string optional

    Licensee individual or organisation name

    Example

    Qwerty Widgets Limited

  • address string optional

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

    Example

    12 High Street, Manchester

  • postcode string optional

    Licensee's postcode

    Example

    ID1 1QD

  • whitelist string[] optional

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

  • daily object optional

    • limit number optional

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

      Format

      int32

      Example

      10000

Response

result is the created licensee object. Each licensee includes an immutable id and a unique key (beginning sl_) used for subsequent requests.

• 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

    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

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

Request

curl

curl -X POST 'https://api.ideal-postcodes.co.uk/v1/keys/ak_test/licensees?user_token=uk_secret' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Qwerty Widgets Limited",
    "address": "12 High Street, Manchester",
    "postcode": "ID1 1QD",
    "whitelist": [],
    "daily": {
      "limit": 10000
    }
  }'

JavaScript

const response = await fetch('https://api.ideal-postcodes.co.uk/v1/keys/ak_test/licensees?user_token=uk_secret', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Qwerty Widgets Limited',
    address: '12 High Street, Manchester',
    postcode: 'ID1 1QD',
    whitelist: [],
    daily: {
      limit: 10000,
    },
  }),
});

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

Python

import requests

response = requests.post(
    "https://api.ideal-postcodes.co.uk/v1/keys/ak_test/licensees",
    params={"user_token": "uk_secret"},
    json={
        "name": "Qwerty Widgets Limited",
        "address": "12 High Street, Manchester",
        "postcode": "ID1 1QD",
        "whitelist": [],
        "daily": {
            "limit": 10000,
        },
    },
)
result = response.json()["result"]

Ruby

require "net/http"
require "json"

uri = URI("https://api.ideal-postcodes.co.uk/v1/keys/ak_test/licensees?user_token=uk_secret")
body = {
  name: "Qwerty Widgets Limited",
  address: "12 High Street, Manchester",
  postcode: "ID1 1QD",
  whitelist: [],
  daily: {
    limit: 10000,
  },
}
response = Net::HTTP.post(uri, body.to_json, "Content-Type" => "application/json")
result = JSON.parse(response.body)["result"]

PHP

<?php
$ch = curl_init("https://api.ideal-postcodes.co.uk/v1/keys/ak_test/licensees?user_token=uk_secret");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode([
    "name" => "Qwerty Widgets Limited",
    "address" => "12 High Street, Manchester",
    "postcode" => "ID1 1QD",
    "whitelist" => [],
    "daily" => [
      "limit" => 10000,
    ],
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true)["result"];

Body

{
  "name": "Qwerty Widgets Limited",
  "address": "12 High Street, Manchester",
  "postcode": "ID1 1QD",
  "whitelist": [
    "https://www.example.com"
  ],
  "daily": {
    "limit": 10000
  }
}

Response

200 OK

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