> ## 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.

# Batch create/update patients

> Create or update up to 500 patients. Each row uses the same matching and update rules as POST /v1/patients/upsert: typed external ID, exact demographics, phone plus fuzzy name, then email plus fuzzy name. Rows are processed independently and returned in order.



## OpenAPI

````yaml https://api.getsolum.com/openapi.json post /v1/patients/batch
openapi: 3.1.0
info:
  title: Solum Health API
  description: '## Solum Health Backend API '
  version: 1.0.0
servers: []
security: []
paths:
  /v1/patients/batch:
    post:
      tags:
        - Patient Batch
      summary: Batch create/update patients
      description: >-
        Create or update up to 500 patients. Each row uses the same matching and
        update rules as POST /v1/patients/upsert: typed external ID, exact
        demographics, phone plus fuzzy name, then email plus fuzzy name. Rows
        are processed independently and returned in order.
      operationId: batch_create_patients_v1_patients_batch_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientBatchCreateRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatientBatchCreateResponse'
        '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:
    PatientBatchCreateRequest:
      properties:
        items:
          items:
            $ref: '#/components/schemas/PatientBatchItem'
          type: array
          maxItems: 500
          minItems: 1
          title: Items
      type: object
      required:
        - items
      title: PatientBatchCreateRequest
      description: Request body for batch patient creation.
    PatientBatchCreateResponse:
      properties:
        created_count:
          type: integer
          title: Created Count
        updated_count:
          type: integer
          title: Updated Count
          default: 0
        failed_count:
          type: integer
          title: Failed Count
          default: 0
        patient_ids:
          items:
            type: string
          type: array
          title: Patient Ids
        updated_patient_ids:
          items:
            type: string
          type: array
          title: Updated Patient Ids
        results:
          items:
            $ref: '#/components/schemas/PatientBatchRowResult'
          type: array
          title: Results
        insurance_created_count:
          type: integer
          title: Insurance Created Count
          default: 0
        insurance_updated_count:
          type: integer
          title: Insurance Updated Count
          default: 0
        insurance_unchanged_count:
          type: integer
          title: Insurance Unchanged Count
          default: 0
        insurance_unresolved_count:
          type: integer
          title: Insurance Unresolved Count
          default: 0
        insurance_incomplete_count:
          type: integer
          title: Insurance Incomplete Count
          default: 0
        insurance_failed_count:
          type: integer
          title: Insurance Failed Count
          default: 0
        insurance_not_processed_count:
          type: integer
          title: Insurance Not Processed Count
          default: 0
        insurance_not_provided_count:
          type: integer
          title: Insurance Not Provided Count
          default: 0
      additionalProperties: false
      type: object
      required:
        - created_count
        - patient_ids
      title: PatientBatchCreateResponse
      description: Response from batch patient creation/upsert.
    PatientBatchItem:
      properties:
        first_name:
          anyOf:
            - {}
            - type: 'null'
          title: First Name
        last_name:
          anyOf:
            - {}
            - type: 'null'
          title: Last Name
        middle_name:
          anyOf:
            - {}
            - type: 'null'
          title: Middle Name
        phone_number:
          anyOf:
            - {}
            - type: 'null'
          title: Phone Number
        additional_phone_number:
          anyOf:
            - {}
            - type: 'null'
          title: Additional Phone Number
        email:
          anyOf:
            - {}
            - type: 'null'
          title: Email
        date_of_birth:
          anyOf:
            - {}
            - type: 'null'
          title: Date Of Birth
        gender:
          anyOf:
            - {}
            - type: 'null'
          title: Gender
        address:
          anyOf:
            - {}
            - type: 'null'
          title: Address
        address2:
          anyOf:
            - {}
            - type: 'null'
          title: Address2
        city:
          anyOf:
            - {}
            - type: 'null'
          title: City
        state:
          anyOf:
            - {}
            - type: 'null'
          title: State
        zip:
          anyOf:
            - {}
            - type: 'null'
          title: Zip
        comments:
          anyOf:
            - {}
            - type: 'null'
          title: Comments
        workflow_stage_id:
          anyOf:
            - {}
            - type: 'null'
          title: Workflow Stage Id
        assigned_user_id:
          anyOf:
            - {}
            - type: 'null'
          title: Assigned User Id
        location_id:
          anyOf:
            - {}
            - type: 'null'
          title: Location Id
        organization_id:
          anyOf:
            - {}
            - type: 'null'
          title: Organization Id
        tags:
          anyOf:
            - {}
            - type: 'null'
          title: Tags
        referral:
          anyOf:
            - {}
            - type: 'null'
          title: Referral
        custom_fields:
          anyOf:
            - {}
            - type: 'null'
          title: Custom Fields
        created_from:
          anyOf:
            - {}
            - type: 'null'
          title: Created From
        external_id_type:
          anyOf:
            - {}
            - type: 'null'
          title: External Id Type
        external_id:
          anyOf:
            - {}
            - type: 'null'
          title: External Id
        payors:
          anyOf:
            - {}
            - type: 'null'
          title: Payors
          description: Payors with insurance name lookup
      type: object
      title: PatientBatchItem
      description: Forgiving batch row; detailed validation is reported per row.
    PatientBatchRowResult:
      properties:
        row:
          type: integer
          title: Row
        patient_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Patient Id
        created:
          type: boolean
          title: Created
          default: false
        matched:
          type: boolean
          title: Matched
          default: false
        match_reason:
          anyOf:
            - type: string
              enum:
                - external_id
                - demographics
                - phone_fuzzy_name
                - email_fuzzy_name
            - type: 'null'
          title: Match Reason
        dropped_fields:
          items:
            type: string
          type: array
          title: Dropped Fields
        insurance_status:
          $ref: '#/components/schemas/BatchInsuranceStatus'
          default: not_provided
        payor_results:
          items:
            $ref: '#/components/schemas/PayorProcessingResult'
          type: array
          title: Payor Results
        error:
          anyOf:
            - $ref: '#/components/schemas/PatientBatchRowError'
            - type: 'null'
      additionalProperties: false
      type: object
      required:
        - row
      title: PatientBatchRowResult
      description: Outcome for one one-based CSV row.
    BatchInsuranceStatus:
      type: string
      enum:
        - not_provided
        - complete
        - partial
        - needs_review
        - not_processed
      title: BatchInsuranceStatus
    PayorProcessingResult:
      properties:
        payor_responsibility:
          anyOf:
            - $ref: '#/components/schemas/InsuranceTier'
            - type: 'null'
        submitted_insurance_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Submitted Insurance Name
        resolved_insurance_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Resolved Insurance Id
        resolved_insurance_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Resolved Insurance Name
        trading_partner_service_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Trading Partner Service Id
        payor_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Payor Id
        coverage_chain_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Coverage Chain Id
        outcome:
          $ref: '#/components/schemas/PayorProcessingOutcome'
        resolution_method:
          anyOf:
            - $ref: '#/components/schemas/InsuranceResolutionMethod'
            - type: 'null'
        reason_code:
          anyOf:
            - $ref: '#/components/schemas/PayorProcessingReason'
            - type: 'null'
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
      additionalProperties: false
      type: object
      required:
        - outcome
      title: PayorProcessingResult
      description: One ordered submitted-coverage outcome, excluding PHI and internals.
    PatientBatchRowError:
      properties:
        type:
          type: string
          title: Type
        code:
          type: string
          title: Code
        message:
          type: string
          title: Message
        param:
          anyOf:
            - type: string
            - type: 'null'
          title: Param
      additionalProperties: true
      type: object
      required:
        - type
        - code
        - message
      title: PatientBatchRowError
      description: Standard API error detail captured for a single batch row.
    InsuranceTier:
      type: string
      enum:
        - primary
        - secondary
        - tertiary
        - quaternary
      title: InsuranceTier
      description: Insurance tier enum matching Prisma
    PayorProcessingOutcome:
      type: string
      enum:
        - created
        - updated
        - unchanged
        - unresolved
        - incomplete
        - failed
        - not_processed
      title: PayorProcessingOutcome
    InsuranceResolutionMethod:
      type: string
      enum:
        - canonical_name
        - alias
        - state_variant
        - ai
      title: InsuranceResolutionMethod
      description: How a configured insurance was selected.
    PayorProcessingReason:
      type: string
      enum:
        - insurance_name_missing
        - no_configured_match
        - configured_insurance_inactive
        - insurance_not_vob_ready
        - ambiguous_match
        - match_confidence_too_low
        - resolution_unavailable
        - persistence_failed
        - patient_row_failed
      title: PayorProcessingReason
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    HTTPBearer:
      type: http
      scheme: bearer

````