Quick start guide for using Postcoder

1. Get an API key

Sign up for a free trial and you'll receive an API key with 300 trial credits for testing. No payment details required - and you can request more trial credits if you need them.

2. Make your first API call

Your API key follows this format: PCW45-12345-12345-1234X

Address autocomplete shows real-time suggestions as a user starts typing their address. Here's a simple request using the autocomplete/find endpoint, searching for "123 foxglove":

You should get a JSON response like this:

[
    {
        "id": "20463404",
        "type": "ADD",
        "summaryline": "123 Foxglove Road, South Ockendon, Essex, RM15 6EU",
        "count": 1
    },
    {
        "id": "20544890",
        "type": "ADD",
        "summaryline": "123 Foxglove Road, Sheffield, South Yorkshire, S5 6FP",
        "count": 1
    },
  	...
  	...
]

Each suggestion includes a unique ID, a summary and a type - which tells you what to do next:

• Type: ADD - this is an address. Pass the ID to the autocomplete/retrieve endpoint to get the full address details (number, street, town, postcode, etc.)
• Any other type - this is a broader location such as a street. Pass the ID back to the autocomplete/find endpoint via the pathfilter querystring parameter to let the user drill down into it

That's it - you're making live API calls.

3. Choose your integration path

Pick the feature you want to integrate:

Address lookup

A popular way to integrate address lookup is using address autocomplete - real-time suggestions as users type. If you prefer a single-step lookup - where a user types a postcode or address fragment and hits a search button - that's also supported.

• Integrations setup guide

  Step-by-step guide for adding address autocomplete to any website or form builder (WordPress, Wix, Gravity Forms, etc.). View integrations setup guide ➜

• Sample code

  JavaScript, Python, PHP and C# examples, plus live CodePen demos. View sample code ➜

• API reference

  Full endpoint documentation. View API reference ➜

Bank validation

Verify UK sort codes and account numbers in real time.

• Sample code

  JavaScript, Python, PHP and C# examples, plus live CodePen demos. View sample code ➜

• API reference

  Full endpoint documentation. View API reference ➜

Email validation

Check whether email addresses can receive emails.

• Sample code

  JavaScript, Python, PHP and C# examples, plus live CodePen demos. View sample code ➜

• API reference

  Full endpoint documentation View API reference ➜

Mobile validation

Check whether mobile phone numbers can receive calls and texts.

• Sample code

  JavaScript, Python, PHP and C# examples, plus live CodePen demos. View sample code ➜

• API reference

  Full endpoint documentation View API reference ➜

OTP verification

Send and verify one-time passwords via SMS.

• Sample code

  Python, PHP and C# examples. View sample code ➜

• API reference

  Full endpoint documentation View API reference ➜

4. Test your integration

Use your trial credits to test your integration end to end. You can monitor usage and check your remaining credits at any time:

If you run low on trial credits, contact us and we'll top you up.

5. Review security and alert settings

Before deploying to production, review the API key security guidance and update your settings. You can configure:

• Rate limits: Limit requests to protect your credits
• Trusted IP addresses: For server-side integrations, lock your API key to trusted IP addresses
• Trusted website URLs: For client-side integrations, restrict your API key to trusted website URLs

You can also enable email alerts to help you monitor your account. These include:

• Low credit alerts: Choose when to be notified about low credits
• Credit expiry alerts: Set reminders before your credits expire
• Usage alerts: Get notified about high or zero usage
• Security alerts: Get notified when requests are being rate-limited

We recommend sending alerts to multiple people or a group distribution list so they never depend on one person.

6. Buy credits and go live

To go live, simply buy a credit pack or set up a monthly plan. Prices start from £27 and there are no subscription commitments for credit packs.

Troubleshooting

Getting a 403 error? The most common cause during testing is hitting the default rate limit (5 requests per IP address per 5 minutes). See Resolve 403 errors for how to fix this.

Getting a 400 error? Check that all required parameters are present and correctly formatted. See the relevant API reference for parameter details.

For anything else, visit the Troubleshooting page or contact us.