openapi: 3.0.0
info:
  version: 1.0.0
  title: HMDA Platform Filing API
  description: Enables financial institutions to submit Home Mortgage Disclosure Act (HMDA) data programmatically to the FFIEC HMDA Platform. Provides endpoints for filing submissions, uploading loan application register (LAR) files, checking submission status, and retrieving edit reports for regulatory compliance.
  contact:
    name: FFIEC HMDA Help
    url: https://ffiec.cfpb.gov/
  license:
    name: Creative Commons CC0
    url: https://creativecommons.org/publicdomain/zero/1.0/
servers:
  - url: 'https://ffiec.cfpb.gov'
    description: Production server
tags:
  - name: Health
    description: Service health check
  - name: Institutions
    description: Financial institution information
  - name: Filings
    description: HMDA filing management
  - name: Submissions
    description: HMDA data submission management
  - name: Edits
    description: Submission edit and validation reports
security:
  - bearerAuth: []
paths:
  /:
    get:
      tags:
        - Health
      summary: Service health check
      description: Returns the health status of the HMDA Platform Filing API
      security: []
      responses:
        '200':
          description: Service is running
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
  /institutions/{lei}:
    get:
      tags:
        - Institutions
      summary: Get institution by LEI
      description: Returns institution details and list of filings for the given Legal Entity Identifier
      parameters:
        - $ref: '#/components/parameters/lei'
      responses:
        '200':
          description: Institution details with filings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Institution'
        '404':
          description: Institution not found
  /institutions/{lei}/filings/{period}:
    get:
      tags:
        - Filings
      summary: Get filing for institution and period
      description: Returns filing details and submission list for an institution in a given filing period
      parameters:
        - $ref: '#/components/parameters/lei'
        - $ref: '#/components/parameters/period'
      responses:
        '200':
          description: Filing details with submissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Filing'
        '404':
          description: Filing not found
    post:
      tags:
        - Filings
      summary: Create filing for institution and period
      description: Creates a new filing for an institution for the given period
      parameters:
        - $ref: '#/components/parameters/lei'
        - $ref: '#/components/parameters/period'
      responses:
        '201':
          description: Filing created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Filing'
        '400':
          description: Bad request
  /institutions/{lei}/filings/{period}/submissions:
    post:
      tags:
        - Submissions
      summary: Create new submission
      description: Creates a new submission for the filing identified by LEI and period
      parameters:
        - $ref: '#/components/parameters/lei'
        - $ref: '#/components/parameters/period'
      responses:
        '201':
          description: Submission created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Submission'
        '400':
          description: Bad request
  /institutions/{lei}/filings/{period}/submissions/latest:
    get:
      tags:
        - Submissions
      summary: Get latest submission
      description: Returns the most recent submission for the given institution and filing period
      parameters:
        - $ref: '#/components/parameters/lei'
        - $ref: '#/components/parameters/period'
      responses:
        '200':
          description: Latest submission details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Submission'
        '404':
          description: No submissions found
  /institutions/{lei}/filings/{period}/submissions/{submissionId}:
    post:
      tags:
        - Submissions
      summary: Upload HMDA data file
      description: Uploads a HMDA LAR (Loan Application Register) file for the given submission
      parameters:
        - $ref: '#/components/parameters/lei'
        - $ref: '#/components/parameters/period'
        - $ref: '#/components/parameters/submissionId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: HMDA LAR file (pipe-delimited format)
      responses:
        '200':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Submission'
        '400':
          description: Invalid file format
        '404':
          description: Submission not found
  /institutions/{lei}/filings/{period}/submissions/{submissionId}/parseErrors:
    get:
      tags:
        - Edits
      summary: Get parse errors for submission
      description: Returns parse errors for the transmittal sheet and LAR records in a submission
      parameters:
        - $ref: '#/components/parameters/lei'
        - $ref: '#/components/parameters/period'
        - $ref: '#/components/parameters/submissionId'
        - name: page
          in: query
          description: Page number (page size is 20)
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: Parse errors with pagination metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParseErrors'
        '404':
          description: Submission not found
  /institutions/{lei}/filings/{period}/submissions/{submissionId}/edits:
    get:
      tags:
        - Edits
      summary: Get all edits for submission
      description: Returns edits grouped by type (syntactical, validity, quality, macro) for a submission
      parameters:
        - $ref: '#/components/parameters/lei'
        - $ref: '#/components/parameters/period'
        - $ref: '#/components/parameters/submissionId'
      responses:
        '200':
          description: Edits grouped by type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Edits'
        '404':
          description: Submission not found
  /institutions/{lei}/filings/{period}/submissions/{submissionId}/edits/{editType}:
    post:
      tags:
        - Edits
      summary: Verify quality or macro edits
      description: Marks quality or macro edits as verified for a submission
      parameters:
        - $ref: '#/components/parameters/lei'
        - $ref: '#/components/parameters/period'
        - $ref: '#/components/parameters/submissionId'
        - name: editType
          in: path
          required: true
          description: The type of edit to verify (quality or macro)
          schema:
            type: string
            enum:
              - quality
              - macro
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                verified:
                  type: boolean
                  description: Whether the edits have been verified
      responses:
        '200':
          description: Edit verification status updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EditVerification'
        '404':
          description: Submission not found
  /institutions/{lei}/filings/{period}/submissions/{submissionId}/edits/{editName}:
    get:
      tags:
        - Edits
      summary: Get edit details
      description: Returns details for a specific edit including affected rows, field names and values, and pagination links
      parameters:
        - $ref: '#/components/parameters/lei'
        - $ref: '#/components/parameters/period'
        - $ref: '#/components/parameters/submissionId'
        - name: editName
          in: path
          required: true
          description: The name of the specific edit
          schema:
            type: string
      responses:
        '200':
          description: Edit details with affected rows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EditDetail'
        '404':
          description: Edit not found
  /institutions/{lei}/filings/{period}/submissions/{submissionId}/sign:
    get:
      tags:
        - Submissions
      summary: Get submission signature receipt
      description: Returns the signature receipt for a submission
      parameters:
        - $ref: '#/components/parameters/lei'
        - $ref: '#/components/parameters/period'
        - $ref: '#/components/parameters/submissionId'
      responses:
        '200':
          description: Submission receipt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignatureReceipt'
        '404':
          description: Submission not found
    post:
      tags:
        - Submissions
      summary: Sign submission
      description: Signs and finalizes a submission after all edits have been verified
      parameters:
        - $ref: '#/components/parameters/lei'
        - $ref: '#/components/parameters/period'
        - $ref: '#/components/parameters/submissionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signed:
                  type: boolean
                  description: Whether the submission is being signed
      responses:
        '200':
          description: Submission signed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignatureReceipt'
        '400':
          description: Submission cannot be signed (edits not verified)
        '404':
          description: Submission not found
  /institutions/{lei}/filings/{period}/submissions/{submissionId}/summary:
    get:
      tags:
        - Submissions
      summary: Get submission summary
      description: Returns submission details plus transmittal sheet information
      parameters:
        - $ref: '#/components/parameters/lei'
        - $ref: '#/components/parameters/period'
        - $ref: '#/components/parameters/submissionId'
      responses:
        '200':
          description: Submission summary with transmittal sheet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionSummary'
        '404':
          description: Submission not found
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    lei:
      name: lei
      in: path
      required: true
      description: Legal Entity Identifier of the financial institution
      schema:
        type: string
        example: B90YWS6AFX2LGWOXJ1LD
    period:
      name: period
      in: path
      required: true
      description: Filing period (year, e.g. 2020)
      schema:
        type: string
        example: '2020'
    submissionId:
      name: submissionId
      in: path
      required: true
      description: Submission identifier
      schema:
        type: string
        example: B90YWS6AFX2LGWOXJ1LD-2020-1
  schemas:
    HealthStatus:
      type: object
      properties:
        status:
          type: string
          description: Service name
        service:
          type: string
          description: Service name
        timestamp:
          type: string
          format: date-time
          description: Current timestamp
        host:
          type: string
          description: Host name
    Institution:
      type: object
      properties:
        lei:
          type: string
          description: Legal Entity Identifier
        agencyCode:
          type: integer
          description: Agency code
        activityYear:
          type: integer
          description: Activity year
        institutionType:
          type: integer
          description: Institution type code
        hmdaFiler:
          type: boolean
          description: Whether institution is a HMDA filer
        respondentName:
          type: string
          description: Name of the responding institution
        filings:
          type: array
          items:
            $ref: '#/components/schemas/FilingSummary'
    FilingSummary:
      type: object
      properties:
        period:
          type: string
          description: Filing period year
        lei:
          type: string
          description: Legal Entity Identifier
        status:
          $ref: '#/components/schemas/FilingStatus'
    Filing:
      type: object
      properties:
        period:
          type: string
          description: Filing period year
        lei:
          type: string
          description: Legal Entity Identifier
        status:
          $ref: '#/components/schemas/FilingStatus'
        submissions:
          type: array
          items:
            $ref: '#/components/schemas/SubmissionSummary'
    FilingStatus:
      type: object
      properties:
        code:
          type: integer
          description: Status code
        message:
          type: string
          description: Status message
    Submission:
      type: object
      properties:
        id:
          type: string
          description: Submission identifier
        status:
          $ref: '#/components/schemas/SubmissionStatus'
        start:
          type: integer
          format: int64
          description: Unix timestamp when submission started
        end:
          type: integer
          format: int64
          description: Unix timestamp when submission ended
    SubmissionStatus:
      type: object
      properties:
        code:
          type: integer
          description: Status code
        message:
          type: string
          description: Status message
    SubmissionSummary:
      type: object
      properties:
        submission:
          $ref: '#/components/schemas/Submission'
        transmittalSheet:
          $ref: '#/components/schemas/TransmittalSheet'
    TransmittalSheet:
      type: object
      properties:
        institutionName:
          type: string
          description: Name of the institution
        year:
          type: integer
          description: Activity year
        quarter:
          type: integer
          description: Quarter (if quarterly filing)
        lei:
          type: string
          description: Legal Entity Identifier
        taxId:
          type: string
          description: Tax ID
        totalLines:
          type: integer
          description: Total number of LAR lines
        contact:
          type: object
          properties:
            name:
              type: string
            phone:
              type: string
            email:
              type: string
            address:
              type: object
    ParseErrors:
      type: object
      properties:
        transmittalSheetErrors:
          type: array
          items:
            type: string
          description: Errors in the transmittal sheet
        larErrors:
          type: array
          items:
            type: object
            properties:
              lineNumber:
                type: integer
              errors:
                type: array
                items:
                  type: string
        count:
          type: integer
          description: Total number of errors
        total:
          type: integer
          description: Total number of records with errors
        _links:
          $ref: '#/components/schemas/PaginationLinks'
    Edits:
      type: object
      properties:
        syntactical:
          $ref: '#/components/schemas/EditGroup'
        validity:
          $ref: '#/components/schemas/EditGroup'
        quality:
          $ref: '#/components/schemas/EditGroup'
        macro:
          $ref: '#/components/schemas/EditGroup'
    EditGroup:
      type: object
      properties:
        edits:
          type: array
          items:
            $ref: '#/components/schemas/Edit'
        verified:
          type: boolean
          description: Whether these edits have been verified (quality and macro only)
    Edit:
      type: object
      properties:
        edit:
          type: string
          description: Edit name/code
        description:
          type: string
          description: Edit description
        rows:
          type: array
          items:
            type: object
            additionalProperties: true
    EditDetail:
      type: object
      properties:
        edit:
          type: string
          description: Edit name
        rows:
          type: array
          items:
            type: object
            additionalProperties: true
        _links:
          $ref: '#/components/schemas/PaginationLinks'
    EditVerification:
      type: object
      properties:
        verified:
          type: boolean
          description: Whether the edits are verified
        status:
          $ref: '#/components/schemas/SubmissionStatus'
    SignatureReceipt:
      type: object
      properties:
        timestamp:
          type: integer
          format: int64
          description: Unix timestamp of signing
        receipt:
          type: string
          description: Receipt code
        status:
          $ref: '#/components/schemas/SubmissionStatus'
    PaginationLinks:
      type: object
      properties:
        href:
          type: string
          description: Template URL for pagination
        self:
          type: string
          description: URL for current page
        next:
          type: string
          description: URL for next page
        prev:
          type: string
          description: URL for previous page
        first:
          type: string
          description: URL for first page
        last:
          type: string
          description: URL for last page