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.

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":[{"account_uuid":"02320c61-1d93-4dcf-9fc4-c196586f54be","title":"mr","date_of_birth":"1999-01-01","birth_gender":"male","salutation":"John","retirement_age":65,"employment_status":"employed","annual_salary_amount":3000000}],"case_uuids":["2233c16d-3b2b-4918-856c-89f503a5cb56","0c176604-c307-4e3f-b28d-2320d277fc60","5e2dba22-a904-44d0-8311-4114c35c60a5"],"oauth_connection_uuid":"d26ff664-55c1-474e-8866-b1ae328ce8e0","proceed":true}'
Request examples 
{
  "applicants": [
    {
      "account_uuid": "02320c61-1d93-4dcf-9fc4-c196586f54be",
      "title": "mr",
      "date_of_birth": "1999-01-01",
      "birth_gender": "male",
      "salutation": "John",
      "retirement_age": 65,
      "employment_status": "employed",
      "annual_salary_amount": 3000000
    }
  ],
  "case_uuids": [
    "2233c16d-3b2b-4918-856c-89f503a5cb56",
    "0c176604-c307-4e3f-b28d-2320d277fc60",
    "5e2dba22-a904-44d0-8311-4114c35c60a5"
  ],
  "oauth_connection_uuid": "d26ff664-55c1-474e-8866-b1ae328ce8e0",
  "proceed": true
}
Response examples (200) 
{
  "uuid": "b9713539-3b13-484f-ab28-ac53269859ce",
  "created_at": "2026-04-30T17:33:16+01:00",
  "updated_at": "2026-04-30T17:33:16+01:00",
  "name": "My Mortgage Search",
  "status": "pending",
  "provider": "Mortgage Brain",
  "provider_reference": "123456789",
  "provider_data": [],
  "applicants": [
    {
      "uuid": "0cfc6c4a-3e99-4b78-84fa-63dfef8cbae5",
      "created_at": "2026-04-30T17:33:16+01:00",
      "updated_at": "2026-04-30T17:33:16+01:00",
      "account": "App\\Http\\Resources\\MinimalAccountResource"
    }
  ],
  "cases": [
    {
      "uuid": "6daf260b-f135-42dc-8f4b-12aec4c5ecde",
      "created_at": "2026-04-30T17:33:16+01:00",
      "updated_at": "2026-04-30T17:33:16+01:00",
      "name": "finance",
      "slug": "finance",
      "status": "App\\Http\\Resources\\CasesStatusResource",
      "type": "App\\Http\\Resources\\CasesTypeResource",
      "review_at": "2026-04-30T17:33:16+01:00",
      "assigned_to_uuids": [
        "731b79a3-2fcd-40c4-be27-b669c252bc67"
      ],
      "group_uuids": [
        "6960a04d-7a81-461e-a704-8470ac88d754"
      ],
      "completed_at": "2026-04-30T17:33:16+01:00",
      "value": {
        "amount": {
          "example": "4000",
          "description": "Money amount at their lowest denominator (for example: pennies)"
        },
        "formatted": {
          "example": "£40.00",
          "description": "Money amount formatted with currency"
        },
        "currency": {
          "example": "GBP",
          "description": "Currency of the money"
        }
      },
      "status_position": 4,
      "participants_count": 4,
      "participants": "App\\Http\\Resources\\AccountResource",
      "task_board_uuid": "1895c75c-c7e7-4e4f-a814-b11c4ec10dfe",
      "plans": "App\\Http\\Resources\\Plans\\PlanResource",
      "custom_fields": "App\\Http\\Resources\\CustomFieldValueResource"
    }
  ],
  "products": [
    {
      "uuid": "5c463261-1be9-44f5-9ef9-00077e0fe211",
      "created_at": "2026-04-30T17:33:16+01:00",
      "updated_at": "2026-04-30T17:33:16+01:00",
      "provider_reference": "example-reference",
      "provider_scenario_name": "Single Applicant, Small Deposit",
      "provider_scenario_data": [],
      "lender_name": "HSBC",
      "product_title": "5% Fixed Rate - 5 year",
      "files": "App\\Http\\Resources\\FileResource"
    }
  ],
  "files": [
    {
      "uuid": "0f283949-8b99-42a6-8a69-529ae212232a",
      "created_at": "2026-04-30T17:33:16+01:00",
      "original_created_at": "2026-04-30T17:33:16+01:00",
      "updated_at": "2026-04-30T17:33:16+01:00",
      "uploaded_at": "2026-04-30T17:33:16+01:00",
      "status": "uploaded",
      "filename": "Welcome to Plannr.pdf",
      "name": "Welcome to Plannr",
      "extension": "pdf",
      "type": "type",
      "size": "21691783",
      "path": "Gareth Thompson/Subfolder/Welcome to Plannr.pdf",
      "last_modified": "2026-04-30T17:33:16+01:00",
      "progress": "100",
      "download_url": "https://api.plannrcrm.com/file/a29a4d4e-cff8-402b-a19a-a71feb5c100b/download",
      "folder_name": "folder 2",
      "folder": "App\\Http\\Resources\\FolderResource",
      "documentable_type": "account",
      "documentable": "Object",
      "navigator": {
        "model_type": "account",
        "model_uuid": "d397f002-c3ca-4004-88c3-b80766016f54"
      },
      "firm": "App\\Http\\Resources\\FirmResource",
      "account": "App\\Http\\Resources\\MinimalAccountResource",
      "tags": "App\\Http\\Resources\\TagResource"
    }
  ]
}