{
  "openapi": "3.1.0",
  "info": {
    "title": "bluerate API for AI agents",
    "version": "1.0.0",
    "summary": "Find licensed US mortgage loan officers listed on bluerate.ai.",
    "description": "Read-only, free and without a key. Answers come from a snapshot of bluerate.ai loan officer profiles taken once a day (asOf). Every loan officer has a url, their bluerate profile, which is how a user reads reviews and asks for a callback: the API never returns phone numbers, email addresses or street addresses. The same two operations are available as MCP tools at https://api.bluerate.ai/mcp (streamable HTTP). Limit without a key: 60 requests a minute per IP address. Guide: https://www.bluerate.ai/developers",
    "termsOfService": "https://www.bluerate.ai/terms-of-use",
    "contact": {
      "name": "bluerate",
      "url": "https://www.bluerate.ai/developers"
    }
  },
  "servers": [
    {
      "url": "https://api.bluerate.ai"
    }
  ],
  "externalDocs": {
    "url": "https://www.bluerate.ai/developers",
    "description": "Developer guide, MCP setup and terms"
  },
  "tags": [
    {
      "name": "loan officers"
    }
  ],
  "paths": {
    "/v1/loan-officers": {
      "get": {
        "operationId": "search_loan_officers",
        "tags": [
          "loan officers"
        ],
        "summary": "Find mortgage loan officers by state, city, ZIP, loan type or language",
        "description": "Returns up to 10 loan officers licensed in the state, for the loan type when one is given. city and zip do not filter: a license covers the whole state, so they only put loan officers with an office there first. total says how many match; moreResultsUrl is the full list on bluerate. Give the user each loan officer's url.",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": true,
            "description": "US state as a two-letter code (CA, TX). Full names such as California also work.",
            "schema": {
              "type": "string",
              "examples": [
                "CA"
              ]
            }
          },
          {
            "name": "city",
            "in": "query",
            "description": "City name. Puts loan officers with an office in this city first; does not filter.",
            "schema": {
              "type": "string",
              "maxLength": 80,
              "examples": [
                "San Jose"
              ]
            }
          },
          {
            "name": "zip",
            "in": "query",
            "description": "5-digit US ZIP code. Puts loan officers with an office in this ZIP code first; does not filter.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{5}(-[0-9]{4})?$",
              "examples": [
                "95112"
              ]
            }
          },
          {
            "name": "loanType",
            "in": "query",
            "description": "Only loan officers who do this loan type in the state. jumbo is not recorded per loan officer: it returns those licensed for conventional loans and says so in notice. Also accepted: nonqm, conforming, usda-rd.",
            "schema": {
              "type": "string",
              "enum": [
                "conventional",
                "fha",
                "va",
                "usda",
                "jumbo",
                "non_qm"
              ]
            }
          },
          {
            "name": "language",
            "in": "query",
            "description": "A language the loan officer speaks, as a name (Spanish, Chinese) or a code (es, zh).",
            "schema": {
              "type": "string",
              "examples": [
                "Spanish"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "How many loan officers to return.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10,
              "default": 10
            }
          },
          {
            "$ref": "#/components/parameters/client"
          },
          {
            "$ref": "#/components/parameters/clientHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Loan officers that match.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                },
                "example": {
                  "asOf": "2026-11-09T10:05:00Z",
                  "source": "bluerate.ai loan officer profiles (NMLS-verified listings), exported once a day",
                  "query": {
                    "state": "CA",
                    "city": "San Jose",
                    "loanType": "fha"
                  },
                  "total": 14,
                  "returned": 1,
                  "loanOfficers": [
                    {
                      "name": "Alex Rivera",
                      "nmls": "1234567",
                      "company": "Example Home Loans",
                      "officeCity": "San Jose",
                      "officeState": "CA",
                      "licensedStates": [
                        "CA",
                        "WA"
                      ],
                      "languages": [
                        "English",
                        "Spanish"
                      ],
                      "loanTypes": [
                        "conventional",
                        "fha",
                        "va",
                        "non_qm"
                      ],
                      "rating": null,
                      "reviewCount": 12,
                      "sponsored": false,
                      "url": "https://www.bluerate.ai/loan-officer/alex-rivera-nmls-1234567?utm_source=agent&utm_medium=my-agent&utm_campaign=api",
                      "callbackUrl": "https://www.bluerate.ai/loan-officer/alex-rivera-nmls-1234567?utm_source=agent&utm_medium=my-agent&utm_campaign=api&utm_content=callback"
                    }
                  ],
                  "moreResultsUrl": "https://www.bluerate.ai/loan-officers/san-jose-ca/fha?utm_source=agent&utm_medium=my-agent&utm_campaign=api"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidParameter"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/SnapshotUnavailable"
          }
        }
      }
    },
    "/v1/loan-officers/{nmls}": {
      "get": {
        "operationId": "get_loan_officer",
        "tags": [
          "loan officers"
        ],
        "summary": "Get one loan officer's profile by NMLS ID",
        "description": "The fields search returns, plus about, up to 3 reviews and the loan officer's own FAQs. Give the user the url.",
        "parameters": [
          {
            "name": "nmls",
            "in": "path",
            "required": true,
            "description": "The loan officer's NMLS ID, digits only. search_loan_officers returns it as nmls.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{1,10}$",
              "examples": [
                "1234567"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/client"
          },
          {
            "$ref": "#/components/parameters/clientHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "The loan officer.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetResponse"
                },
                "example": {
                  "asOf": "2026-11-09T10:05:00Z",
                  "source": "bluerate.ai loan officer profiles (NMLS-verified listings), exported once a day",
                  "loanOfficer": {
                    "name": "Alex Rivera",
                    "nmls": "1234567",
                    "company": "Example Home Loans",
                    "officeCity": "San Jose",
                    "officeState": "CA",
                    "licensedStates": [
                      "CA",
                      "WA"
                    ],
                    "languages": [
                      "English",
                      "Spanish"
                    ],
                    "loanTypes": [
                      "conventional",
                      "fha",
                      "va",
                      "non_qm"
                    ],
                    "rating": null,
                    "reviewCount": 12,
                    "sponsored": false,
                    "url": "https://www.bluerate.ai/loan-officer/alex-rivera-nmls-1234567?utm_source=agent&utm_medium=my-agent&utm_campaign=api",
                    "callbackUrl": "https://www.bluerate.ai/loan-officer/alex-rivera-nmls-1234567?utm_source=agent&utm_medium=my-agent&utm_campaign=api&utm_content=callback",
                    "about": "I help first-time buyers in the South Bay with FHA, VA and conventional loans.",
                    "reviews": [
                      {
                        "text": "Alex walked us through every step and closed on time.",
                        "author": "Maria G."
                      }
                    ],
                    "faqs": [
                      {
                        "question": "Do you work with first-time buyers?",
                        "answer": "Yes, most of my clients are first-time buyers."
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidParameter"
          },
          "404": {
            "description": "No loan officer with this NMLS ID is listed on bluerate.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "No loan officer with NMLS ID 1234567 is listed on bluerate.",
                    "hint": "Use search_loan_officers with a state to find loan officers who are listed."
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/SnapshotUnavailable"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "client": {
        "name": "client",
        "in": "query",
        "description": "Your agent's or app's name, for example my-agent. Optional; goes into the links' utm_medium and bluerate's usage counts. Without it, X-Client-Name and then the User-Agent are used.",
        "schema": {
          "type": "string",
          "maxLength": 40
        }
      },
      "clientHeader": {
        "name": "X-Client-Name",
        "in": "header",
        "description": "The same as client, as a header.",
        "schema": {
          "type": "string",
          "maxLength": 40
        }
      }
    },
    "headers": {
      "CacheControl": {
        "description": "public, max-age=300. The data changes once a day.",
        "schema": {
          "type": "string"
        }
      }
    },
    "responses": {
      "InvalidParameter": {
        "description": "A parameter is missing or wrong; error.hint says what to send instead.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "invalid_parameter",
                "message": "state is required.",
                "hint": "Pass state as a two-letter US state code, for example state=CA."
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Too many requests from this IP address (60 a minute without a key). Wait about a minute and try again.",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait.",
            "schema": {
              "type": "integer",
              "examples": [
                60
              ]
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Too many requests from this IP address (limit: 60 per minute).",
                "hint": "Wait about a minute and retry with fewer requests; cache results for 5 minutes (responses carry Cache-Control: max-age=300)."
              }
            }
          }
        }
      },
      "SnapshotUnavailable": {
        "description": "The loan officer list is not loaded yet (a new server). Try again later.",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait.",
            "schema": {
              "type": "integer",
              "examples": [
                600
              ]
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "snapshot_unavailable",
                "message": "The loan officer list is not loaded yet.",
                "hint": "Try again in a few minutes. Meanwhile, send the user to https://www.bluerate.ai/loan-officers to search."
              }
            }
          }
        }
      }
    },
    "schemas": {
      "LoanOfficer": {
        "type": "object",
        "description": "A loan officer listed on bluerate. No phone, email or street address: reach the loan officer through url or callbackUrl.",
        "required": [
          "name",
          "nmls",
          "company",
          "licensedStates",
          "languages",
          "loanTypes",
          "rating",
          "reviewCount",
          "sponsored",
          "url",
          "callbackUrl"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "nmls": {
            "type": "string",
            "description": "NMLS ID (Nationwide Multistate Licensing System), digits only."
          },
          "company": {
            "type": "string",
            "description": "The company the loan officer works for; may be empty."
          },
          "officeCity": {
            "type": "string",
            "description": "City of the company's office, when known."
          },
          "officeState": {
            "type": "string",
            "description": "Two-letter state of the company's office, when known."
          },
          "licensedStates": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Two-letter codes of the states the loan officer is licensed in."
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "loanTypes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "conventional",
                "fha",
                "va",
                "usda",
                "non_qm"
              ]
            }
          },
          "rating": {
            "type": [
              "number",
              "null"
            ],
            "description": "Always null for now: bluerate profiles carry no star rating."
          },
          "reviewCount": {
            "type": "integer",
            "description": "Client reviews shown on the profile."
          },
          "sponsored": {
            "type": "boolean",
            "description": "Whether payment affected this result's position. Always false: the order does not depend on payment."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The loan officer's bluerate profile. Give this to the user. Carries utm_source=agent, utm_medium=<client> and utm_campaign=api so bluerate can count visits from agents."
          },
          "callbackUrl": {
            "type": "string",
            "format": "uri",
            "description": "Where the user asks the loan officer to call back, on bluerate. Carries utm_source=agent, utm_medium=<client> and utm_campaign=api so bluerate can count visits from agents."
          }
        }
      },
      "Review": {
        "type": "object",
        "required": [
          "text",
          "author"
        ],
        "properties": {
          "text": {
            "type": "string",
            "description": "Up to 400 characters."
          },
          "author": {
            "type": "string",
            "description": "First name and last initial."
          }
        }
      },
      "FAQ": {
        "type": "object",
        "required": [
          "question",
          "answer"
        ],
        "properties": {
          "question": {
            "type": "string"
          },
          "answer": {
            "type": "string"
          }
        }
      },
      "LoanOfficerDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/LoanOfficer"
          },
          {
            "type": "object",
            "required": [
              "about",
              "reviews",
              "faqs"
            ],
            "properties": {
              "about": {
                "type": "string",
                "description": "The loan officer's own introduction, plain text, up to 1,500 characters."
              },
              "reviews": {
                "type": "array",
                "maxItems": 3,
                "items": {
                  "$ref": "#/components/schemas/Review"
                }
              },
              "faqs": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/FAQ"
                },
                "description": "Questions the loan officer answered on their profile."
              }
            }
          }
        ]
      },
      "SearchResponse": {
        "type": "object",
        "required": [
          "asOf",
          "source",
          "query",
          "total",
          "returned",
          "loanOfficers",
          "moreResultsUrl"
        ],
        "properties": {
          "asOf": {
            "type": "string",
            "format": "date-time",
            "description": "When the snapshot was taken (UTC)."
          },
          "source": {
            "type": "string",
            "description": "Where the data comes from."
          },
          "query": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "The search as understood: state as a code, loanType normalized."
          },
          "total": {
            "type": "integer",
            "description": "How many loan officers match."
          },
          "returned": {
            "type": "integer",
            "description": "How many are in loanOfficers (at most 10)."
          },
          "loanOfficers": {
            "type": "array",
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/LoanOfficer"
            }
          },
          "moreResultsUrl": {
            "type": "string",
            "format": "uri",
            "description": "The same search on bluerate, with every result. Carries utm_source=agent, utm_medium=<client> and utm_campaign=api so bluerate can count visits from agents."
          },
          "notice": {
            "type": "string",
            "description": "A note the user should hear, for example that jumbo is not recorded per loan officer, or how to widen a search with no results."
          }
        }
      },
      "GetResponse": {
        "type": "object",
        "required": [
          "asOf",
          "source",
          "loanOfficer"
        ],
        "properties": {
          "asOf": {
            "type": "string",
            "format": "date-time",
            "description": "When the snapshot was taken (UTC)."
          },
          "source": {
            "type": "string",
            "description": "Where the data comes from."
          },
          "loanOfficer": {
            "$ref": "#/components/schemas/LoanOfficerDetail"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "hint"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "invalid_parameter",
                  "not_found",
                  "rate_limited",
                  "snapshot_unavailable"
                ]
              },
              "message": {
                "type": "string",
                "description": "What went wrong."
              },
              "hint": {
                "type": "string",
                "description": "One sentence on what to send instead."
              }
            }
          }
        }
      }
    }
  }
}