Key Logs (CSV)

GET/v1/keys/{key}/lookups

Returns a CSV of the charged lookups made on a key, one row per request.

Requires the user_token for the account. The maximum interval is 90 days. Without a start or end date the interval is the last 21 days.

The response is text/csv and downloads as an attachment. A non-200 response 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 AZ-Source-IP header. We record it only 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 weekly, covering the IP, source IP, search term and URL columns.

The default retention is 28 days. Change the period from your dashboard. Set it to 0 days to stop collecting PII 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 (redacted after configured interval)
• Referrer — Request referrer URL
• Lookup Type — Method used (Address Lookup, Address Verification, 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.addresszen.com/v1/keys/ak_test/lookups?user_token=uk_secret

curl

curl -G 'https://api.addresszen.com/v1/keys/ak_test/lookups' \
  -d 'user_token=uk_secret'

JavaScript

const response = await fetch(
  'https://api.addresszen.com/v1/keys/ak_test/lookups?' +
  new URLSearchParams({
    user_token: 'uk_secret',
  })
);

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

Python

import requests

response = requests.get(
    "https://api.addresszen.com/v1/keys/ak_test/lookups",
    params={
        "user_token": "uk_secret",
    },
)
result = response.json()["result"]

Ruby

require "net/http"
require "json"

uri = URI("https://api.addresszen.com/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.addresszen.com/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,123 Main St Springfield,https://www.example.com/,Address Lookup,
2015-02-21T16:05:38.298Z,82.85.128.18,1600 Pennsylvania Ave NW,https://www.example.com/,Address Lookup,CRM
2015-02-21T16:06:49.227Z,82.85.128.18,350 Fifth Avenue New York,https://www.example.com/,Address Verification,"Website,Live"
2015-02-21T16:07:02.706Z,82.85.128.18,1 Infinite Loop Cupertino,https://www.example.com/,Address Lookup,

400 Bad Request

response.json

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