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

# Match Suggestion (no-write)

> Run the patient matcher against caller-supplied identifiers and return the verdict. Never persists. The verdict's `kind` tells the caller how to render its picker: `hard` (lock — external-id / name+DOB uniqueness), `medium` (pre-fill with override — phone/email + name heuristic), `soft` (pre-fill, confirm — a single same-name patient with no date of birth to confirm), or `none`. Used by the file detail page to lock or pre-fill its patient picker, and by future eligibility / prior-auth extraction surfaces. Identifiers are normalized with the same forgiving parsers the upsert endpoint uses, so callers can pass raw values from extracted document data.



## OpenAPI

````yaml https://api.getsolum.com/openapi.json post /v1/patients/match-suggestion
openapi: 3.1.0
info:
  title: Solum Health API
  description: '## Solum Health Backend API '
  version: 1.0.0
servers: []
security: []
paths:
  /v1/patients/match-suggestion:
    post:
      tags:
        - Patients
      summary: Match Suggestion (no-write)
      description: >-
        Run the patient matcher against caller-supplied identifiers and return
        the verdict. Never persists. The verdict's `kind` tells the caller how
        to render its picker: `hard` (lock — external-id / name+DOB uniqueness),
        `medium` (pre-fill with override — phone/email + name heuristic), `soft`
        (pre-fill, confirm — a single same-name patient with no date of birth to
        confirm), or `none`. Used by the file detail page to lock or pre-fill
        its patient picker, and by future eligibility / prior-auth extraction
        surfaces. Identifiers are normalized with the same forgiving parsers the
        upsert endpoint uses, so callers can pass raw values from extracted
        document data.
      operationId: get_patient_match_suggestion_v1_patients_match_suggestion_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MatchSuggestionRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchSuggestionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: validation_error
                  code:
                    type: string
                    example: invalid_parameter
                  message:
                    type: string
                    example: Field validation failed
                  param:
                    type: string
                    example: phone_number
                required:
                  - type
                  - code
                  - message
      security:
        - APIKeyHeader: []
        - HTTPBearer: []
components:
  schemas:
    MatchSuggestionRequest:
      properties:
        external_id:
          anyOf:
            - $ref: '#/components/schemas/ExternalIdInput'
            - type: 'null'
          description: External-id pair. Tier 1 of the matcher when supplied.
        first_name:
          anyOf:
            - type: string
            - type: 'null'
          title: First Name
        last_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Name
        date_of_birth:
          anyOf:
            - type: string
            - type: 'null'
          title: Date Of Birth
          description: >-
            DOB in any of: YYYY-MM-DD, YYYYMMDD, MM/DD/YYYY, MM-DD-YYYY,
            MM/DD/YY. Unparseable values are ignored.
        phone_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone Number
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
      additionalProperties: false
      type: object
      title: MatchSuggestionRequest
      description: |-
        Identifiers the matcher will resolve to a patient.

        Forgiving on the wire — same `parse_*_safe` normalizers the upsert
        endpoint runs, so a partly-formatted phone or a free-text DOB still
        matches. Pass raw values from extracted document data, form fields,
        or eligibility payloads — the service normalizes before calling the
        matcher. Empty/missing fields are skipped (matcher tiers gate on
        presence, so unsupplied identifiers just narrow the tier set).
    MatchSuggestionResponse:
      properties:
        kind:
          type: string
          enum:
            - hard
            - medium
            - soft
            - none
          title: Kind
          description: >-
            How the caller should render the picker: `hard` = lock to the
            matched patient (DB-enforced uniqueness leaves exactly one valid
            choice); `medium` = pre-fill with override (contact-channel
            heuristic); `soft` = pre-fill with override (name-only suggestion,
            confirm before use); `none` = free.
        reason:
          anyOf:
            - type: string
              enum:
                - external_id
                - demographics
                - phone_fuzzy_name
                - email_fuzzy_name
            - type: string
              const: name_only
            - type: 'null'
          title: Reason
          description: >-
            Which matcher tier resolved the patient (`external_id`,
            `demographics`, `phone_fuzzy_name`, `email_fuzzy_name`,
            `name_only`). Null when `kind` is `none`.
        patient:
          anyOf:
            - $ref: '#/components/schemas/MatchSuggestionPatient'
            - type: 'null'
          description: >-
            The matched patient when `kind` is `hard`, `medium`, or `soft`; null
            otherwise.
      additionalProperties: false
      type: object
      required:
        - kind
      title: MatchSuggestionResponse
      description: >-
        Matcher verdict + optional slim patient. Never includes side-effect
        data.
    ExternalIdInput:
      properties:
        type_id:
          type: string
          format: uuid
          title: Type Id
          description: external_id_types.id (must belong to caller's company)
        value:
          type: string
          maxLength: 500
          minLength: 1
          title: Value
          description: External identifier value
      additionalProperties: false
      type: object
      required:
        - type_id
        - value
      title: ExternalIdInput
      description: External-id pair used for matching and (optionally) record creation.
    MatchSuggestionPatient:
      properties:
        id:
          type: string
          title: Id
        first_name:
          anyOf:
            - type: string
            - type: 'null'
          title: First Name
        last_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Name
        phone_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone Number
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
        day_of_birth:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Day Of Birth
        workflow_stage:
          anyOf:
            - $ref: '#/components/schemas/WorkflowStageSummary'
            - type: 'null'
        active:
          type: boolean
          title: Active
          default: true
      type: object
      required:
        - id
      title: MatchSuggestionPatient
      description: |-
        Slim patient surface for the suggestion response.

        The full `Patient` schema includes nested expansions (payors, referrals,
        custom_fields, external_id_values) that callers of the suggestion
        endpoint don't need — they're picking lock vs suggest vs free, not
        rendering the patient detail page. Keeping this narrow keeps the
        response payload small and the contract stable as `Patient` evolves.
    WorkflowStageSummary:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        actions:
          anyOf:
            - items:
                $ref: '#/components/schemas/WorkflowStageAction'
              type: array
            - type: 'null'
          title: Actions
        order:
          anyOf:
            - type: integer
            - type: 'null'
          title: Order
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
      type: object
      required:
        - id
      title: WorkflowStageSummary
      description: Lightweight workflow stage for patient expansion responses.
    WorkflowStageAction:
      type: string
      enum:
        - verify_insurance
        - sync_external
        - complete_verification
      title: WorkflowStageAction
      description: Actions that can be triggered when a patient enters a stage.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    HTTPBearer:
      type: http
      scheme: bearer

````