What Is A Lookup and a Credit?

What Is a Lookup and a Credit?

How credits are counted across your API keys.

In short: A lookup is a completed, verified address. Lookups are what you're buying when you purchase credits.

Two ways to look up an address

Ideal Postcodes offers two tools for finding addresses. Each works differently, but both cost the same: 1 credit per lookup.

1. Address Finder (autocomplete)

A user starts typing an address into a form. A dropdown list of matching addresses appears as they type.

How credits work with Address Finder:

• The dropdown suggestions are free. Browsing the list costs nothing

• A credit is only charged when a user selects an address from the list and the full address is returned

• If no address is selected, no credit is used

Note: If you are calling the API directly, the suggestion endpoint must be used with the intention of resolving a full address. Consistently retrieving suggestions without ever selecting an address is a violation of our Terms of Service.

Example: A user types "10 Down" and sees a list of 8 suggestions. They click "10 Downing Street, London, SW1A 2AA." That's 1 credit.

If you're building directly against the API, resolving a full address by UDPRN or UMPRN also counts as 1 credit. See the API documentation for details.

2. Postcode Lookup (enter a postcode, get a list)

A user enters a full postcode. The API returns all addresses at that postcode, and the user picks theirs.

How credits work with Postcode Lookup:

• A credit is charged when the user clicks Find my address and the postcode returns at least one result

• Invalid postcodes (ones that return nothing) are free

• A postcode can return up to 100 addresses for 1 credit

• If you're using the Multiple Residence dataset and a postcode has more than 100 addresses, each additional page of results costs 1 credit

Example: A user enters "BR8 7RE" and clicks Find my address. A list of addresses appears and they pick theirs. That's 1 credit, regardless of how many addresses were in the list.

What is a credit?

A credit is the unit you buy to pay for lookups.

• You buy credits in advance
• Each API key has its own credit balance. Usage on one key doesn't affect another
• When you have multiple credit batches, your oldest credits are used first

When do credits expire?

Royal Mail requires all data suppliers to expire credits within 12 months. Most suppliers start that clock from the date of purchase.

We do things differently, and do everything we can to push expiry dates as far into the future as possible:

• The 12-month timer only starts when you begin using that batch of credits, not when you purchase them. The expiry date can be viewed on the Keys page
• We deduct credits from your earliest purchased balance first, so newer batches stay untouched for longer
• Each batch expires independently. Buying new credits won't affect the expiry of credits you've already purchased

Quick reference

Scenario	Credits used
User selects an address via Address Finder	1
Postcode returns one or more addresses	1
Resolving a full address by UDPRN or UMPRN	1
User browses Address Finder dropdown without selecting	0
Postcode returns no addresses (invalid postcode)	0
Additional page of results: Multiple Residence, 100+ addresses	1 per page

Credits per dataset vary. You can see a full breakdown on each Key's Overview page in your account dashboard.