Skip to content

API Overview

The Eligibility Engine (EE) API provides comprehensive mortgage eligibility assessment and product sourcing capabilities. This guide introduces the API's core concepts and capabilities at a high level.

Introduction

The API is designed to help mortgage intermediaries and technology platforms:

  • Assess Eligibility: Evaluate applicant circumstances against lender lending criteria
  • Source Lenders: Access lender information including branding, URLs, and product offerings
  • Filter Products: Search and filter mortgage products with extensive options

API Basics

  • Base URLs:
    • Staging: https://staging.api.eligibility-engine.com/
    • Production: https://api.eligibility-engine.com/
  • Version: v1 (included in all endpoint paths: /v1/...)
  • Authentication: OAuth 2.0 Bearer tokens (see Authentication guide)
  • Format: JSON for all requests and responses
  • Timeout: 60 seconds for all requests

Detailed Specifications

This overview provides conceptual understanding. For complete endpoint specifications, request/response schemas, and interactive testing, visit the Swagger UI documentation.

Response Format

All API endpoints (except OAuth) return responses in a consistent structure:

{
  "metadata": {
    "timestamp": "2026-01-21 12:00:00",
    "total_count": 42,
    "request_parameters": {
      "offset": 0,
      "limit": 10
    }
  },
  "results": {
    // Actual response data (object or array)
  }
}

Response Fields

  • metadata: Contains request metadata
    • timestamp: When the response was generated
    • total_count: Total number of items available (for paginated responses)
    • request_parameters: Echo of the parameters you sent
  • results: The actual response data (format varies by endpoint)

This consistent structure makes it easy to handle responses across all endpoints.

Core Concepts

The API is organised around three core capabilities:

Criteria Assessment

Evaluate mortgage applications against lender-specific lending criteria to determine eligibility.

What It Does

Criteria assessment allows you to:

  • Submit applicant answers to lending criteria questions
  • Get eligibility results grouped by lender and by criterion
  • Retrieve previously submitted eligibility assessments
  • Access the full catalogue of criteria definitions

Key Concepts

  • Criteria: Lending rules defined by each lender (e.g., minimum income, maximum LTV, credit history requirements)
  • Answers: Your applicant's responses to criteria questions (boolean or numeric values)
  • Eligibility Results: Pass/fail decisions for each criterion and each lender
  • Reference Tracking: Use your own partner_reference to retrieve results later

Typical Workflow

  1. Retrieve the list of the Eligibility Engine's available criteria
  2. Collect applicant answers matching to those criteria
  3. Submit answers to the eligibility endpoint
  4. Receive results showing which lenders the applicant is eligible for
  5. Retrieve results later using your partner reference

Explore Endpoints

See detailed criteria endpoints, request schemas, and examples in Swagger UI under the "Criteria" section.

Lender Information

Access metadata and information about mortgage lenders.

What It Does

Lender endpoints provide:

  • Complete lender directory with names and UUIDs
  • Lender branding (logos) and URLs
  • Criteria answers to the Eligibility Engine's criteria set that define each lender's lending policy
  • Product offerings for specific lenders (with pagination)

Key Concepts

  • Lender Metadata: Basic information including name, logo URL, website
  • Lender UUID: Unique identifier used throughout the API
  • Criteria Answers: The lending criteria and thresholds each lender uses
  • Lender Products: Mortgage products offered by a specific lender

Common Use Cases

  • Display lender logos and branding in your application
  • Link to lender websites for more information
  • Filter products by specific lenders
  • Understand why an applicant was or wasn't eligible for a lender

Explore Endpoints

See detailed lender endpoints and response schemas in Swagger UI under the "Lenders" section.

Product Filtering

Search, filter, and retrieve mortgage product information with comprehensive filtering options.

What It Does

Product endpoints enable you to:

  • Search across all mortgage products
  • Apply extensive filters (LTV, rates, mortgage type, adverse credit, and more)
  • Calculate costs (monthly payments, total cost, APRC) when loan parameters are provided
  • Sort results by rate or initial rate duration
  • Retrieve detailed information for specific products
  • Find related products (those sharing notes)

Key Concepts

  • Product Attributes: Rates, fees, LTV limits, mortgage type, buyer type, repayment method
  • Filtering: 20+ filter options including include/exclude lists for lenders and products
  • Cost Calculations: Automatic calculation of monthly payments and total costs when you provide property_value, loan_amount, and term_years
  • LTV Calculation: Automatically calculated from property value and loan amount
  • Adverse Credit Support: Filter by specific adverse credit criteria (CCJs, defaults, bankruptcy, etc.)
  • Pagination: Control result size with offset and limit

Typical Workflow

  1. Define your search criteria (LTV, mortgage type, rates, etc.)
  2. Submit filter request to the products endpoint
  3. Receive paginated results sorted by your preference
  4. Display product details to users
  5. Optionally retrieve full details for specific products including product notes

Key Filter Categories

Basic Filters:

  • Mortgage purpose (purchase/remortgage)
  • Mortgage type (residential/buy-to-let)
  • Buyer type (first-time/next-time)
  • Mortgage scheme (Help to Buy, Shared Ownership, etc.)

Financial Filters:

  • LTV range (min/max bounds)
  • Initial rate range
  • Rate type (fixed/variable/tracker/discounted)
  • Initial rate duration

Lender Selection:

  • Include/exclude specific lenders by UUID
  • Include/exclude products by UUID
  • Include/exclude by product name keywords

Additional Options:

  • Repayment method (repayment/interest-only/part-and-part)
  • Region (England, Wales, Scotland, etc.)
  • Incentives (cashback, free legals, free valuation)
  • Early repayment charge preferences
  • Adverse credit filtering

Adverse Credit Filtering

Filter products based on specific adverse credit criteria:

  • Arrears: Mortgage/rent arrears acceptance (satisfied/unsatisfied)
  • Bankruptcy: Acceptance and months since resolved
  • CCJs: County Court Judgements (satisfied/unsatisfied)
  • Defaults: Credit defaults (satisfied/unsatisfied)
  • IVA: Individual Voluntary Arrangements and time since resolution
  • Repossessions: Property repossessions and time since occurrence

Explore Endpoints

See detailed product filtering options, all available filters, and cost calculation details in Swagger UI under the "Products" section.

Working with the API

Pagination

Endpoints that return lists of items support pagination:

  • offset: Number of items to skip (default: 0)
  • limit: Maximum items to return (default: 50, max: 100)
  • total_count: Available in metadata to show total items

Error Handling

The API uses standard HTTP status codes:

  • 200 OK: Request succeeded
  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Missing or invalid authentication
  • 403 Forbidden: Valid authentication but insufficient permissions
  • 404 Not Found: Requested resource doesn't exist
  • 500 Internal Server Error: Server-side error
  • 504 Gateway Timeout: Request exceeded 60-second timeout

Error responses include a detail field explaining the issue.

Rate Limits

Currently, there are no enforced rate limits, but we recommend:

  • Caching tokens for their full 1-hour lifetime
  • Implementing reasonable request throttling in your application
  • Batching requests where possible

If you anticipate high-volume usage, please contact us to discuss your requirements.

Request Timeouts

All API requests have a 60-second timeout. If a request takes longer:

  • You'll receive a 504 Gateway Timeout error
  • The request should be retried
  • Consider reducing the scope of your request (e.g., fewer results, simpler filters)

Interactive Documentation

For complete endpoint specifications, request/response schemas, and interactive API testing:

Visit the Swagger UI: api.eligibility-engine.com/docs

The Swagger documentation provides:

  • Complete endpoint reference with all parameters
  • Request and response schema definitions
  • Interactive "Try it out" functionality
  • Example requests and responses
  • Scope-filtered views - only shows endpoints you can access based on your token

Dynamic Documentation

The Swagger UI dynamically shows only the endpoints available for your scopes. After authenticating in Swagger, you'll see exactly which endpoints you can use.

Next Steps