Integration Guide

Affordability API

Submit a mortgage affordability job, then retrieve the per-lender results. Every request is authenticated with an HMAC-SHA256 signature — no session, no login, just your key and secret.

How it works

Affordability is calculated asynchronously across multiple lenders, so the flow is submit-then-poll:

Two ways to get results — pick whichever fits

Both return the same data. Choose the model that suits your integration; you can even use callbacks with polling as a safety net.

Authentication

Credentials & headers

We issue you three values. The secret is never sent over the wire — it only ever signs requests, so keep it on your server side.

Request headers on every call

Authentication

Signing a request

The signature covers the method, path, timestamp, and a hash of the body — so any tampering invalidates it. Build it in four steps:

1. timestamp — current Unix time in seconds, as a string, e.g. 1751880000.
2. body hash — lowercase hex SHA-256 of the raw request body bytes. For a request with no body (GET), hash the empty string.
3. canonical string — join with newline (\n) characters:

   {METHOD}\n{PATH}\n{timestamp}\n{body_hash}

   METHOD uppercase (POST). PATH is the request path including any query string, exactly as sent — everything after the host, e.g. /ps/affordability/affordabilityJobs. No host, no scheme.
4. signature — lowercase hex HMAC-SHA256(secret, canonical_string). Send it as Authorization: HMAC {api_client_key}:{signature}.

Authentication

Code examples

A reusable signer, then a signed POST. Swap in your credentials.

const crypto = require('crypto');

const API_CLIENT_KEY = 'your-api-client-key';
const SECRET         = 'your-shared-secret';
const TID            = 'your-tid';
const BASE_URL       = 'https://staging.mintlabs.io/ps';

// Build the signed headers. `url` is the full request URL — the signed path is
// derived from it, so it always matches the path you actually call.
function signedHeaders(method, url, body = '') {
  const u         = new URL(url);
  const path      = u.pathname + u.search;  // e.g. /ps/affordability/affordabilityJobs
  const timestamp = String(Math.floor(Date.now() / 1000));
  const bodyHash  = crypto.createHash('sha256').update(body).digest('hex');
  const canonical = `${method.toUpperCase()}\n${path}\n${timestamp}\n${bodyHash}`;
  const signature = crypto.createHmac('sha256', SECRET).update(canonical).digest('hex');
  return {
    'Authorization':  `HMAC ${API_CLIENT_KEY}:${signature}`,
    'X-Mk-Timestamp': timestamp,
    'x-tid':          TID,
    'accept-version': '2.0.0',
    'Content-Type':   'application/json',
  };
}

// Submit an affordability job.
const url  = `${BASE_URL}/affordability/affordabilityJobs`;
const body = JSON.stringify({ run_id: '3wc7', /* … rest of affordability payload */ });

const res = await fetch(url, {
  method: 'POST', headers: signedHeaders('POST', url, body), body,
});
console.log(res.status, await res.json());

import hashlib, hmac, time, json, requests
from urllib.parse import urlsplit

API_CLIENT_KEY = "your-api-client-key"
SECRET         = "your-shared-secret"
TID            = "your-tid"
BASE_URL       = "https://staging.mintlabs.io/ps"

def signed_headers(method, url, body=""):
    parts = urlsplit(url)
    path = parts.path + (("?" + parts.query) if parts.query else "")  # e.g. /ps/affordability/affordabilityJobs
    ts = str(int(time.time()))
    body_hash = hashlib.sha256(body.encode()).hexdigest()
    canonical = f"{method.upper()}\n{path}\n{ts}\n{body_hash}"
    sig = hmac.new(SECRET.encode(), canonical.encode(), hashlib.sha256).hexdigest()
    return {
        "Authorization":  f"HMAC {API_CLIENT_KEY}:{sig}",
        "X-Mk-Timestamp": ts,
        "x-tid":          TID,
        "accept-version": "2.0.0",
        "Content-Type":   "application/json",
    }

url  = f"{BASE_URL}/affordability/affordabilityJobs"
body = json.dumps({ "run_id": "3wc7", # … rest of affordability payload })
r = requests.post(url, headers=signed_headers("POST", url, body), data=body)
print(r.status_code, r.json())

API_CLIENT_KEY="your-api-client-key"
SECRET="your-shared-secret"
TID="your-tid"
BASE="https://staging.mintlabs.io"
PATH_="/ps/affordability/affordabilityJobs"
TS=$(date +%s)
BODY='{"run_id":"3wc7","...":"rest of affordability payload"}'

BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $2}')
CANONICAL=$(printf '%s\n%s\n%s\n%s' "POST" "$PATH_" "$TS" "$BODY_HASH")
SIG=$(printf '%s' "$CANONICAL" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -X POST "$BASE$PATH_" \
  -H "Authorization: HMAC $API_CLIENT_KEY:$SIG" \
  -H "X-Mk-Timestamp: $TS" \
  -H "x-tid: $TID" \
  -H "accept-version: 2.0.0" \
  -H "Content-Type: application/json" \
  --data "$BODY"

Endpoint

Submit a job

Submits an affordability calculation. Responds immediately with an applicationId; the calculation runs in the background.

Request body

The affordability payload (applicants, property, income, selected lenders). Your onboarding pack includes the full schema and a worked example. Optionally include callback_url if you have push delivery enabled.

{
  "run_id": "3wc7",   // required — your identifier for this affordability run
  "application_id": "OR99ZDDNEYIDG571L5Z8J5J1LK",   // optional; we generate one if omitted
  "callback_url": "https://your-app.example.com/hooks/affordability",  // optional; enables real-time callbacks
  "data": {
    "no_of_applicants": 2,
    "purchase_property_value": 400000,
    "purchase_term": 300
    // … full applicant & property details
  },
  "lender_metadata": [   // optional; per-lender rate/fee overrides
    { "lender": "HSBC",      "initial_rate": 4.39, "rate_type": "Fixed", "second_rate": 7.25, "second_type": "Variable", "third_rate": null, "reversion_rate": 7.25, "percent_fee": null, "net_fee": 3999 },
    { "lender": "Barclays",  "initial_rate": 4.74, "rate_type": "Fixed", "second_rate": 8.24, "second_type": "Variable", "third_rate": null, "reversion_rate": 8.24, "percent_fee": null, "net_fee": 964 }
    // … one entry per lender in selected_banks
  ],
  "selected_banks": ["HSBC", "Barclays", "Santander"]
}

run_id is required — a request without it is rejected with 404 Missing run id. application_id stays optional; omit it and we generate one for you.

Lender metadata (optional)

lender_metadata lets you pass known rate/fee terms per lender, one object per entry in selected_banks, matched by the lender field.

Response · 201 Created

{
  "message": "Job accepted for (2b1e9c7a-…-uuid)",
  "applicationId": "2b1e9c7a-…-uuid",
  "runId": "3wc7"
}

Store the applicationId — it's the key used to fetch results and screenshots (run_id is echoed back but is not used to look anything up). Submitting a duplicate application_id while a job is still running returns 409 Conflict.

Endpoint

Get result

Returns the current state of a job. This request has no body — sign it with the empty-string body hash.

While calculating · 200 OK

{
  "application_id": "2b1e9c7a-…-uuid",
  "status": "PENDING",
  "bank_details": []
}

When complete · 200 OK

{
  "application_id": "2b1e9c7a-…-uuid",
  "status": "DONE",
  "bank_details": [
    { "bank_name": "Santander", "status": "pass", "aff_amt": 452000, "screenshot_file_name": "santander_2b1e.png" },
    { "bank_name": "Barclays",  "status": "pass", "aff_amt": 438500, "screenshot_file_name": "barclays_2b1e.png" },
    { "bank_name": "HSBC",      "status": "unable_to_calculate", "aff_amt": null, "screenshot_file_name": null }
  ]
}

An unknown or not-yet-created applicationId returns 404 Not Found.

Real-time delivery

Callbacks

Option B for getting results. Instead of polling, provide a callback_url when you submit and we POST results to your endpoint as they happen — one message per lender the moment it finishes, then a final summary once every lender is done. Because each lender arrives individually, you can render results progressively (lazy loading) rather than waiting for the whole job — but that's optional, and how you use the updates is entirely your choice.

Enable it

Include callback_url in the submit body (see Submit a job). We then send two kinds of message to that URL.

Message 1 · per-lender update

Sent each time a single lender finishes — this is the one you use to lazy-load results into your UI.

{
  "application_id":  "2b1e9c7a-…-uuid",
  "bank_name":       "Santander",
  "status":          "pass",
  "aff_amt":         452000,
  "banks_completed": 3,
  "banks_total":     10,
  "screenshot_url":  "https://…/screenshot/2b1e…/Santander"
}

Message 2 · job complete

Sent once, after every lender has finished. Identify it by "event": "job_complete".

{
  "application_id":        "2b1e9c7a-…-uuid",
  "event":                 "job_complete",
  "total_banks":           10,
  "passed":                7,
  "failed":                3,
  "all_screenshots": [
    { "bank_name": "Santander", "status": "pass", "aff_amt": 452000, "screenshot_url": "https://…" },
    { "bank_name": "HSBC",      "status": "unable_to_calculate", "aff_amt": null, "screenshot_url": null }
  ],
  "screenshots_index_url": "https://…/screenshots/2b1e…"
}

Delivery & your endpoint

Results

Screenshots

Each lender result can include a screenshot (a visual capture of the affordability calculation). Screenshots are available with both polling and callbacks, and the images are retrieved from dedicated endpoints using the same HMAC signing as every other request.

Where the reference appears

• Polling — each bank_details entry includes screenshot_file_name when a screenshot exists (null if not).
• Callbacks — the per-lender and job_complete messages include a ready-to-use screenshot_url that points at the download endpoint below.

Download one lender's screenshot

Streams the PNG image for a single lender (Content-Type: image/png). bankName must be URL-encoded. Returns 404 with a JSON error if the job, lender, or screenshot isn't found (not_found, bank_not_found, screenshot_unavailable).

List all screenshots for a job

Returns a JSON index of every lender's screenshot download URL for the job.

{
  "application_id":       "2b1e9c7a-…-uuid",
  "job_status":           "DONE",
  "total_banks":          3,
  "screenshots_index_url": "https://…/ps/affordability/screenshots/2b1e…",
  "screenshots": [
    { "bank_name": "Santander", "status": "pass", "aff_amt": 452000, "screenshot_url": "https://…/ps/affordability/screenshot/2b1e…/Santander" },
    { "bank_name": "HSBC",      "status": "unable_to_calculate", "aff_amt": null, "screenshot_url": null }
  ]
}

Guide

Polling for completion

After submitting, poll GET /ps/affordability/affordabilityJobs/{applicationId} until status is DONE.

• Poll every 3–5 seconds — most jobs finish within a minute, depending on lender count.
• Apply a sensible overall timeout (e.g. a few minutes) and surface a retry to the user rather than polling forever.
• Each poll is a new signed request — generate a fresh timestamp and signature every time.
• DONE is terminal. Individual lenders may still be unable_to_calculate; that is a result, not an error.

Reference

Errors

Authentication failures return 401 with a JSON body { "error": "<code>" }. Other failures return a plain-text message with the status below.

Reference

Integration checklist

• Store api_client_key, secret, and tid server-side — never expose the secret in a browser or mobile client.
• Sign the exact path you request, including the /ps/affordability prefix and any query string.
• Hash the raw body bytes you actually send; use the empty-string hash for GET.
• Generate a fresh Unix-seconds timestamp and signature for every request.
• Keep your server clock synced (NTP) to stay inside the ±5-minute window.
• Always send run_id on submit — it's required; the request is rejected without it.
• Submit → capture applicationId → get results by either polling until DONE or receiving callbacks (your choice). applicationId, not run_id, is the key used to fetch results and screenshots.
• Handle 401 codes distinctly from business errors (409/404).