SOAP API guide

Overview

The ePostcode SOAP API exposes UK address lookup and validation over a classic SOAP/XML interface. It is ideal where your stack already expects WSDL-generated clients or long-running enterprise integrations.

When to use SOAP

• Enterprise / legacy stacks - .NET Framework, Java EE, older middleware and ESBs that generate clients from WSDL.
• Contract-first tooling - Visual Studio service references, wsimport, SoapUI and similar.
• XML pipelines - environments standardised on SOAP envelopes and XML transforms.

WSDL integration

Point your tooling at the live WSDL to generate strongly typed client proxies. Most platforms only need the URL below.

Quick start by platform

1. .NET - Add Service Reference, paste the WSDL URL, generate proxy classes in Visual Studio.
2. Java - Run wsimport against the WSDL to create client stubs.
3. PHP - Create SoapClient($wsdl) and call operations by name.
4. Python - Use zeep (or similar) with the WSDL for typed bindings.

Authentication

Authenticate with the API key issued in the ePostcode portal. Pass it as an operation parameter (commonly ApiKey) on each call.

• Create or rotate keys in the portal.
• Never embed keys in public client-side pages; call SOAP from your server or trusted backend.
• Usage is credit-based - the same credit packs as REST and other ePostcode products.

Common operations

Core operations for lookup, detail retrieval, validation and account balance. Exact signatures are defined in the WSDL.

Request & response examples

Illustrative SOAP 1.1 envelopes for a postcode lookup. Field names should match your generated client and the current WSDL.

SOAP request (PostcodeLookup)

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <PostcodeLookup xmlns="http://ws.epostcode.com/">
      <ApiKey>YOUR_API_KEY_HERE</ApiKey>
      <Postcode>SW1A 1AA</Postcode>
    </PostcodeLookup>
  </soap:Body>
</soap:Envelope>

SOAP response

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <PostcodeLookupResponse xmlns="http://ws.epostcode.com/">
      <PostcodeLookupResult>
        <Address>
          <BuildingNumber>10</BuildingNumber>
          <Street>Downing Street</Street>
          <Locality>Westminster</Locality>
          <Town>London</Town>
          <County>Greater London</County>
          <Postcode>SW1A 2AA</Postcode>
          <Latitude>51.503396</Latitude>
          <Longitude>-0.127764</Longitude>
        </Address>
      </PostcodeLookupResult>
    </PostcodeLookupResponse>
  </soap:Body>
</soap:Envelope>

.NET C# example

Use Visual Studio service references to generate proxy classes from the WSDL, then call operations asynchronously.

1. Add a service reference

1. Right-click the project → Add → Service Reference.
2. Enter https://ws.epostcode.com/uk/postcodeservices19.asmx?WSDL and click Go.
3. Choose a namespace (for example PostcodeServiceReference) and click OK.

2. Call the service

// Add Service Reference to:
// https://ws.epostcode.com/uk/postcodeservices19.asmx?WSDL

using PostcodeServiceReference;

var client = new PostcodeServices19SoapClient();
var result = await client.PostcodeLookupAsync("YOUR_API_KEY", "SW1A 1AA");

foreach (var address in result.Addresses)
{
    Console.WriteLine($"{address.BuildingNumber} {address.Street}");
    Console.WriteLine($"{address.Town}, {address.Postcode}");
}

PHP example

PHP’s built-in SoapClient can consume the WSDL with minimal setup.

<?php
$wsdl = "https://ws.epostcode.com/uk/postcodeservices19.asmx?WSDL";
$client = new SoapClient($wsdl);

$params = array(
    'ApiKey' => 'YOUR_API_KEY_HERE',
    'Postcode' => 'SW1A 1AA'
);

try {
    $result = $client->PostcodeLookup($params);

    foreach ($result->PostcodeLookupResult->Address as $address) {
        echo $address->BuildingNumber . " " . $address->Street . "\n";
        echo $address->Town . ", " . $address->Postcode . "\n";
    }
} catch (SoapFault $e) {
    echo "Error: " . $e->getMessage();
}
?>

Java example

Generate stubs with wsimport, then call the generated service port.

1. Generate client stubs

wsimport -keep -verbose https://ws.epostcode.com/uk/postcodeservices19.asmx?WSDL

2. Use the generated classes

import com.epostcode.ws.*;

public class PostcodeLookupExample {
    public static void main(String[] args) {
        try {
            PostcodeServices19 service = new PostcodeServices19();
            PostcodeServices19Soap port = service.getPostcodeServices19Soap();

            String apiKey = "YOUR_API_KEY_HERE";
            String postcode = "SW1A 1AA";

            PostcodeLookupResponse response = port.postcodeLookup(apiKey, postcode);

            for (Address address : response.getAddresses()) {
                System.out.println(address.getBuildingNumber() + " " + address.getStreet());
                System.out.println(address.getTown() + ", " + address.getPostcode());
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Errors & SOAP faults

Failed calls typically return a SOAP fault. Surface the fault code and string in logs so support can diagnose quickly.

• Invalid API key - check portal keys, IP restrictions and that the key is active.
• Insufficient credits - top up in the portal or enable auto-renewal.
• Bad request data - validate postcode formatting and required fields before calling.
• Transport errors - timeouts and TLS issues are client/network side; retry with backoff where appropriate.