Developer API Guide

Complete REST API documentation for integrating eSortcode bank validation services into your application

Contents

API Overview

The eSortcode API enables high-speed validation for UK and Irish bank and sort codes. All endpoints require an API key and use the base URL:

https://wsp.esortcode.com/uk/v1/

Available Endpoints

  • GET /ValidateAccount: Modulus check validation of a sort code and account number. Returns result of modulus check and all bank branches associated with the verified data.
  • GET /COP: Confirmation of Payee - real-time name verification for recipients.
  • GET /PNV: Payer Name Verification - real-time name verification for payers.
  • GET /GetCredits: Check remaining API credits.
Need Help?
If you have any questions please email support@esortcode.com for further assistance.

Quick Start

Important - Master Keys vs API Keys:

The master key issued to you is for managing available credits and account administration only. It is not used for consuming the web services themselves.

You must create API keys securely within your portal's Manage API Keys tab to enable you to utilize the publicly available web services. API keys can be configured with security restrictions (IP/domain whitelisting and rate limiting) to protect your account.

1

Create/Manage Your API Key

Create or manage your API key in the Manage API Keys tab of your eSortcode Portal.

2

Make a Request

curl -X GET "https://wsp.esortcode.com/uk/v1/validateaccount?key=your_api_key&sortcode=000000&accountNumber=00110022"
3

Interpret the Response

The response contains the modulus check result and associated bank branches in JSON format.

Securing Your API Endpoint

For additional security, especially when using client-side scripting, it is recommended that you configure access restrictions for your API key to prevent unauthorized usage.

Important: Client-side JavaScript exposes your API key in the browser. Always use IP/domain restrictions and rate limiting to protect your account from unauthorized access.

IP Address & Domain Restrictions

You can specify authorized IP addresses or fully qualified domain names (FQDN) that are permitted to make requests using your API key. This ensures access to your services is restricted to only the entries you specify.

Configuration Options

Single IP Address:
203.0.113.10

Multiple IP Addresses:
203.0.113.10, 203.0.113.20, 198.51.100.5

Domain Names:
www.example.com, api.example.com

Mixed IP and Domain:
203.0.113.10, www.example.com, api.example.com

Wildcard (Allow All):
*
Note: You can enter multiple domains or IP addresses for each API key by using comma delimitation (e.g., 1.1.1.1, 2.2.2.2). You can also use an asterisk (*) as a wildcard to enable access from any client address.

Rate Limiting

In addition to IP/domain restrictions, you can specify the maximum number of requests allowed from any client endpoint address within a 1-hour timeframe.

Default Configuration

Max Requests per Hour: 5
Per Client IP: Yes
Window: Rolling 60 minutes

Custom Configuration

Available Options:
5, 10, 50, 100, 500, 1000, Unlimited

Recommended for Production:
100-1000 (based on expected load)

Security Best Practices

  • Never expose API keys in public repositories: Use environment variables or secure credential storage.
  • Use server-side integration when possible: Keep API keys on your backend servers, not in client-side code.
  • Enable IP/domain restrictions: Especially important for client-side implementations.
  • Set appropriate rate limits: Start conservative (e.g., 100/hour) and increase as needed.
  • Monitor API usage regularly: Check for unusual patterns in the eSortcode Portal.
  • Rotate API keys periodically: Generate new keys and deprecate old ones on a regular schedule.
  • Use separate keys per environment: Different keys for development, staging, and production.

How to Configure

1

Access API Key Management

Log in to the eSortcode Portal and navigate to the Manage API Keys tab.

2

Configure IP/Domain Restrictions

Enter authorized IP addresses or domain names, separated by commas. Use * to allow all (not recommended for production).

3

Set Rate Limits

Configure the maximum requests per hour per client IP. Default is 5, adjust based on your application needs.

4

Test Your Configuration

Make test requests from authorized and unauthorized sources to verify restrictions are working correctly.

Enterprise Security: Enterprise SLA customers receive dedicated API endpoints with additional security features. Learn more

GET /ValidateAccount

Performs modulus check validation for UK and Irish bank and sort codes.

Testing: You can receive a test response from this endpoint by passing 000000 as the bank sort code.

Parameters

Name Type Required Description
key String Yes Your API key.
sortcode String Yes The bank sortcode (e.g., "82-22-20" or "822220").
accountNumber String Yes The bank account number (e.g., "00110022").

Responses

200 OK

Returns the result of the modulus check and a list of associated bank branches.

400 Bad Request

The sortcode and account number do not exist.

403 Forbidden

See Service-Wide Errors.

Response Fields

Field Type Description
modulusCheck Object The modulus check result with associated sortcode and account number.
branches[] Array List of branches associated with the bank sort code.

Example Request

https://wsp.esortcode.com/uk/v1/validateaccount?key=your_api_key&sortcode=000000&accountNumber=00110022

Example 200 Response

{
    "modulusCheck": {
        "sortcode": "000000",
        "accountNumber": "00110022",
        "valid": true
    },
    "branches": [
        {
            "bankName": "ROYAL BANK OF SCOT",
            "branchTitle": "GREENOCK CATHCART STREET",
            "address1": "Cartsdyke Avenue",
            "address2": "Cartsburn East",
            "address3": "",
            "town": "Greenock",
            "county": "",
            "postcode": "PA15 1EF",
            "bacsPayments": true,
            "directDebits": true,
            "directCredits": true,
            "claimsForUnpaidCheques": true,
            "buildingSocietyCredits": true,
            "dividendInterestPayments": true,
            "auddisDirectDebitInstructions": true
        }
    ]
}

Example 400 Response

{
    "message": "No match found for sortcode or account number"
}

GET /COP and /PNV

Requires: ConfirmationOfPayee licence type. You can purchase credits for this licence type in your portal. For further details or assistance please call us.

These endpoints provide real-time name verification against UK bank accounts using Confirmation of Payee or Payer Name Verification.

  • /COP performs Confirmation of Payee (verifies the recipient/payee name matches the account before sending a payment, e.g. Faster Payments or CHAPS).
  • /PNV performs Payer Name Verification (verifies the payer name, typically used before setting up or amending Bacs Direct Debits).

Both endpoints combine the name match result with standard modulus validation and branch details in a single response.

Parameters

Name Type Required Description
key String Yes Your API key.
sortcode String Yes 6-digit sort code (without hyphens, e.g. "404784").
accountNumber String Yes 8-digit account number.
name String Yes The payee's account name. For increased accuracy, provide the correct payee name as held at the receiving institution. We recommend obtaining first name(s) and last name(s) separately for personal accounts. Each name element must be separated by a space. Do not include titles or honorifics. Supports UTF-8 encoding. URL-encode spaces/special characters.
accountType String Yes The type of account (either PERSONAL or BUSINESS).
secondaryAccountId String No Additional data, such as a Building Society Roll Number or Credit Card number. Must be provided if requested by the receiving Payment Service Provider.
testOutcome String No To test scenarios, provide the desired result (e.g., "CLOSE_MATCH"). Test outcome requests do not deduct credits.

CoP/PNV Response Codes

Code Description
MATCHED The account name and account type exactly match the provided details. Action: Safe to proceed with creating the Direct Debit Instruction (DDI).
NOT_MATCHED The account name and/or account type do not match. Action: Do not proceed. Ask the payer to check and correct the details.
CLOSE_MATCH The provided name is similar (but not identical) to the actual account name. Correct name returned in result.name. Action: Update the DDI with the returned name or ask the payer to amend the details.
BUSINESS_ACCOUNT_NAME_MATCHED The account name matches, but the account is a business account (while a personal account was expected). Action: Confirm with the payer before proceeding.
PERSONAL_ACCOUNT_NAME_MATCHED The account name matches, but the account is a personal account (while a business account was expected). Action: Confirm with the payer before proceeding.
BUSINESS_ACCOUNT_CLOSE_MATCH The provided name is similar and the account is a business account (expected personal). Action: Update DDI with returned name or ask payer to correct.
PERSONAL_ACCOUNT_CLOSE_MATCH The provided name is similar and the account is a personal account (expected business). Action: Confirm with payer, update to actual name, then proceed.
ACCOUNT_DOES_NOT_EXIST The account does not exist at the paying bank. Action: Do not proceed – this will result in a Bank Rejected AUDDIS advice.
ACCOUNT_NOT_SUPPORTED The account/bank does not support account name check requests. Action: Verify details carefully (consider using Open Banking AIS).
ACCOUNT_SWITCHED The account has been switched using CASS. Action: Ask the payer for the new account details.
WRONG_PARTICIPANT The account name check cannot be completed. Action: Check details carefully (consider Open Banking AIS).
NO_RESPONSE The bank did not respond to the account name check request. Action: Try again later.
NOT_ENROLLED The bank does not participate in account name check requests. Action: Verify details carefully (consider Open Banking AIS).
SECONDARY_ACCOUNT_ID_NOT_FOUND The provided secondaryAccountId is not valid. Action: Check account details and submit a new name check request.

Responses

200 OK

Successful check. Returns the CoP/PNV outcome plus modulus and branch info.

400 Bad Request

Invalid parameters, unsupported test outcome.

403 Forbidden

Invalid key, insufficient credits, rate limit exceeded. See Service-Wide Errors.

Response Fields (200 OK)

Field Type Description
cop Object The name verification outcome.
modulusCheck Object Standard modulus validation result (same as /ValidateAccount).
branches[] Array Branch details (same format as /ValidateAccount).

Example Requests

https://wsp.esortcode.com/uk/v1/cop?key=your_api_key&sortcode=000000&accountNumber=00110022&name=Joe%20Bloggs&accountType=PERSONAL

https://wsp.esortcode.com/uk/v1/pnv?key=your_api_key&sortcode=000000&accountNumber=00110022&name=Joe%20Bloggs&accountType=PERSONAL

Example 200 Response

{
  "cop": {
    "code": "MATCHED",
    "name": "",
    "description": "The account name and account type match the name and account type provided.",
    "advice": "You can proceed with the creation of the Direct Debit Instruction."
  },
  "modulusCheck": {
    "sortcode": "000000",
    "accountNumber": "00110022",
    "valid": false
  },
  "branches": [
    {
      "bankName": "SERVICE TEST BRANCH",
      "branchTitle": "CITY CENTRE",
      "address1": "1 Main Street",
      "address2": "Area West",
      "address3": "",
      "town": "Old Town",
      "county": "",
      "postcode": "ST0 1XX",
      "bacsPayments": false,
      "directDebits": false,
      "directCredits": false,
      "claimsForUnpaidCheques": false,
      "buildingSocietyCredits": false,
      "dividendInterestPayments": false,
      "auddisDirectDebitInstructions": false
    }
  ]
}

GET /GetCredits

Retrieves the number of remaining API credits for the provided API key.

Parameters

Name Type Required Description
key String Yes Your API key.

Responses

200 OK

Returns the number of remaining credits.

403 Forbidden

See Service-Wide Errors.

Example Request

https://wsp.esortcode.com/uk/v1/getcredits?key=your_api_key

Example Response

{
    "credits": 29
}

Service-Wide Errors

The following errors may apply to any endpoint due to security or credit checks:

403 Forbidden

Invalid API Key

{
    "message": "Request from {client} denied: InvalidApiKey"
}

Unauthorized Domain

{
    "message": "Request from {client} denied: UnauthorisedDomain"
}

Zero Credits

{
    "message": "Request from {client} denied: ZeroCredits"
}

Requests Throttled

{
    "message": "Maximum {allowed} requests per {interval} seconds have been served for {client}."
}

Licence does not support this request

{
    "message": "The license assigned to the supplied key does not support {type} requests."
}

Versioning

This documentation covers eSortcode REST API v1 (base URL: https://wsp.esortcode.com/uk/v1/).

Changelog

  • January 2026: Added /COP and /PNV endpoints.

Ready to Get Started?

Sign up for a free account and get instant access to the API with 50 free credits.

Create Free Account Access Portal