MortgageBrokerTools API

The MBT API is GraphQL-first. All case creation, result retrieval, user management, and webhook configuration are performed through a single /graphql endpoint — there are no REST alternatives.

Key advantages of GraphQL for this integration:

• Client-driven queries — request exactly the fields you need; no over- or under-fetching.
• Self-documenting schema — use GraphiQL or the schema browser to explore types, fields, and relationships interactively.
• Non-breaking additions — new fields are added without affecting existing queries. Fields are deprecated before removal.
• Single-request fetches — retrieve a case, its results, and lender details in one call.

The three main integration paths are:

1. Residential (RESI) — createCase or createCaseDraft → invokeCaseResults
2. Buy-to-let (BTL) — createBtlCase or createBtlCaseDraft → invokeCaseResults
3. Webhook push — receive result and PDF events via createOrUpdateWebhookSubscription

Release Notes

Deployments follow the branch pipeline: main (nightly) → staging → release (production). The GraphQL schema is additive-only — new fields and types are introduced without breaking existing queries. Fields are deprecated before removal; your existing queries will continue to work unchanged.

30 June 2026

New GraphQL features

• Paginated cases query with limit/offset args (max 40), and a new search query returning PaginatedCases { totalCount, cases }. Searches across case UUID, client name, and reference.
• New lenders query with active, limit, offset, and type (RESI / BTL) args. Replaces ad-hoc filtering on activeLenders, which is retained for backward compatibility.
• New magicLink mutation returning { url, expiresAt }. Action enum values: CRITERIA, RESI, BTL, SOURCING, VULNERABLE.
• Case type gains: adviser, applicant (new ApplicantShort type), office, createdAt, lastUpdatedAt, caseType.
• Lender type gains: btlName, imageResi, imageBtl, referral, address, contact, disclosure. New objects: LenderReferral, LenderAddress, LenderContact, Disclosure.
• CaseResult gains lenderProducts: [LenderProduct!]! with new object LenderProduct (id, code, mortgageClass, initialRateYear, initialRate, bestBuy) and enum MortgageClass (Fixed, Variable, Tracker, Discount).
• Credit checks: new CreditCheck / CreditCheckDraft input objects (consentGivenAt: DateTime!, residenceHistory: [ResidenceHistory!]!) and a creditCheck field on all applicant input and response types. Three years of residence history required.
• Foreign national support: foreignNational, foreignStatus, foreignNationalResidence, and foreignNationalResidenceYearsRemaining added to RESI and BTL personal details. New enums ForeignStatus and ForeignNationalResidence.
• Loan.ownership enum gains RIGHT_TO_BUY and FIRST_HOMES_SCHEME.
• Loan.reason enum gains LET_TO_BUY.
• Loan gains purchaseDiscount; BTL Loan gains multiblockUnits.
• Income gains bonusYearThree (annual bonus, year 3).
• Expenditure enums gain EV_SALARY_SACRIFICE for both RESI and BTL.
• AdditionalIncome.income_type gains RENT_ROOM_SCHEME.
• PersonalDetails gains rentTenant (monthly rent paid if applicant is currently a tenant).
• CaseResult.amount / amountMax semantics clarified: amount is the lend amount; amountMax is the maximum based on product and income.

Webhook changes

• New signatureMethod arg on createOrUpdateWebhookSubscription. Enum WebhookSignatureMethod: CANONICAL_JSON (legacy, default) and RAW_BODY (recommended). Existing subscriptions remain on CANONICAL_JSON until explicitly migrated.
• RAW_BODY mode signs the exact wire bytes. Headers: X-Webhook-Timestamp (Unix seconds) and X-Webhook-Signature: v1=<base64-hmac>,alg=sha512. Enforce a 5-minute freshness window.
• CANONICAL_JSON (legacy) is unchanged: X-Webhook-Signature: t=<nanoseconds>,v1=<base64-hmac>,alg=sha512.
• New topic CRITERIA_PDF_CREATED — fires when a criteria PDF is generated. Payload: { topic, payload: { case_id, token, uuid, pdf, reference } }. When not associated with a case, only pdf and reference are present.
• Note: case_pdf_created payload does not carry reference — that field is emitted only on criteria_pdf_created.
• Subscription response shape gains the signatureMethod field.

Environments

Staging tokens can be generated from /api_tokens. Production credentials are provisioned by MBT — allow 2 weeks lead time before go-live.

GraphiQL

GraphiQL is an in-browser IDE for exploring and testing the API. It provides syntax highlighting, autocompletion, inline schema documentation, and a live response viewer. Use it to prototype queries before integrating them into your application.

Authentication

Every request to the GraphQL API must include a valid JWT in the Authorization header:

For WebSocket connections, pass the token as a query parameter:

Tokens are available from /api_tokens or generated programmatically via the token mutations listed in the Mutations section.

Example curl request:

Token Types

Three JWT types exist, ordered from lowest to highest privilege. Each is scoped to a specific trust boundary.

1. Broker Token

Used by broker users, backend services, or CRM integrations acting on behalf of a specific adviser. Scoped entirely to that one broker — it cannot impersonate other brokers or access other accounts. This is the token used for creating and managing cases.

2. Company Token

Used by internal company systems, admin dashboards, or trusted backend services acting on behalf of the company. Can act on behalf of any broker within the company, issue broker JWTs, and create new broker accounts. Cannot operate outside its own company boundary or create other companies.

To generate a broker token using a company token:

3. Integration Token

Used by authorised third parties and platform-level integrations. Represents MBT's trust in an external integrator. Can create companies, bootstrap accounts, and issue company-level credentials. Extremely sensitive — IP-restricted, audited, and tightly rate-limited. Contact MBT to request an integration token.

Quick Start

GraphiQL — Interactive Explorer

GraphiQL is the in-browser IDE for the API. It provides syntax highlighting, autocompletion, inline schema docs, and a live response viewer. The ▶ Try in GraphiQL buttons throughout this section open GraphiQL with the example query and variables pre-loaded.

▶ Open GraphiQL

GraphiQL benefits:

• Clients specify exactly the fields they want — one query returns a perfectly tailored response.
• The schema defines types, fields, and relationships — the Docs explorer makes it self-discoverable.
• Additions to the API never break existing clients.
• A single query can fetch all related entities in one request.

Stage 1 — Create a Draft Case

Use createCaseDraft to create a case in draft status — the case can be updated with further calls to updateCaseDraft before invoking affordability. Use createCase if all data is available upfront and you want to trigger affordability immediately.

The magicLink is a one-time, short-lived SSO link. It redirects the user into the MBT web app without requiring a separate sign-in. A fresh link can be requested at any time using the magicLink mutation.

Update a draft (optional)

Invoke affordability on a draft

Stage 2 — Retrieve Results

Poll caseResults every 5–10 seconds. Use index.total to know how many results to expect. After 90 seconds call completeCase to finalise and trigger PDF generation, then call caseResults one final time for the complete set. MBT automatically completes cases after 5 minutes.

Optional — Create an Adviser and Issue Their Token

Requires a company token. The email must be unique within MBT. Using a customer reference as the prefix (e.g. 12345@yourcompany.com) is recommended.

Buy-to-Let (BTL)

The BTL flow mirrors RESI using createBtlCase / createBtlCaseDraft:

Use the GraphiQL explorer or schema browser to discover the full field set for each input type.

Queries

All queries require a valid JWT. See the schema browser for full type details.

activeLenders

Returns the list of lenders that are currently active in this environment.

lenders

Returns lenders with optional filtering by segment and active state.

case

Returns the case (RESI or BTL) for the given UUID, scoped to the current token.

caseResidential

Returns a residential case with full type-specific fields including loan, applicants, and credit check data.

caseBtl

Returns a buy-to-let case with full type-specific fields.

caseResults

Returns the current set of affordability results for a case. Use for polling (every 5–10 s). index.total gives the total number of results expected. amount is the lend amount; amountMax is the maximum based on product and income.

cases

Returns a paginated list of cases for the authenticated user.

search

Searches cases by UUID, client name, and reference. Returns paginated results with a total count.

currentCompany

Returns the company for the authenticated token. Requires a broker or company token.

caseStatistics

Returns aggregated statistics for a given case type and value.

occupations

Returns ONS-compliant occupation entries for use in applicant personal details.

Mutations

Token Management

createTokenForBroker (requires company token)

Creates a broker JWT by email address or UUID. The preferred mutation for generating adviser tokens.

createTokenByEmail (requires company token)

Creates a broker token by email address.

createTokenByUuid (requires company token)

Creates a broker token by user UUID.

createTokenForCompany (requires integration token)

Creates a company token. Identify the company by any one of the arguments below.

User & Company Provisioning

createUser (requires company token)

Creates a user under the current company. The email must be unique within MBT.

createCompany (requires integration token)

Creates a company with an admin user. Optionally sends an onboarding email.

Magic Link

magicLink

Generates a one-time, short-lived SSO link. The link redirects the user into the MBT web app without requiring a separate sign-in. Available actions:

Residential Cases

createCase

Creates a residential case and immediately invokes affordability. Preferred when all data is available upfront. Charged per invocation.

createCaseDraft

Creates a draft residential case. All fields optional — build the case incrementally, then call invokeCaseResults when ready. Not charged at creation. See the Quick Start section for a full 2-applicant payload.

updateCaseDraft

Updates a draft residential case. Each update replaces the supplied section entirely.

Buy-to-Let Cases

createBtlCase

Creates a BTL case and immediately invokes affordability. Charged per invocation.

createBtlCaseDraft

Creates a draft BTL case. All fields optional. Not charged at creation.

updateBtlCaseDraft

Updates a draft BTL case. Takes the same arguments as createBtlCaseDraft plus uuid.

Case Lifecycle

invokeCaseResults

Triggers affordability evaluation on a draft case. After calling this, poll caseResults for incoming lender results. Charged per invocation.

completeCase

Marks the case as complete and triggers PDF generation. Call once you have sufficient results (recommended: after 90 seconds). MBT automatically completes cases after 5 minutes. After completing, call caseResults once more for the final comprehensive result set.

cloneCase

Clones a case (RESI or BTL). Optionally creates a new client record and depersonalises the data.

Webhook Management

createOrUpdateWebhookSubscription (requires company token)

Creates or updates the company's webhook subscription. A company has at most one subscription record; calling this again updates the existing one.

Subscriptions (WebSocket)

The caseResults subscription streams results in real time as lenders respond. Subscriptions require a WebSocket connection using Phoenix Sockets and Absinthe. Client libraries: @absinthe/socket, Phoenix.js. For CLI testing, websocat is useful.

1. Connect

2. Join the control channel

3. Subscribe to results

The reply includes a subscriptionId. Events then arrive as:

4. Unsubscribe

Try the subscription in GraphiQL

GraphiQL supports subscriptions over WebSocket. Replace the UUID with a real case UUID, then click ▶ Try in GraphiQL.

Heartbeat

Send every 30 seconds (must be at least every 60) to keep the connection alive:

Protocol versions

vsn=1.0.0: messages are JSON objects with topic, event, payload, ref.
vsn=2.0.0: messages are arrays [joinRef, ref, topic, event, payload], where joinRef matches the ref from the initial phx_join and stays consistent for the stream.

Webhooks

MBT pushes event notifications to your endpoint when cases produce results or PDFs are generated. Delivery is best-effort: one attempt per event; succeeded on any 2xx response; failures are logged but not retried. Always call completeCase and then caseResults as your definitive source of truth — do not rely solely on webhook delivery.

For local development, use ngrok to expose a local endpoint. A test harness with example receiver code is available at github.com/Parobus/mbt-webhooks-example.

Topics

CASE_RESULTS payload

Screenshot URLs in results are valid for 1 hour. Download and store them on receipt for compliance purposes.

CASE_PDF_CREATED payload

PDF URLs are valid for 24 hours. Store the file on receipt.

CRITERIA_PDF_CREATED payload

When not associated with a case, only pdf and reference are present.

Signature Verification

Every delivery is signed with HMAC-SHA-512 using the subscription's shared secret. Choose your signing method when creating the subscription:

RAW_BODY (recommended)

Headers on each delivery:

The signed payload is "<timestamp>" + "." + <raw-body-bytes>. Do not parse and re-serialise the JSON before verifying — any whitespace or key-ordering difference will produce a mismatching digest. Read the raw request body before any JSON middleware touches it.

Framework notes:

• Express: express.raw({ type: 'application/json' }) before express.json(); use req.body (a Buffer).
• FastAPI: raw = await request.body() before request.json().
• Go: read r.Body into a byte slice once, pass the same bytes to both verifier and json.Unmarshal.
• AWS Lambda: use event.body string before JSON.parse; base64-decode first if isBase64Encoded is true.

Always compare digests using a constant-time function (crypto.timingSafeEqual, hmac.compare_digest, crypto/hmac.Equal) and reject requests where the timestamp is more than 5 minutes old.

Node.js (RAW_BODY)

Python / FastAPI (RAW_BODY)

CANONICAL_JSON (legacy)

Header on each delivery:

t is Unix time in nanoseconds (~19 digits, not seconds). The signed payload is "<t>" + "." + canonical_string(body), where canonical_string:

1. JSON-decodes the body into a map.
2. Recursively flattens to dotted/indexed key=value pairs (nested maps: a.b=1; lists: xs[0]=10).
3. Sorts pairs lexicographically (byte/ordinal order — not locale-aware).
4. Joins with ,.
5. Lowercases the entire resulting string.

Gotchas: lowercase after sorting; integers must not gain a trailing .0; use a parser that preserves int vs. float for large IDs.

Elixir (CANONICAL_JSON)

Node.js (CANONICAL_JSON)

Rate Limits & Billing

Rate limits

Billing

API charging is based on case execution. You are only billed when you invoke affordability via createCase, createBtlCase, or invokeCaseResults. All subsequent queries against a completed case (results, lender data, case status) are free.

WAF / IP allowlisting

If your server-to-server requests are blocked by CloudFront WAF (the SignalKnownBotDataCenter managed rule blocks requests originating from known data-centre IP ranges), contact MBT to have your IP range allowlisted via the contact form.

FAQ