Update Key Details

PUT/v1/keys/{key}/details

Updates a key's settings and returns its private details. Only the fields you send change. A key on an unlimited plan ignores changes to datasets, daily_limit and monthly_limit.

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

The request body accepts the following editable fields:

body ApiKeyDetailsEditable
- name string optional
  A name for the key
  Example
  My API Key
- daily_limit object optional
  - limit integer optional
    number or null. The daily lookup limit currently set on your key. null means the limit is currently disabled.
    Format
    int32
    Example
    1000
- monthly_limit object optional
  - limit integer optional
    number or null. The monthly lookup limit currently set on your key. null means the limit is currently disabled.
    Format
    int32
    Example
    10000
- individual_limit object optional
  - limit integer optional
    number or null Limit set on the number of lookups that can be performed from a single IP address. null means the limit is currently disabled.
    Format
    int32
    Example
    30
- allowed_urls string[] optional
  A list of allowed URLs. An empty list means that allowed URLs are disabled. Up to 10 allowed.
- redact_days integer optional
  Number of days to preserve personal data stored in your key usage history. Set to 0 to prevent personal data storage
  Default
  28
- notifications object optional
  - emails string[] optional
    A list of email addresses designated by you to receive notifications about this key. Up to 5 allowed.
  - enabled boolean optional
    Indicates whether email notifications are enabled.
  - balance_threshold integer optional
    Balance threshold that triggers a reminder email. null to disable.
    Format
    int32
    Example
    500
  - no_balance boolean optional
    Send notice when balance hits zero.
  - limit_reached boolean optional
    Send notice when rate limit is reached.
- ip_forwarding boolean optional
  Accept IP addresses forwarded in the AZ-Source-IP header
  Default
  false
- datasets object optional
  Indicates which datasets are available and added by default to the address responses
  - pafa boolean optional
    UK Property Alias dataset
    Example
    false
  - pafw boolean optional
    UK Welsh Language Dataset
    Example
    false
  - usps boolean optional
    US Address Dataset
    Example
    true
  - hereap boolean optional
    Asia Pacific Address File
    Example
    true
  - herehk boolean optional
    Hong Kong Address File
    Example
    true
  - herei boolean optional
    India Address File
    Example
    true
  - herem boolean optional
    Macau Address File
    Example
    true
  - heremea boolean optional
    Middle East and Africa Address File
    Example
    true
  - heremeas boolean optional
    Middle East and Africa Extended File
    Example
    true
  - herena boolean optional
    North America Address File
    Example
    true
  - hereo boolean optional
    Oceania Address File
    Example
    true
  - heresa boolean optional
    South America Address File
    Example
    true
  - heret boolean optional
    Taiwan Address File
    Example
    true
  - hereee boolean optional
    Eastern Europe Address File
    Example
    true
  - herewe boolean optional
    Western Europe Address File
    Example
    true
  - phone boolean optional
    Phone validation is enabled
    Example
    true
  - email boolean optional
    Email validation is enabled
    Example
    true
  - gnaf boolean optional
    Australia: Geoscape Geocoded National Address File
    Example
    true
  - kadaster boolean optional
    Netherlands: Kadaster BAG 2.0 Address File
    Example
    true
  - kartverket boolean optional
    Norway: Kartverket Address File
    Example
    true
  - sdfi boolean optional
    Denmark: SDFI Address File
    Example
    true
  - cannar boolean optional
    Canada: Statistics Canada National Address Register
    Example
    true
  - fodbosa boolean optional
    Belgium: FOD BOSA Address File
    Example
    true
  - mois boolean optional
    South Korea: MOIS Address File
    Example
    true
  - upujp boolean optional
    Japan: UPU Address File
    Example
    true
  - bev boolean optional
    Austria: BEV Address File
    Example
    true
  - ban boolean optional
    France: BAN (Base Adresse Nationale)
    Example
    true
  - swt boolean optional
    Switzerland and Liechtenstein: Swisstopo Address File
    Example
    true
  - ab boolean optional
    UK AddressBase dataset
    Example
    false
  - abp boolean optional
    UK AddressBase Premium dataset
    Example
    false
  - nip boolean optional
    Northern Ireland Pointer Dataset
    Example
    false
  - gbrcleanse boolean optional
    UK GBR Cleanse
    Example
    true
  - uspscleanse boolean optional
    US CASS Cleanse
    Example
    true

Response

Returns the full key details object after applying the update.

result ApiKeyDetails
- name string
  A name for the key
  Example
  My API Key
- contexts object[]
  A list of available contexts for a key
  - iso_3 string
    3 letter ISO code
    Example
    USA
  - iso_2 string
    2 letter ISO code
    Example
    US
  - description string
    Country descriptor to show in Address Finder
    Example
    United States
  - emoji string
    Emoji text icon
    Example
    🇺🇸
  - rgeo boolean
    Indicates availability of reverse geolocation search
    Example
    true
- lookups_remaining integer
  Format
  int32
  Example
  19889
- daily_limit ApiKeyDailyLimit
  - limit integer
    number or null. The daily lookup limit currently set on your key. null means the limit is currently disabled.
    Format
    int32
    Example
    1000
  - consumed integer
    Number of lookups performed today which count towards your daily limit.
    Format
    int32
    Example
    288
- monthly_limit ApiKeyMonthlyLimit
  - limit integer
    number or null. The monthly lookup limit currently set on your key. null means the limit is currently disabled.
    Format
    int32
    Example
    10000
  - consumed integer
    Number of lookups performed this month which count towards your monthly limit.
    Format
    int32
    Example
    2500
- individual_limit ApiKeyIndividualLimit
  - limit integer
    number or null Limit set on the number of lookups that can be performed from a single IP address. null means the limit is currently disabled.
    Format
    int32
    Example
    30
- allowed_urls string[]
  A list of allowed URLs. An empty list means that allowed URLs are disabled.
- redact_days integer
  Number of days to preserve personal data stored in your key usage history. Set to 0 to prevent personal data storage
  Default
  28
- notifications ApiKeyNotifications
  - emails string[]
    A list of email addresses designated by you to receive notifications about this key.
  - enabled boolean
    Indicates whether email notifications are enabled.
  - balance_threshold integer
    Balance threshold that triggers a reminder email. null means disabled.
    Format
    int32
    Example
    500
  - no_balance boolean
    Send notice when balance hits zero.
  - limit_reached boolean
    Send notice when rate limit is reached.
- datasets ApiKeyDatasets
  Indicates which datasets are available and added by default to the address responses
  - paf boolean
    UK Main Address File (Postcode Address File)
    Example
    true
  - pafa boolean
    UK Property Alias dataset
    Example
    false
  - pafw boolean
    UK Welsh Language Dataset
    Example
    false
  - mr boolean
    UK Multiple Residence Dataset
    Example
    true
  - nyb boolean
    UK Not Yet Built Dataset
    Example
    false
  - ab boolean
    UK AddressBase dataset
    Example
    false
  - abp boolean optional
    UK AddressBase Premium dataset
    Example
    false
  - nip boolean
    Northern Ireland Pointer Dataset
    Example
    false
  - usps boolean
    US Address Dataset
    Example
    true
  - ecad boolean
    Republic of Ireland: Eircode Address Database
    Example
    false
  - ecaf boolean
    Republic of Ireland: Eircode Address File
    Example
    false
  - gnaf boolean
    Australia: Geocoded National Address File
    Example
    true
  - hereap boolean
    Asia Pacific Address File
    Example
    true
  - herehk boolean
    Hong Kong Address File
    Example
    true
  - herei boolean
    India Address File
    Example
    true
  - herem boolean
    Macau Address File
    Example
    true
  - heremea boolean
    Middle East and Africa Address File
    Example
    true
  - heremeas boolean
    Middle East and Africa Standalone Intermediate Maps Address File
    Example
    true
  - herena boolean
    North America Address File
    Example
    true
  - hereo boolean
    Oceania Address File
    Example
    true
  - heresa boolean
    South America Address File
    Example
    true
  - heret boolean
    Taiwan Address File
    Example
    true
  - hereee boolean
    Eastern Europe Address File
    Example
    true
  - herewe boolean
    Western Europe Address File
    Example
    true
  - phone boolean
    Phone validation is enabled
    Example
    true
  - email boolean
    Email validation is enabled
    Example
    true
  - kadaster boolean
    Netherlands: Kadaster BAG 2.0 Address File
  - kartverket boolean
    Norway: Kartverket Address File
    Example
    true
  - mois boolean
    South Korea: MOIS Address File
    Example
    true
  - sdfi boolean
    Denmark: Danmarks Adresseregister (DAR)
    Example
    true
  - cannar boolean
    Canada: Statistics Canada National Address Register
    Example
    true
  - fodbosa boolean
    Belgium: FOD BOSA Address File
    Example
    true
  - upujp boolean
    Japan: UPU Address File
    Example
    true
  - bev boolean
    Austria: BEV Address File
    Example
    true
  - ban boolean
    France: BAN (Base Adresse Nationale)
    Example
    true
  - swt boolean
    Switzerland and Liechtenstein: Swisstopo Address File
    Example
    true
  - gbrcleanse boolean
    UK GBR Cleanse
    Example
    true
  - uspscleanse boolean
    US CASS Cleanse
    Example
    true
- automated_topups ApiKeyAutomatedTopup
  Automated topup status
  - enabled boolean
    Indicates whether automated top-ups are enabled
    Example
    true
- current_purchases object[]
  Current balance purchases attached to key.
  - expires string
    string or null The date when this purchase will expire in simplified extended ISO format (ISO 8601). This is typically 365 days from the time of first use. This field will be null if the purchase has not yet been used.
    Example
    2022-01-06T11:41:27.092Z
  - purchased integer
    Number of procured lookups from this purchase.
    Format
    int32
    Example
    20000
  - consumed integer
    Number of consumed lookups off this purchase.
    Format
    int32
    Example
    121
- ip_forwarding boolean
  Accept IP addresses forwarded in the AZ-Source-IP header
  Default
  false
- premier_support boolean
  Whether the key is enrolled in the premier support programme and monitored closely by our devops team. Read-only; managed by our team.
  Default
  false

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

Request

curl
JavaScript
Python
Ruby
PHP

curl -X PUT 'https://api.addresszen.com/v1/keys/ak_test/details?user_token=uk_secret' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "My Updated Key",
    "daily_limit": 1000,
    "notifications": {
      "enabled": true
    }
  }'

const response = await fetch('https://api.addresszen.com/v1/keys/ak_test/details?user_token=uk_secret', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'My Updated Key',
    daily_limit: 1000,
    notifications: {
      enabled: true,
    },
  }),
});

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

import requests

response = requests.put(
    "https://api.addresszen.com/v1/keys/ak_test/details",
    params={"user_token": "uk_secret"},
    json={
        "name": "My Updated Key",
        "daily_limit": 1000,
        "notifications": {
            "enabled": True,
        },
    },
)
result = response.json()["result"]

require "net/http"
require "json"

uri = URI("https://api.addresszen.com/v1/keys/ak_test/details?user_token=uk_secret")
body = {
  name: "My Updated Key",
  daily_limit: 1000,
  notifications: {
    enabled: true,
  },
}
response = Net::HTTP.put(uri, body.to_json, "Content-Type" => "application/json")
result = JSON.parse(response.body)["result"]

<?php
$ch = curl_init("https://api.addresszen.com/v1/keys/ak_test/details?user_token=uk_secret");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode([
    "name" => "My Updated Key",
    "daily_limit" => 1000,
    "notifications" => [
      "enabled" => true,
    ],
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true)["result"];

Body

{
  "name": "My API Key",
  "daily_limit": {
    "limit": 1000
  },
  "monthly_limit": {
    "limit": 10000
  },
  "individual_limit": {
    "limit": 30
  },
  "allowed_urls": [
    ""
  ],
  "redact_days": 28,
  "notifications": {
    "emails": [
      "person@example.com"
    ],
    "enabled": true,
    "balance_threshold": 500,
    "no_balance": true,
    "limit_reached": true
  },
  "ip_forwarding": false,
  "datasets": {
    "pafa": false,
    "pafw": false,
    "usps": true,
    "hereap": true,
    "herehk": true,
    "herei": true,
    "herem": true,
    "heremea": true,
    "heremeas": true,
    "herena": true,
    "hereo": true,
    "heresa": true,
    "heret": true,
    "hereee": true,
    "herewe": true,
    "phone": true,
    "email": true,
    "gnaf": true,
    "kadaster": true,
    "kartverket": true,
    "sdfi": true,
    "cannar": true,
    "fodbosa": true,
    "mois": true,
    "upujp": true,
    "bev": true,
    "ban": true,
    "swt": true,
    "ab": false,
    "abp": false,
    "nip": false,
    "gbrcleanse": true,
    "uspscleanse": true
  }
}

Response

200 OK
400 Bad Request
401 Unauthorised

{
  "result": {
    "name": "My API Key",
    "contexts": [
      {
        "iso_3": "USA",
        "iso_2": "US",
        "description": "United States",
        "emoji": "🇺🇸",
        "rgeo": true
      }
    ],
    "lookups_remaining": 19889,
    "daily_limit": {
      "limit": 1000,
      "consumed": 288
    },
    "monthly_limit": {
      "limit": 10000,
      "consumed": 2500
    },
    "individual_limit": {
      "limit": 30
    },
    "allowed_urls": [
      ""
    ],
    "redact_days": 28,
    "notifications": {
      "emails": [
        "person@example.com"
      ],
      "enabled": true,
      "balance_threshold": 500,
      "no_balance": true,
      "limit_reached": true
    },
    "datasets": {
      "paf": true,
      "pafa": false,
      "pafw": false,
      "mr": true,
      "nyb": false,
      "ab": false,
      "abp": false,
      "nip": false,
      "usps": true,
      "ecad": false,
      "ecaf": false,
      "gnaf": true,
      "hereap": true,
      "herehk": true,
      "herei": true,
      "herem": true,
      "heremea": true,
      "heremeas": true,
      "herena": true,
      "hereo": true,
      "heresa": true,
      "heret": true,
      "hereee": true,
      "herewe": true,
      "phone": true,
      "email": true,
      "kadaster": true,
      "kartverket": true,
      "mois": true,
      "sdfi": true,
      "cannar": true,
      "fodbosa": true,
      "upujp": true,
      "bev": true,
      "ban": true,
      "swt": true,
      "gbrcleanse": true,
      "uspscleanse": true
    },
    "automated_topups": {
      "enabled": true
    },
    "current_purchases": [
      {
        "expires": "2022-01-06T11:41:27.092Z",
        "purchased": 20000,
        "consumed": 121
      }
    ],
    "ip_forwarding": false,
    "premier_support": false
  },
  "code": 2000,
  "message": "Success"
}

response.json
{
  "code": 4000,
  "message": "Invalid request"
}

response.json
{
  "code": 4010,
  "message": "Invalid token"
}

Path parameters​

Query parameters​

Request body​

Response​

Path parameters

Query parameters

Request body

Response