Key Logs (CSV)

GET/v1/keys/{key}/lookups

Returns a CSV of the paid lookups made on a key, with the information recorded against each one.

This method requires a user_token, which can be found on your accounts page.

You can request a maximum interval of 90 days. Without a start or end date, the interval defaults to the last 21 days.

The Content-Type returned is CSV (text/csv). For a non-200 response it reverts to JSON, with the error code and message in the body.

CSV Format

The CSV has no header row. Columns, in order:

1. Timestamp (ISO 8601)
2. IP address the request was received from
3. Search term
4. URL the request originated from
5. Lookup type
6. Tags
7. Lookups consumed
8. Licensee name (sublicensing keys only)
9. Source IP address

The source IP column carries the address forwarded in the IDPC-Source-IP header. It is only recorded for keys with IP address forwarding enabled, and only when the header holds a valid IP address. It is empty otherwise.

Data Redaction

We redact Personally Identifiable Data (PII) in your usage log (including IP, source IP, search term and URL data) weekly.

By default we redact PII older than 28 days. You can change this period from your dashboard.

Set the interval to 0 days to prevent PII collection altogether.

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

start integer optional

Start Timestamp

A start date/time in the form of a UNIX Timestamp in milliseconds. E.g. 1418556452651

Format int64Example 1418556452651

end integer optional

End Timestamp

An end date/time in the form of a UNIX Timestamp in milliseconds. E.g. 1418556477882

Format int64Example 1418556492651

licensee string optional

Licensee Key

Uniquely identifies a licensee.

Example sl_hk71kco54zGSGvF9eXXrvvnMOLLNh

Response

The response is a CSV file with the following columns:

• Timestamp — Lookup timestamp (ISO 8601 format)
• IP Address — Client IP address (redacted after configured interval)
• Query — Search term or postcode (redacted after configured interval)
• Referrer — Request referrer URL
• Lookup Type — Method used (Postcode Lookup, Address Lookup, etc.)
• Tags — Associated transaction tags (comma-separated)

Data Redaction

Personally Identifiable Data (PII) including IP addresses, search terms, and URLs are automatically redacted on a weekly basis. By default, PII is redacted if older than 21 days — this can be configured from your account dashboard.

To prevent PII collection entirely, set the redaction interval to 0 days.

Request

URL

https://api.ideal-postcodes.co.uk/v1/keys/ak_test/lookups?user_token=uk_secret

curl

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

JavaScript

const response = await fetch(
  'https://api.ideal-postcodes.co.uk/v1/keys/ak_test/lookups?' +
  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/lookups",
    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/lookups")
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/lookups?" .
  http_build_query([
    "user_token" => "uk_secret",
  ])
);
$result = json_decode($response, true)["result"];

Response

200 OK (CSV)

lookups.csv

2015-02-21T16:05:22.991Z,82.85.128.18,SW12AA,https://www.example.com/,Postcode Lookup,
2015-02-21T16:05:38.298Z,82.85.128.18,10 Downing Street London,https://www.example.com/,Address Lookup,CRM
2015-02-21T16:06:49.227Z,82.85.128.18,OX44PP,https://www.example.com/,Postcode Lookup,"Website,Live"
2015-02-21T16:07:02.706Z,82.85.128.18,PL9 9HE,https://www.example.com/,Postcode Lookup,

400 Bad Request

response.json

{
  "code": 4000,
  "message": "Invalid date range"
}