SOAP API Overview

XML-based web service for enterprise and legacy systems. Full WSDL support for automatic code generation.

Legacy Service: The SOAP API is maintained for backward compatibility. We recommend new integrations use the REST API for better performance and easier integration.
WSDL URL: https://ws.epostcode.com/uk/postcodeservices19.asmx?WSDL

Key Features

  • WSDL Support: Automatic client code generation
  • Enterprise Ready: Compatible with legacy systems
  • XML Responses: Standard SOAP envelope format
  • Comprehensive Operations: Full address lookup and validation
  • Wide Platform Support: .NET, Java, PHP, Python, and more

WSDL Integration

The SOAP API uses WSDL (Web Services Description Language) for service definition. Most enterprise development tools can automatically generate client code from the WSDL.

WSDL Endpoint: https://ws.epostcode.com/uk/postcodeservices19.asmx?WSDL

Quick WSDL Integration Guide

  1. .NET: Add Service Reference → Enter WSDL URL → Visual Studio generates proxy classes
  2. Java: Use wsimport tool to generate client stubs from WSDL
  3. PHP: Use SoapClient class with WSDL URL
  4. Python: Use zeep library for WSDL-based SOAP clients
Full WSDL Documentation: Visit https://ws.epostcode.com/uk/postcodeservices19.asmx for complete WSDL documentation and test console.

Common SOAP Operations

The SOAP API provides several operations for address lookup and validation.

PostcodeLookup

Search for addresses by postcode. Returns a list of all addresses at the specified postcode.

AddressLookup

Search by building name or street. Performs keyword-based address searches.

GetAddressDetails

Retrieve full address details for a specific property using its unique identifier.

ValidateAddress

Validate and standardize addresses against Royal Mail PAF database.

GetCredits

Check remaining API credits for your account.

Request & Response Examples

Example SOAP Request (PostcodeLookup)

SOAP XML Request 
<?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>

Example SOAP Response

SOAP XML 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's "Add Service Reference" to automatically generate proxy classes from the WSDL.

Step 1: Add Service Reference

  1. Right-click on your project → Add → Service Reference
  2. Enter WSDL URL: https://ws.epostcode.com/uk/postcodeservices19.asmx?WSDL
  3. Click Go → Set namespace (e.g., "PostcodeServiceReference")
  4. Click OK to generate proxy classes

Step 2: Use the Service

C# with Service Reference 
// Add Service Reference to: https://ws.epostcode.com/uk/postcodeservices19.asmx

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}");
}
Tip: Visual Studio automatically handles serialization and deserialization when using Service References.

PHP Example

PHP's built-in SoapClient class makes it easy to consume SOAP web services.

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

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

// Call PostcodeLookup operation
try {
    $result = $client->PostcodeLookup($params);
    
    // Process results
    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();
}
?>

Error Handling

Important: Always wrap SOAP calls in try-catch blocks to handle SoapFault exceptions gracefully.

Java Example

Use Java's wsimport tool to generate client stubs from the WSDL.

Step 1: Generate Client Stubs

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

Step 2: Use the Generated Classes

Java Client Code 
import com.epostcode.ws.*;

public class PostcodeLookupExample {
    public static void main(String[] args) {
        try {
            // Create service and port
            PostcodeServices19 service = new PostcodeServices19();
            PostcodeServices19Soap port = service.getPostcodeServices19Soap();
            
            // Call PostcodeLookup operation
            String apiKey = "YOUR_API_KEY_HERE";
            String postcode = "SW1A 1AA";
            
            PostcodeLookupResponse response = port.postcodeLookup(apiKey, postcode);
            
            // Process results
            for (Address address : response.getAddresses()) {
                System.out.println(address.getBuildingNumber() + " " + address.getStreet());
                System.out.println(address.getTown() + ", " + address.getPostcode());
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
Note: The exact package and class names may vary depending on your wsimport configuration.

Need Help with SOAP Integration?

Our technical support team is here to help you integrate ePostcode SOAP API into your application.

Email Support Developer Portal Contact Us