Partner API (1.0.0)

1. Get an API key. A partner admin creates keys in the partner admin, choosing each key's scopes (applications:create, applications:read, applications:amend) and, optionally, the IP ranges it may be used from. The key is shown once. Send it on every request as Authorization: Bearer <key>. The server in this page is a placeholder: use the base URL you are given, which ends in /partner. Every path here, such as /v1/applications, follows it.
2. Create the application with POST /v1/applications: your partnerReference, the customer, the property and the quote. A 201 returns the Application and a handoffUrl.
3. Send the customer to handoffUrl. It works once and expires 30 minutes after it is issued. For another, call issueHandoff (or repeat the create): each call issues a new one.
4. Receive webhooks. A partner admin registers an https URL on port 443, the default (no other port is accepted), and creates the signing secret in the partner admin. Each status change and each amend is POSTed there, signed: see Verifying webhook signatures. Read the full Application with getApplication at any time.

All three are whole numbers; nothing in this API is a decimal.

• Money is { "amount", "currency" }, amount in pence: 2345 = £23.45, from 0 to 1000000000 (£10,000,000.00). currency is GBP, the only one accepted for now.
• quantity is in hundredths: 100 = one item, 150 = 1.5 (an hour and a half), from 1 to 100000. Leave it out for one item.
• percentage (a percentage discount) is in hundredths of a percent: 1000 = 10.00%, from 1 to 10000.

How each line is priced, which is how your figures are checked:

1. gross = quantity × unitPrice ÷ 100, rounded half away from zero to a whole penny.
2. A discount is at most gross. For a percentage discount, its amount must be within 1p of gross × percentage ÷ 10000.
3. net = gross − the discount's amount.
4. vat must be within 1p of net × the rate for 5% and 20%, and exactly 0 for exempt and 0%. A line outside these rules is refused with 422 invalid_line_item.

The total including VAT is the sum of every line's net and vat. expectedTotal must equal it exactly, or the quote is refused with 422 total_mismatch and totals carries ours. That total must be above zero (total_out_of_range) and inside the loan amounts of a finance product offered to you now (amount_out_of_bounds).

Worked example (Package plus add-ons under createApplication): the package is 100 × 149900 ÷ 100 = 149900 gross, less 10% (1000) = 14990, so net 134910 and VAT 26982; 1.5 hours (150) at 6000 is 9000 net and 1800 VAT; the search fee, quantity left out, is 2500 net and exempt. The total is 146410 + 28782 = 175192 pence, £1,751.92: the expectedTotal sent.

Each delivery carries X-Signature: t=<unix seconds>,v1=<hex>. To verify it:

1. Take the request body's raw bytes, before parsing the JSON (re-serialising changes them).
2. Compute HMAC-SHA256, keyed with your webhook secret (the whole string shown, whsec_ included, as UTF-8), over t, a full stop, then the raw body.
3. Compare its lowercase hex with each v1 in constant time. Accept the delivery only if one matches and t is within 5 minutes of your clock, either side.

For 24 hours after you rotate the secret, the header carries two v1 entries, one per secret.

Worked example. With the example secret whsec_example_do_not_use and this raw body:

{"eventId":"0b6f3c1e-7d2a-4f58-9c41-3e8a5d2b7f90","type":"application.status_changed","occurredAt":"2026-10-12T09:41:07.000Z","applicationId":"5f0c7d2e-8a41-4c3b-9e6f-2d1a7b9c4e10","partnerReference":"PB-104231","from":"created","to":"in_progress"}

the signed string is 1791798067. followed by that body, and the header is:

X-Signature: t=1791798067,v1=5cd52388091b18ca49ccffe17dd8d15475426045c29dcf9bd45ea48d1bebef53

so the HMAC's hex is 5cd52388091b18ca49ccffe17dd8d15475426045c29dcf9bd45ea48d1bebef53.

Node:

import { createHmac, timingSafeEqual } from "node:crypto";

// header: X-Signature. rawBody: the request body's bytes, before any JSON parsing (a Buffer).
export function verifySignature(header, rawBody, secret, nowSeconds = Math.floor(Date.now() / 1000)) {
  const parts = header.split(",").map((p) => p.split("="));
  const t = parts.find(([k]) => k === "t")?.[1];
  if (!t || !/^\d+$/.test(t) || Math.abs(nowSeconds - Number(t)) > 300) return false;
  const expected = createHmac("sha256", Buffer.from(secret, "utf8"))
    .update(Buffer.concat([Buffer.from(`${t}.`, "utf8"), rawBody]))
    .digest();
  return parts
    .filter(([k, v]) => k === "v1" && /^[0-9a-f]{64}$/.test(v ?? ""))
    .some(([, v]) => timingSafeEqual(Buffer.from(v, "hex"), expected));
}

Answer 2XX within 10 seconds. Every retry and replay of an event has the same eventId: use it to ignore a delivery you have already handled.

createApplication is idempotent on partnerReference. If a create times out, send the same request again. For a partnerReference you have already used:

• with the same customer email, it answers 200 with the Application and a fresh handoffUrl, creating nothing. A changed title, name, mobile or property updates what we hold.
• with a different customer email, it is refused with 409 email_conflict.
• with a changed quote, it is an amend: the key needs applications:amend as well (otherwise 403 insufficient_scope, nothing changed), and the application must be created or in progress (otherwise 409 invalid_state).
• once the application has ended (declined, withdrawn, cancelled, expired or paid out), it is refused with 409 invalid_state.

amendApplication replaces the whole quote. It answers 201 while the application is created or in progress. From submitted or approved an amend will move the application back to in progress; that is not yet available and answers 501. From any other status it is refused with 409 invalid_state.

fulfilApplication takes an Idempotency-Key; its rules are on the operation. It answers 501 until it is available.

Webhooks are retried with growing gaps for 24 hours, then marked failed. Read the application with getApplication to catch up; Ideal can replay any event.

At the end of the journey we can send the customer back to your site, to one of two addresses a partner admin sets in the partner admin. There is no API endpoint for them.

• Success address: where we send a customer after they sign their credit agreement.
• Failure address: where we send a customer whose application is declined.

No other ending sends the customer back, and either address may be left empty, in which case we do not offer the way back for that ending. Each must be an https address on the standard port (443): no other port, and no name or password before the host.

The placeholder. Put {{ref}} where your partnerReference goes, at most once, in the path or the query, never in the host. We replace it with the reference, URL-encoded, so a reference such as PB 1/2&3 arrives as PB%201%2F2%263:

https://www.example.com/finance/done?ref={{ref}}
https://www.example.com/finance/done?ref=PB-12345

Nothing else is added to the address, and nothing about the customer is put in it. A reference of . or .. would change the address's path, so for one of those we do not offer the way back.

Arriving is not proof. Anyone can open either address, with any reference. Confirm the outcome from the webhook, or with getApplication, before acting on it.

Every error is application/problem+json:

{ "type": "about:blank", "title": "Conflict", "status": 409, "code": "email_conflict",
  "detail": "This partnerReference belongs to a different customer." }

Branch on status and code. title and detail are written for people and may change; detail is sometimes absent.

Each operation lists its own responses, with an example of each.

Rate limits. Each API key, and each calling address, may send only so many requests in a short time; past that, a request is refused with 429 rate_limited before it does anything, so it is always safe to retry. The Retry-After header says how many whole seconds to wait. Wait at least that long, then retry, backing off further if you are refused again. The limits are well above normal use and may change, so do not build to a number.

Every response, an error or not, carries an X-Request-Id header. Quote it when you ask us about a request. You may send your own X-Request-Id as a UUID and we use it; any other value is replaced with one of ours.

Applications.

What Ideal sends to your webhook URL.