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

1

Get an API Key

Setup your API key in the Manage Keys area 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.

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