Create a mortgage search with the Mortgage Brain provider

Create a mortgage search with the Mortgage Brain provider Run in API Explorer

POST /api/v1/addons/mortgagebrain/mortgage-search

Personal access token & O auth2

application/json

Body

applicants array[object] Required

The applicants for the mortgage search. Must be at least one and no more than two.
Hide applicants attributes Show applicants attributes object
- account_uuid string(uuid)
  
  The UUID of the applicant
- title string
  
  The title of the applicant
  
  Value Description
  
  mr MR
  
  mrs MRS
  
  miss MISS
  
  ms MS
  
  mx MX
  
  dr DR
  
  dame DAME
  
  father FATHER
  
  madam MADAM
  
  lord LORD
  
  sir SIR
  
  prof PROF
  
  Values are mr, mrs, miss, ms, mx, dr, dame, father, madam, lord, sir, or prof.
- date_of_birth string(date) | null
  
  The date of birth of the applicant
- birth_gender string | null
  
  The birth gender of the applicant
  
  Value Description
  
  male MALE
  
  female FEMALE
  
  Values are male or female.
- salutation string | null
  
  The salutation of the applicant
- retirement_age integer | null
  
  The retirement age of the applicant
- employment_status string | null
  
  The employment status of the applicant
  
  Value Description
  
  employed EMPLOYED
  
  self_employed SELF_EMPLOYED
  
  retired RETIRED
  
  Values are employed, self_employed, or retired.
- annual_salary_amount integer | null
  
  The annual salary amount of the applicant. Price must be in pennies.
case_uuids array[string(uuid)] | null

An optional array of case UUIDs to associate to the mortgage search
oauth_connection_uuid string(uuid) | null

An optional OAuth2 connection UUID to overwrite the default behaviour (which is to pick the first Mortgage Brain OAuth2 connection)
proceed boolean Required

This parameter can be used to indicate whether to proceed with creating the mortgage search or not. If false, a 202 response will be returned without creating the search. This can be used to validate the data before continuing.

Value	Description
mr	MR
mrs	MRS
miss	MISS
ms	MS
mx	MX
dr	DR
dame	DAME
father	FATHER
madam	MADAM
lord	LORD
sir	SIR
prof	PROF

Value	Description
male	MALE
female	FEMALE

Value	Description
employed	EMPLOYED
self_employed	SELF_EMPLOYED
retired	RETIRED

Responses

200 application/json
Hide response attributes Show response attributes object
- uuid string
  
  The UUID of the resource.
- created_at string
  
  The timestamp of when the resource was created.
- updated_at string
  
  The timestamp of when the resource was updated.
- name string
  
  The name of the mortgage search
- status string
  
  The status of the mortgage search
- provider string
  
  The provider that the mortgage search is for
- provider_reference string
  
  The provider reference of the mortgage search
- provider_data array
  
  Any provider data related to the mortgage search
- applicants array[object]
  
  The applicants of the mortgage search
  
  Hide applicants attributes Show applicants attributes object
  
  uuid string
  
  created_at string
  
  updated_at string
  
  account string
- cases array[object]
  
  The cases that are related to the mortgage search
  
  Hide cases attributes Show cases attributes object
  
  uuid string
  
  created_at string
  
  updated_at string
  
  name string
  
  slug string
  
  status string
  
  type string
  
  review_at string
  
  assigned_to_uuids array[string]
  
  group_uuids array[string]
  
  completed_at string
  
  value object
  
  Hide value attributes Show value attributes object
  
  amount object
  
  Hide amount attributes Show amount attributes object
  
  example string
  
  description string
  
  formatted object
  
  Hide formatted attributes Show formatted attributes object
  
  example string
  
  description string
  
  currency object
  
  Hide currency attributes Show currency attributes object
  
  example string
  
  description string
  
  status_position integer
  
  participants_count integer
  
  participants string
  
  task_board_uuid string
  
  plans string
  
  custom_fields string
- products array[object]
  
  The products that are related to the mortgage search
  
  Hide products attributes Show products attributes object
  
  uuid string
  
  created_at string
  
  updated_at string
  
  provider_reference string
  
  provider_scenario_name string
  
  provider_scenario_data array
  
  lender_name string
  
  product_title string
  
  files string
- files array[object]
  
  The files that are related to the mortgage search
  
  Hide files attributes Show files attributes object
  
  uuid string
  
  created_at string
  
  original_created_at string
  
  updated_at string
  
  uploaded_at string
  
  status string
  
  filename string
  
  name string
  
  extension string
  
  type string
  
  size string
  
  path string
  
  last_modified string
  
  progress string
  
  download_url string
  
  folder_name string
  
  folder string
  
  documentable_type string
  
  documentable string
  
  navigator object
  
  Hide navigator attributes Show navigator attributes object
  
  model_type string
  
  model_uuid string
  
  firm string
  
  account string
  
  tags string

POST /api/v1/addons/mortgagebrain/mortgage-search

curl \
 --request POST 'https://api.plannrcrm.com/api/v1/addons/mortgagebrain/mortgage-search' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"applicants":[{"title":"mr","salutation":"John","account_uuid":"3dd137e1-4c0e-4dc9-b81b-95e8179a1573","birth_gender":"male","date_of_birth":"1999-01-01","retirement_age":65,"employment_status":"employed","annual_salary_amount":3000000}],"case_uuids":["4b91a2a2-02df-43a3-b751-d36fb7f92f57","8672f1cb-5d85-462d-8203-08c5880efaaa","6ef46b38-52ba-4add-92ff-52b5eb98f441"],"oauth_connection_uuid":"5356afb7-aa3f-4d80-b3a0-e19d0180bcd7","proceed":true}'

Request examples

{
  "applicants": [
    {
      "title": "mr",
      "salutation": "John",
      "account_uuid": "3dd137e1-4c0e-4dc9-b81b-95e8179a1573",
      "birth_gender": "male",
      "date_of_birth": "1999-01-01",
      "retirement_age": 65,
      "employment_status": "employed",
      "annual_salary_amount": 3000000
    }
  ],
  "case_uuids": [
    "4b91a2a2-02df-43a3-b751-d36fb7f92f57",
    "8672f1cb-5d85-462d-8203-08c5880efaaa",
    "6ef46b38-52ba-4add-92ff-52b5eb98f441"
  ],
  "oauth_connection_uuid": "5356afb7-aa3f-4d80-b3a0-e19d0180bcd7",
  "proceed": true
}

Response examples (200)

{
  "name": "My Mortgage Search",
  "uuid": "7fd883a6-c839-4c5b-aaf8-698deff20c23",
  "cases": [
    {
      "name": "finance",
      "slug": "finance",
      "type": "App\\Http\\Resources\\CasesTypeResource",
      "uuid": "465e45f5-1d8b-4ca6-ae8d-de4bdc30d203",
      "plans": "App\\Http\\Resources\\Plans\\PlanResource",
      "value": {
        "amount": {
          "example": "4000",
          "description": "Money amount at their lowest denominator (for example: pennies)"
        },
        "currency": {
          "example": "GBP",
          "description": "Currency of the money"
        },
        "formatted": {
          "example": "£40.00",
          "description": "Money amount formatted with currency"
        }
      },
      "status": "App\\Http\\Resources\\CasesStatusResource",
      "review_at": "2026-03-20T13:25:17+00:00",
      "created_at": "2026-03-20T13:25:17+00:00",
      "updated_at": "2026-03-20T13:25:17+00:00",
      "group_uuids": [
        "573024b8-1413-4263-a51f-f2ffa196a2d1"
      ],
      "completed_at": "2026-03-20T13:25:17+00:00",
      "participants": "App\\Http\\Resources\\AccountResource",
      "custom_fields": "App\\Http\\Resources\\CustomFieldValueResource",
      "status_position": 4,
      "task_board_uuid": "6e4e269f-d535-4aa4-8465-917bd5d65302",
      "assigned_to_uuids": [
        "365268ea-6868-4ef6-8e00-fe2b61f06f60"
      ],
      "participants_count": 4
    }
  ],
  "files": [
    {
      "firm": "App\\Http\\Resources\\FirmResource",
      "name": "Welcome to Plannr",
      "path": "Gareth Thompson/Subfolder/Welcome to Plannr.pdf",
      "size": "21691783",
      "tags": "App\\Http\\Resources\\TagResource",
      "type": "type",
      "uuid": "471a5e3f-cb11-43c1-ba7c-3b54f38d2c20",
      "folder": "App\\Http\\Resources\\FolderResource",
      "status": "uploaded",
      "account": "App\\Http\\Resources\\MinimalAccountResource",
      "filename": "Welcome to Plannr.pdf",
      "progress": "100",
      "extension": "pdf",
      "navigator": {
        "model_type": "account",
        "model_uuid": "00892fcb-085c-4d66-9155-b94513d524bc"
      },
      "created_at": "2026-03-20T13:25:17+00:00",
      "updated_at": "2026-03-20T13:25:17+00:00",
      "folder_name": "folder 2",
      "uploaded_at": "2026-03-20T13:25:17+00:00",
      "documentable": "Object",
      "download_url": "https://api.plannrcrm.com/file/2c5e3b32-4584-4d93-8602-4dc2619816df/download",
      "last_modified": "2026-03-20T13:25:17+00:00",
      "documentable_type": "account",
      "original_created_at": "2026-03-20T13:25:17+00:00"
    }
  ],
  "status": "pending",
  "products": [
    {
      "uuid": "c55b85c4-e7b9-403d-a058-323ba2244f67",
      "files": "App\\Http\\Resources\\FileResource",
      "created_at": "2026-03-20T13:25:17+00:00",
      "updated_at": "2026-03-20T13:25:17+00:00",
      "lender_name": "HSBC",
      "product_title": "5% Fixed Rate - 5 year",
      "provider_reference": "example-reference",
      "provider_scenario_data": [],
      "provider_scenario_name": "Single Applicant, Small Deposit"
    }
  ],
  "provider": "Mortgage Brain",
  "applicants": [
    {
      "uuid": "42536fc1-5944-4791-abaf-5377f44228c5",
      "account": "App\\Http\\Resources\\MinimalAccountResource",
      "created_at": "2026-03-20T13:25:17+00:00",
      "updated_at": "2026-03-20T13:25:17+00:00"
    }
  ],
  "created_at": "2026-03-20T13:25:17+00:00",
  "updated_at": "2026-03-20T13:25:17+00:00",
  "provider_data": [],
  "provider_reference": "123456789"
}