Licensees

Use this resource to create and mange licensees belonging to a key. To find out more about licensees, read the licensees FAQ.


List Licensees

GET /keys/:key/licensees

Returns a list of licensees for a key.

Query Parameters

Property Description
user_token Required unless authenticating with Authorization HTTP Header. Your user token can be found on your account information page. Do not reveal this key.
starting_after Optional. Specify ID of the licensee after which you would like to list results
limit Optional. Specify the maximum number of results to return per page. Default and maximum is 100.
query Optional. Filter result by licensee name. Query can be shortened to q=

Request

https://api.ideal-postcodes.co.uk/v1/keys/iddqd/licensees?user_token=my_secret_token

Response

{
     "result":{
            "licensees":[
                 {
                        "id":"56a10d49ebe230380bf104c1",
                        "key":"sl_ijoi0qlrTRIGCej30vJdN",
                        "name":"Online Commerce Limited",
                        "address":"10 Darwin Place, Holborn, London",
                        "postcode":"E12 9WW",
                        "createdAt":"2016-01-21T16:54:33.906Z",
                        "whitelist": [],
                        "daily": {
                            "limit": null,
                            "count": 0,
                            "updatedAt": "2016-08-05T16:43:28.865Z"
                        }
                 },
                 {
                        "id":"56a1119febe230380bf104c2",
                        "key":"sl_ijoioiyaZCZA5klg1ZxID",
                        "name":"Brian Jones",
                        "address":"10 Hilldown Close, Surrey",
                        "postcode":"IS1 0SK",
                        "createdAt":"2016-01-21T17:13:03.731Z",
                        "whitelist": [],
                        "daily": {
                            "limit": null,
                            "count": 0,
                            "updatedAt": "2016-08-05T16:43:28.865Z"
                        }
                 },
                 {
                        "id":"56a11209ebe230380bf104c3",
                        "key":"sl_ijoiqsxeQgXW2gkiE0X94",
                        "name":"Qwerty Widgets Limited",
                        "address":"12 High Street, Manchester",
                        "postcode":"ID1 1QD",
                        "createdAt":"2016-01-21T17:14:49.971Z",
                        "whitelist": [],
                        "daily": {
                            "limit": null,
                            "count": 0,
                            "updatedAt": "2016-08-05T16:43:28.865Z"
                        }
                 }
            ],
            "hasMore":false
     },
     "code":2000,
     "message":"Success"
}
Property Description
licensees.id string An immutable ID provided for every licensee. Primarily used for paginated list requests
licensees.key string Uniquely identifies a licensee for a key. Required to perform paid lookups for a specific licensee
licensees.name string Licensee individual or organisation name
licensees.address string Licensee's first, second and third line address as well as post town concatenated by commas
licensees.postcode string Licensee's postcode
licensees.createdAt string Timestamp for when the licensee was created
licensees.whitelist string[] A whitelist of authorised URLs. An empty list means that whitelisting is disabled
licensees.daily.limit number The maximum number of lookups this licensee can perform in a day. null indicates the limit is not active
licensees.daily.count number The number lookups performed by the licensee on the day represented by licensees.daily.updatedAt
licensees.daily.updatedAt string The timestamp when the limit was last used
hasMore boolean Returns true if there are more licensees listed after the maximum number of results as implied by limit

Retrieve Licensee

GET /keys/:key/licensees/:licensee_key

Returns a licensee information as identified by the licensee key

Query Parameters

Property Description
user_token Required unless authenticating with Authorization HTTP Header. Your user token can be found on your account information page. Please do not reveal this key.

Request

https://api.ideal-postcodes.co.uk/v1/keys/iddqd/licensees/sl_ijoi0qlrTRIGCej30vJdN?user_token=my_secret_token

Response

{
    "result":{
        "id":"56a10d49ebe230380bf104c1",
        "key":"sl_ijoi0qlrTRIGCej30vJdN",
        "name":"Online Commerce Limited",
        "address":"10 Darwin Place, Holborn, London",
        "postcode":"E12 9WW",
        "createdAt":"2016-01-21T16:54:33.906Z",
        "whitelist": [],
        "daily": {
            "limit": null,
            "count": 0,
            "updatedAt": "2016-08-05T16:43:28.865Z"
        }
     },
     "code":2000,
     "message":"Success"
}
Property Description
licensees.id string An immutable ID provided for every licensee. Primarily used for paginated list requests
licensees.key string Uniquely identifies a licensee for a key. Required to perform paid lookups for a specific licensee
licensees.name string Licensee individual or organisation name
licensees.address string Licensee's first, second and third line address as well as post town concatenated by commas
licensees.postcode string Licensee's postcode
licensees.createdAt string Timestamp for when the licensee was created
licensees.whitelist string[] A whitelist of authorised URLs. An empty list means that whitelisting is disabled
licensees.daily.limit numberThe maximum number of lookups this licensee can perform in a day. null indicates the limit is not active
licensees.daily.count number The number lookups performed by the licensee on the day represented by licensees.daily.updatedAt
licensees.daily.updatedAt string The timestamp when the limit was last used

Create a Licensee

POST /keys/:key/licensees

Create a licensee for the specified API Key.

Query Parameters

Property Description
user_token Required unless authenticating with Authorization HTTP Header. Your user token can be found on your account information page. Please do not reveal this key.

Request Body Format

You will need to provide a JSON object as your POST body, specifying some information about your licensee. Only application/json Content-Type is accepted.

Property Description
name string Required. Your licensee's individual or organisation name
address string Required. Licensee's first, second and third line address as well as post town concatenated by commas
postcode string Required. Licensee's postcode
whitelist string[] Optional. A whitelist of authorised URLs. Default is an empty list, which means URL whitelisting is disabled. Maximum of 5 whitelisted URLs and each no longer than 256 characters
daily.limit number Optional. The maximum number of lookups this licensee can perform in a day. Set to null to deactivate the limit

Request

POST https://api.ideal-postcodes.co.uk/v1/keys/iddqd/licensees?user_token=my_secret_token

Request Body

{
    "name":"Online Commerce Limited",
    "address":"10 Darwin Place, Holborn, London",
    "postcode":"E12 9WW",
    "whitelist": ["foo", "bar"],
    "daily": {
        "limit": 5
    }
}

Response

{
    "result":{
        "id":"56a10d49ebe230380bf104c1",
        "key":"sl_ijoi0qlrTRIGCej30vJdN",
        "name":"Online Commerce Limited",
        "address":"10 Darwin Place, Holborn, London",
        "postcode":"E12 9WW",
        "createdAt":"2016-01-21T16:54:33.906Z",
        "whitelist": ["foo", "bar"],
        "daily": {
            "limit": 5,
            "count": 0,
            "updatedAt": "2016-08-05T16:43:28.865Z"
        }
     },
     "code":2000,
     "message":"Success"
}
Property Description
licensees.id string An immutable ID provided for every licensee. Primarily used for paginated list requests
licensees.key string Uniquely identifies a licensee for a key. Required to perform paid lookups for a specific licensee
licensees.name string Licensee individual or organisation name
licensees.address string Licensee's first, second and third line address as well as post town concatenated by commas
licensees.postcode string Licensee's postcode
licensees.whitelist string[] A whitelist of authorised URLs
licensees.daily.limit number The maximum number of lookups this licensee can perform in a day. null indicates the limit is not active
licensees.daily.count number The number lookups performed by the licensee on the day represented by licensees.daily.updatedAt
licensees.daily.updatedAt string The date when the limit was last used
licensees.createdAt string Timestamp for when the licensee was created

Update a Licensee

POST /keys/:key/licensees/:licensee_key

Update a licensee as specified by its API and Licensee keys.

Query Parameters

Property Description
user_token Required unless authenticating with Authorization HTTP Header. Your user token can be found on your account information page. Please do not reveal this key.

Request Body Format

You will need to provide a JSON object as your POST body, specifying the information to be updated for your licensee. Only application/json Content-Type is accepted.

Property Description
address string Optional. Licensee's first, second and third line address as well as post town concatenated by commas
postcode string Optional. Licensee's postcode
whitelist string[] Optional. A list of authorised URLs. Set to an empty array to disable whitelisting. Maximum of 5 whitelisted URLs and each no longer than 256 characters
daily.limit number Optional. The maximum number of lookups this licensee can perform in a day. null indicates the limit is not active

Request

POST https://api.ideal-postcodes.co.uk/v1/keys/iddqd/licensees/sl_ijoi0qlrTRIGCej30vJdN?user_token=my_secret_token

Request Body

{
    "address":"2 Surrey Place, Canary Wharf, London",
    "whitelist": ["https://www.example.com"],
    "daily": {
        "limit": 100
    }
}

Response

{
    "result":{
        "id":"56a10d49ebe230380bf104c1",
        "key":"sl_ijoi0qlrTRIGCej30vJdN",
        "name":"Online Commerce Limited",
        "address":"2 Surrey Place, Canary Wharf, London",
        "postcode":"E12 9WW",
        "createdAt":"2016-01-21T16:54:33.906Z",
        "whitelist": ["https://www.example.com"],
        "daily": {
            "limit": 100,
            "count": 0,
            "updatedAt": "2016-08-05T16:43:28.865Z"
        }
     },
     
     "code":2000,
     "message":"Success"
}
Property Description
licensees.id string An immutable ID provided for every licensee. Primarily used for paginated list requests
licensees.key string Uniquely identifies a licensee for a key. Required to perform paid lookups for a specific licensee
licensees.name string Licensee individual or organisation name
licensees.address string Licensee's first, second and third line address as well as post town concatenated by commas
licensees.postcode string Licensee's postcode
licensees.whitelist array A whitelist of authorised URLs
licensees.daily.limit numberThe maximum number of lookups this licensee can perform in a day. null indicates the limit is not active
licensees.daily.count number The number lookups performed by the licensee on the day represented by licensees.daily.updatedAt
licensees.daily.updatedAt string The date when the limit was last used
licensees.createdAt string Timestamp for when the licensee was created

Delete a Licensee

DELETE /keys/:key/licensees/:licensee_key

This renders a licensee unusable. This action can be reversed if you get in contact with us.

Query Parameters

Property Description
user_token Required unless authenticating with Authorization HTTP Header. Your user token can be found on your account information page. Please do not reveal this key.

Request

DELETE https://api.ideal-postcodes.co.uk/v1/keys/iddqd/licensees/sl_ijoi0qlrTRIGCej30vJdN?user_token=my_secret_token

Response

{
    "result":{
        "deleted": 1
     },
     "code":2000,
     "message":"Success"
}
Property Description
deleted number Number of licensees deleted