> ## Documentation Index
> Fetch the complete documentation index at: https://hc.starbridge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Buyers

> Search for buyer institutions — cities, counties, school districts, higher-education institutions, police and fire departments, federal agencies, and other public-sector entities — by name. Returns a list of candidates; pick the single buyer that best fits the user's intent based on name, type, and location, then use its `id` (the buyer ID) for downstream tools. If the user mentions a state or province, pass `buyerStateCode` as the matching `StateMapping` enum name (the server resolves it to the corresponding ISO 3166-2 code).



## OpenAPI

````yaml https://core-http2-157602306522.us-central1.run.app/external/public/swagger/documentation.yaml get /api/external/buyer/quick/search
openapi: 3.1.1
info:
  title: Starbridge External Public API
  version: '1.0'
servers:
  - url: https://dashboard.starbridge.ai
security: []
paths:
  /api/external/buyer/quick/search:
    get:
      tags:
        - Buyer
        - External MCP
        - External API
      summary: Search Buyers
      description: >-
        Search for buyer institutions — cities, counties, school districts,
        higher-education institutions, police and fire departments, federal
        agencies, and other public-sector entities — by name. Returns a list of
        candidates; pick the single buyer that best fits the user's intent based
        on name, type, and location, then use its `id` (the buyer ID) for
        downstream tools. If the user mentions a state or province, pass
        `buyerStateCode` as the matching `StateMapping` enum name (the server
        resolves it to the corresponding ISO 3166-2 code).
      operationId: searchBuyers
      parameters:
        - name: buyerName
          in: query
          description: Buyer name to search Buyer entity by.
          required: true
          schema:
            type: string
        - name: buyerStateCode
          in: query
          description: >-
            StateMapping enum value for the buyer's ISO 3166-2 state code.
            Optional.
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of buyers to return. Defaults to 10.
          schema:
            type: string
      responses:
        '200':
          description: Matching buyers ordered by relevance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerSearchResponse'
        '400':
          description: Invalid request body or format
        '401':
          description: Missing or invalid authentication
        '403':
          description: Unauthorized to access resource or perform action
        '404':
          description: Resource not found
        '415':
          description: Unsupported media type or request body format
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
      security:
        - apiKey: []
components:
  schemas:
    BuyerSearchResponse:
      type: object
      title: BuyerSearchResponse
      required:
        - buyers
      properties:
        buyers:
          type: array
          description: >-
            Matching buyers (institutions) ordered by search relevance. Pick the
            single buyer that best fits the user's intent.
          items:
            $ref: '#/components/schemas/BuyerBrief'
    BuyerBrief:
      type: object
      title: BuyerBrief
      required:
        - id
        - name
        - countryCode
        - fromSourceFile
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        type:
          type:
            - string
            - 'null'
          enum:
            - AdministrativeAgency
            - City
            - CityAttorney
            - CityClerk
            - CityEngineer
            - CityManager
            - CitySecretary
            - County
            - CountyAttorney
            - CountyClerk
            - CountyEngineer
            - CountyManager
            - CulturalFacility
            - Department
            - DiplomaticEntity
            - District
            - FinancialAgency
            - HealthcareFacility
            - HigherEducation
            - LawEnforcementAgency
            - LegislativeBody
            - MilitaryOrganization
            - NonProfitOrganization
            - PrivateCompany
            - PublicWorksAgency
            - RegulatoryAgency
            - School
            - SchoolDistrict
            - SpecialDistrict
            - State
            - StateAgency
            - StateAttorney
            - StateClerk
            - StateEngineer
            - TransportationAgency
            - UncategorizedAgency
            - UncategorizedClerk
            - UncategorizedDistrict
            - PoliceDepartment
            - FireDepartment
            - Library
            - IndigenousGovernment
            - Federal
            - Other
        countryCode:
          type: string
        stateCode:
          type:
            - string
            - 'null'
        url:
          type:
            - string
            - 'null'
        fromSourceFile:
          type: boolean
        tags:
          type: array
          items:
            type: string
        linkedinSlug:
          type:
            - string
            - 'null'
        logoPath:
          type:
            - string
            - 'null'
  securitySchemes:
    apiKey:
      scheme: bearer
      description: HTTP Bearer Authentication
      type: http

````