Skip to main content

API Key Settings

You can limit your API Key usage via the Security panel on your dashboard. This is important when you want to control how many lookups you spend per day.

Setting the Right Restrictions​

There are two approaches to using your API Key within your project. Your Key can either be:

  • Private. Lookups are generated from a controlled environment, such as a server belonging to you
  • Public. Lookups are generated from a client (e.g. browser or app), which means embedding the Key on the client side

In both scenarios, we strongly recommend you to set both a daily and individual limit on lookups.

If you will be making requests from within your client's browser, we strongly recommend you create a list of "Allowed URLs" from which you can make requests.

API Key Controls​

The following controls are provided to limit how your API Key can be used:

Daily Lookup Limits​

A limit on the number of lookups your API Key can make per day

  • This limits the number of postcode lookups on your API Key per day. The limit is reset on midnight.
  • This is ideal for controlling the amount you wish to spend on lookups per day.

Your email notification recipients will be notified when you reach 90% or 100% of this cap.

Individual Lookup Limits​

A limit on the number of lookups an individual user can make on your API Key per day.

  • This limits the number of daily requests from an specific IP address. The limit is reset on each IP Address on midnight.
  • This is ideal if you intend on embedding your Key on client side code.

IP Address Forwarding​

Forward the IP address to be whitelisted for paid API requests.

When the Daily Individual Lookup Limit is enabled, you may also opt to enable IP Address Forwarding. This will limit requests based on the IP address you provide using a HTTP request header named IDPC-Source-IP. If an address is successfully forwarded, your API response will also contain a IDPC-Source-IP header relaying the rate limited IP address.

Malformed IP addresses passed with the IDPC-Source-IP header will return a 400 response.

IP Address Forwarding should be enabled for integrations that require IP based daily limiting, but API requests are proxied through a small number of privately controlled hosts. Without IP Address Forwarding, the IP addresses associated with the proxies themselves will be rate limited rather than the end user.

If IP Address Forwarding is enabled but no IDPC-Source-IP header is provided, the original IP address will be limited as usual.

IP Address Forwarding should not be enabled for client side integrations as this would allow daily rate limiting to be circumvented.

Allowed URLs​

A list of web addresses that can perform lookups using your API Key.

  • This list determines the URLs that are allowed to perform lookups on your API Key, e.g. example.com or example.com/users/signup.
  • This is ideal if you intend on embedding your Key on client side code.

Enabling Allowed URLs will also enable CORS.

Allowed strings beginning with http:// or https:// will look for matches that start with the string. For instance, https://www.example.com will match https://www.example.com/ as well as https://www.example.com/signup.

Allowed strings which do not begin with http[s]:// will look for positive substring matches. For instance, .example.com/signup will match https://www.example.com/signup, including https://app.example.com/signup.

We strongly recommend restricting by domain and protocal only (e.g. https://www.example.com). Browsers are becoming are deploying increasingly strict defaults when it comes to returning path information on the referer header.

API Key Regeneration​

You can also generate a new Key through API Key Settings. This will not affect your existing purchases. Requests made on your old Key will fail. Please note this is not reversible.

Retention Period (Days)​

Your transaction logs will contain some personal information detailed in our data processing section.

We will periodically redact any logs (older than your retention period) of personal data. This includes IP address, address query and URL referer headers.

By default, this retention period is set at 28 days. You may also set the retention period to 0 if you wish to disable retention of any personal data.

For an overview of personal data we capture and process, please see our data processing guide. The details can be found in our Terms of Service.