Quick Start Guide

Get up and running with our APIs in minutes. This guide will walk you through creating an API token, setting up authentication, and making your first postcode lookup request.

What You'll Learn

Create API Token

Generate your authentication credentials

Setup Authentication

Configure secure API access

Lookup Addresses

Retrieve postcode and address data

1
Create Your API Token

Before you can access our APIs, you'll need to create an API token. This token acts as your digital key and proves your identity when making requests.

1

Navigate to Token Management

Go to your dashboard and access the token management section to create a new API token.

Create API Token
2

Generate Your Token

Click "Create New Token", provide a descriptive name, and copy the generated token. Store this securely - you won't be able to see it again!

Security Important

Treat your API token like a password. Store it securely and never share it publicly. For production applications, consider using environment variables.

Need more details about token management?View the complete Security API documentation →

2
Setup Authentication

Now that you have an API token, you'll need to include it in your requests. Our API's use Bearer token authentication for secure API access.

1

Add Authorization Header

Include your API token in the Authorization header of every request:

Authorization: Bearer your-api-token-here
2

Example with cURL

Here's how to make an authenticated request using cURL:

curl
-H "Authorization: Bearer your-api-token-here"
-H "Content-Type: application/json"
"https://api.findableplus.com/postcode/lookup/v1/royal-mail?postcode=SW1A 1AA"
3

Example with JavaScript

And here's the same request using JavaScript fetch:

const response = await fetch(
'https://api.findableplus.com/postcode/lookup/v1/royal-mail?postcode=SW1A 1AA',
{
headers: {
'Authorization': 'Bearer your-api-token-here',
'Content-Type': 'application/json'
}
}
);

Best Practice: Short-lived Tokens

For enhanced security, consider generating short-lived JWT tokens using the Security API instead of using your main dashboard token directly in production applications.

Learn about short-lived tokens and advanced authentication patterns in ourSecurity API documentation →

3
Lookup Postcode Data

Now you're ready to make your first postcode lookup! Our API provides fast and accurate UK address data with optional coordinate information.

1

Choose Your Dataset

Select your dataset based on your accuracy, desired coverage, and cost requirements:

royal-mail

Official, comprehensive dataset with highest accuracy

2

Make Your First Request

Here's a complete example using the royal-mail dataset to lookup postcode "SW1A 1AA":

curl
-H "Authorization: Bearer your-api-token-here"
-H "Content-Type: application/json"
"https://api.findableplus.com/postcode/lookup/v1/royal-mail?postcode=SW1A 1AA"
3

Understanding the Response

The API returns structured address data with all matching addresses for the postcode:

{
"status": "OK",
"matchedItems": [
{
"address": "Buckingham Palace, London, SW1A 1AA",
"formattedLines": [
"Buckingham Palace"
],
"organisation": "Buckingham Palace",
"town": "London",
"postcode": "SW1A 1AA"
}
]
}
4

Optional: Add Coordinate Data

Include latitude/longitude and grid reference data for mapping applications. You can request both fields together or individually:

// Request both coordinate fields
?postcode=SW1A 1AA&data=onspd_coordinates,onspd_gridreference
// Or request just coordinates
?postcode=SW1A 1AA&data=onspd_coordinates
// Or request just grid reference
?postcode=SW1A 1AA&data=onspd_gridreference

Congratulations!

You've successfully made your first postcode lookup! You can now integrate this into your application to provide address capture, validation, and location services.

Explore advanced features like accessing extra data in ourcomplete Postcode Lookup API documentation →

Next Steps

Security API

Learn about authentication and obtaining JWT tokens for API access.

Postcode Lookup API

Explore the UK postcode lookup service with comprehensive address data.

Purchase Credits

Choose a credit pack that suits your API usage needs.