Fincura Files API

openapi: 3.0.2
info:
  title: Automated Spreading and Analysis Api-Key Files API
  version: 1.3.1
  description: "This [REST API](https://en.wikipedia.org/wiki/Representational_state_transfer) allows you to interact with the Automated Spreading processing and insights engine. \n\n# Authentication\n\nThis API uses API keys generated from a Automated Spreading User account. To get access to your User account, speak with your Automated Spreading account manager.\n\n# Accepted Media Types\n\n| File Type      | Extension(s)     | Content-Type(s) |\n| -------------------------------- |-------------- | ------------ |\n| PDF File | .pdf | `application/pdf` , `application/x-pdf` |\n| Excel File | .xls | `application/vnd.ms-excel`  |\n| Excel File | .xlsx | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`  |\n| Excel File | .xlsm | `application/vnd.ms-excel.sheet.macroEnabled.12`  |\n| PNG Image | .png | `image/png`  |\n| GIF Image | .gif | `image/gif`  |\n| JPG Image | .jpg, .jpeg | `image/jpeg`  |\n| GIF Image | .gif | `image/gif`  |\n| JSON File | .json | `application/json`  |\n\n\n# Getting Started\n\n1. [Create a Borrower](#operation/createBorrower) \n2. [Add a file](#operation/createDocumentFile) for that Borrower.\n3. Analyze in the Automated Spreading App\n\n****"
  x-logo:
    url: https://manual-public-web-static-resources.s3.amazonaws.com/public-api/Moodys-icon.svg
  contact:
    name: Moody's Automated Spreading Customer Support
    email: MA_NMR_Support@moodys.com
security:
- API_Key: []
tags:
- name: Files
  description: Files serve as the source input data for our insights engine. They are represented by a `DocumentFile` record.
paths:
  /v1/document-file:
    get:
      operationId: listDocumentFiles
      description: List files submitted to Fincura
      parameters:
      - name: limit
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - name: offset
        required: false
        in: query
        description: The initial index from which to return the results.
        schema:
          type: integer
      - name: borrower_uuid
        required: false
        in: query
        description: Borrower to filter results for
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                required:
                - count
                - results
                properties:
                  count:
                    type: integer
                    example: 123
                  next:
                    type: string
                    nullable: true
                    format: uri
                    example: http://api.example.org/accounts/?offset=400&limit=100
                  previous:
                    type: string
                    nullable: true
                    format: uri
                    example: http://api.example.org/accounts/?offset=200&limit=100
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/DocumentFileRead'
          description: ''
      tags:
      - Files
      summary: List DocumentFile records
    post:
      operationId: createDocumentFile
      description: "Add a new file to Fincura for processing.\n\nThe minimal document creation request requires just a `borrower_uuid` and the `media_type` of the file to process.\n\n\n    POST /v1/document-file HTTP/1.1\n    Host: api.amer.spreading.moodysanalytics.com\n    Accept: application/json\n    Authorization: Bearer eyJ0e...nFTRKTbcg\n    Content-Type: application/json\n\n    {\n        \"borrower_uuid\": \"6e64724a-25fc-4e1a-8071-1ef29845ab1d\",\n        \"media_type\": \"application/pdf\"\n    }\n    \n\nThe above request will create a new document record in Fincura and return a url to send the file to, as seen below.\n\n    {\n        \"uuid\": \"f67a21dd-32a0-4664-9cd4-4181640be400\",\n        \"upload_url\": \"https://upload.fincura.com/f67a21dd-32a0-4664-9cd4-4181640be400/document.pdf?signature=mWFg4xsgm4EtFEt\"\n    }\n\nIn a subsequent request, the file can be sent to the `upload_url` via [HTTP PUT](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT). The `Content-Length` and `Content-Type` headers are required. The `Content-Type` should match the `media_type` from the previous request.\n\n    PUT /f67a21dd-32a0-4664-9cd4-4181640be400/document.pdf?signature=mWFg4xsgm4EtFEt HTTP/1.1\n    Host: upload.fincura.com\n    Content-Length: 18828\n    Content-Type: application/pdf\n    \n    {FILE  DATA}\n\nFincura will begin processing the file once it has been completely uploaded.\n\nAdditional fields described below:"
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentFileCreate'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DocumentFileCreate'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DocumentFileCreate'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentFileCreate'
          description: ''
        429:
          content:
            application/json:
              schema:
                properties:
                  details:
                    type: string
                    example: Request was throttled. Expected available in 35 seconds.
          description: Rate Limit
      tags:
      - Files
      summary: Submit a new DocumentFile
  /v1/document-file/{uuid}:
    get:
      operationId: retrieveDocumentFile
      description: Retrieve a file submitted to Fincura
      parameters:
      - name: uuid
        in: path
        required: true
        description: ''
        schema:
          type: string
      - name: borrower_uuid
        required: false
        in: query
        description: Borrower to filter results for
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentFileRead'
          description: ''
      tags:
      - Files
      summary: Get a DocumentFile
    delete:
      operationId: destroyDocumentFile
      description: Delete a file from Fincura.
      parameters:
      - name: uuid
        in: path
        required: true
        description: ''
        schema:
          type: string
      - name: borrower_uuid
        required: false
        in: query
        description: Borrower to filter results for
        schema:
          type: string
      responses:
        '204':
          description: ''
      tags:
      - Files
      summary: Delete a DocumentFile
  /v1/bulk-file/{uuid}:
    get:
      operationId: retrieveBulkFile
      description: Retrieve a bulk file submitted to Fincura
      parameters:
      - name: uuid
        in: path
        required: true
        description: ''
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkFileRead'
          description: ''
      tags:
      - Files
      summary: Retrieve a BulkFile
  /v1/bulk-file:
    post:
      operationId: createBulkFile
      description: "Add a new file to Fincura that maps to many borrowers. Requires use of a specific file processor per file format. Speak with you Fincura account manager about available options on your account.\n\n\n    POST /v1/bulk-file HTTP/1.1\n    Host: api.amer.spreading.moodysanalytics.com\n    Accept: application/json\n    Authorization: Bearer eyJ0e...nFTRKTbcg\n    Content-Type: application/json\n\n    {\n        \"processor_key\": \"6e64724a-25fc-4e1a-8071-1ef29845ab1d\",\n        \"media_type\": \"application/pdf\"\"\n    }\n    \n\nThe above request will create a new document record in Fincura and return a url to send the file to, as seen below.\n\n    {\n        \"uuid\": \"d789dfd5-42ee-46df-99f2-e6725bee9678\",\n        \"upload_url\": \"https://upload.fincura.com/d789dfd5-42ee-46df-99f2-e6725bee9678/document.pdf?signature=mWFg4xsgm4EtFEt\"\n    }\n\nIn a subsequent request, the file can be sent to the `upload_url` via [HTTP PUT](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT). The `Content-Length` and `Content-Type` headers are required. The `Content-Type` should match the `media_type` from the previous request.\n\n    PUT /d789dfd5-42ee-46df-99f2-e6725bee9678/document.pdf?signature=mWFg4xsgm4EtFEt HTTP/1.1\n    Host: upload.fincura.com\n    Content-Length: 18828\n    Content-Type: application/pdf\n    \n    {FILE  DATA}\n\nFincura will begin processing the file once it has been completely uploaded."
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkFileCreate'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/BulkFileCreate'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/BulkFileCreate'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkFileCreate'
          description: ''
      tags:
      - Files
      summary: Submit a new BulkFile
components:
  schemas:
    BulkFileCreate:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          readOnly: true
        status:
          type: string
          readOnly: true
        created_date:
          type: string
          format: date-time
          readOnly: true
        media_type:
          enum:
          - application/pdf
          - application/x-pdf
          - application/vnd.ms-excel
          - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
          - application/vnd.ms-excel.sheet.macroEnabled.12
          - image/png
          - image/gif
          - image/jpeg
          - application/json
          type: string
          writeOnly: true
          description: '[MIME type](https://developer.mozilla.org/en-US/docs/Glossary/MIME_type) of the file'
        filename:
          type: string
          description: Used to reference the original filename. Defaults to `document.{MEDIA TYPE FILE EXTENSION}` e.g. fye_2026.pdf
          maxLength: 200
        processor_key:
          type: string
          description: Key of custom processor
        upload_url:
          type: string
          format: uri
          readOnly: true
          maxLength: 2500
          pattern: "^(?:[a-z0-9.+-]*)://(?:[^\\s:@/]+(?::[^\\s:@/]*)?@)?(?:(?:0|25[0-5]|2[0-4][0-9]|1[0-9]?[0-9]?|[1-9][0-9]?)(?:\\.(?:0|25[0-5]|2[0-4][0-9]|1[0-9]?[0-9]?|[1-9][0-9]?)){3}|\\[[0-9a-f:.]+\\]|([a-z¡-\uFFFF0-9](?:[a-z¡-\uFFFF0-9-]{0,61}[a-z¡-\uFFFF0-9])?(?:\\.(?!-)[a-z¡-\uFFFF0-9-]{1,63}(?<!-))*\\.(?!-)(?:[a-z¡-\uFFFF-]{2,63}|xn--[a-z0-9]{1,59})(?<!-)\\.?|localhost))(?::[0-9]{1,5})?(?:[/?#][^\\s]*)?\\z"
        external_id:
          type: string
          description: External ID is used to uniquely identify a record from your system in our system. Must be unique across records.
          maxLength: 255
        custom_attributes:
          type: object
      required:
      - media_type
    DocumentFileCreate:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          readOnly: true
        status:
          type: string
          readOnly: true
        created_date:
          type: string
          format: date-time
          readOnly: true
        borrower_uuid:
          type: string
          format: uuid
          description: UUID of the borrower for this file. (see [Borrowers](#tag/Borrowers))
        media_type:
          enum:
          - application/pdf
          - application/x-pdf
          - application/vnd.ms-excel
          - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
          - application/vnd.ms-excel.sheet.macroEnabled.12
          - image/png
          - image/gif
          - image/jpeg
          - application/json
          type: string
          writeOnly: true
          description: '[MIME type](https://developer.mozilla.org/en-US/docs/Glossary/MIME_type) of the file'
        filename:
          type: string
          description: Used to reference the original filename. Defaults to `document.{MEDIA TYPE FILE EXTENSION}` e.g. fye_2026.pdf
          maxLength: 200
        statements:
          type: array
          items:
            type: object
            properties:
              form_type:
                enum:
                - INCOME_STATEMENT
                - BALANCE_SHEET
                - TAX_RETURN
                - '1065'
                - '1040'
                - '1120'
                - 1120S
                - Puerto Rico Corporate
                - Puerto Rico Individual
                - Puerto Rico Schedule M Individual
                - Puerto Rico Schedule CO Individual
                - Puerto Rico Schedule D Individual
                - Puerto Rico Schedule F Individual
                - Puerto Rico Schedule H Individual
                - Puerto Rico Schedule IE Individual
                - Puerto Rico Schedule J Individual
                - Puerto Rico Schedule K Individual
                - Puerto Rico Schedule L Individual
                - Puerto Rico Schedule N Individual
                - Puerto Rico Schedule R1 Individual
                type: string
              start_date:
                type: string
                format: date
              end_date:
                type: string
                format: date
              tax_year:
                type: integer
                maximum: 2026
                minimum: 1901
          writeOnly: true
          description: "\nBy default, any document submitted to Fincura will be scanned for Income Statement and Balance Sheet information.\n\nThe engine can also be pointed at Tax Returns by setting a statement object with a `form_type` and `tax_year`. Supported tax form types: \n\n```\n{\n    \"borrower_uuid\": \"6e...845ab1d\",\n    \"media_type\": \"application/pdf\",\n    \"statements\": [\n        {\n          \"form_type\": \"1065\"\n          \"tax_year\": 2019\n        }\n      ]\n}\n```\n    \n\n"
        upload_url:
          type: string
          format: uri
          readOnly: true
          maxLength: 2500
          pattern: "^(?:[a-z0-9.+-]*)://(?:[^\\s:@/]+(?::[^\\s:@/]*)?@)?(?:(?:0|25[0-5]|2[0-4][0-9]|1[0-9]?[0-9]?|[1-9][0-9]?)(?:\\.(?:0|25[0-5]|2[0-4][0-9]|1[0-9]?[0-9]?|[1-9][0-9]?)){3}|\\[[0-9a-f:.]+\\]|([a-z¡-\uFFFF0-9](?:[a-z¡-\uFFFF0-9-]{0,61}[a-z¡-\uFFFF0-9])?(?:\\.(?!-)[a-z¡-\uFFFF0-9-]{1,63}(?<!-))*\\.(?!-)(?:[a-z¡-\uFFFF-]{2,63}|xn--[a-z0-9]{1,59})(?<!-)\\.?|localhost))(?::[0-9]{1,5})?(?:[/?#][^\\s]*)?\\z"
        external_id:
          type: string
          description: External ID is used to uniquely identify a record from your system in our system. Must be unique across records.
          maxLength: 255
        custom_attributes:
          type: object
        document_type:
          enum:
          - INCOME_STATEMENT
          - BALANCE_SHEET
          - TAX_RETURN
          type: string
          default: TAX_RETURN
      required:
      - borrower_uuid
      - media_type
    DocumentFileRead:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          readOnly: true
        status:
          type: string
          readOnly: true
        pipeline_step:
          type: string
          readOnly: true
        created_date:
          type: string
          format: date-time
          readOnly: true
        borrower_uuid:
          type: string
          format: uuid
          description: UUID of the borrower for this file.
        borrower_name:
          type: string
          readOnly: true
        filename:
          type: string
          description: Used to reference the original filename. Defaults to `document.{MEDIA TYPE FILE EXTENSION}` e.g. fye_2026.pdf
          maxLength: 200
        statement_types:
          type: array
          items: {}
          readOnly: true
          default:
          - OTHER
        custom_attributes:
          type: object
        document_type:
          enum:
          - INCOME_STATEMENT
          - BALANCE_SHEET
          - TAX_RETURN
          type: string
          default: TAX_RETURN
        review_queue_item_status:
          type: string
          readOnly: true
        review_queue_item_status_code:
          type: string
          readOnly: true
        review_queue_item_exception_message:
          type: string
          readOnly: true
        review_queue_item_exception_class:
          type: string
          readOnly: true
        tax_form_type:
          type: string
          nullable: true
          maxLength: 50
      required:
      - borrower_uuid
    BulkFileRead:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          readOnly: true
        status:
          type: string
          readOnly: true
        created_date:
          type: string
          format: date-time
          readOnly: true
        media_type:
          enum:
          - application/pdf
          - application/x-pdf
          - application/vnd.ms-excel
          - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
          - application/vnd.ms-excel.sheet.macroEnabled.12
          - image/png
          - image/gif
          - image/jpeg
          - application/json
          type: string
          writeOnly: true
          description: '[MIME type](https://developer.mozilla.org/en-US/docs/Glossary/MIME_type) of the file'
        filename:
          type: string
          description: Used to reference the original filename. Defaults to `document.{MEDIA TYPE FILE EXTENSION}` e.g. fye_2026.pdf
          maxLength: 200
        document_files:
          type: array
          items:
            type: string
          readOnly: true
        processor_key:
          type: string
          description: Key of custom processor
        external_id:
          type: string
          description: External ID is used to uniquely identify a record from your system in our system. Must be unique across records.
          maxLength: 255
        custom_attributes:
          type: object
      required:
      - media_type
  securitySchemes:
    API_Key:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-tagGroups:
- name: Tenant
  tags:
  - Api-Key
  - TenantSettings
- name: Templates
  tags:
  - SpreadingTemplate
  - DscrTemplate
  - GlobalCashflowTemplate
- name: Borrower
  tags:
  - Borrowers
  - Files
  - Loans
  - Requirements
  - Portfolios
- name: Normalized Data
  tags:
  - DataViews
  - Templates
- name: Analysis
  tags:
  - DscrAnalysis
  - GlobalCashflowAnalysis
- name: Events
  tags:
  - Webhooks
- name: Embedded UI
  tags:
  - EmbeddedDocument
  - EmbeddedFinancials
  - EmbeddedDscrAnalysis
  - EmbeddedGlobalCashflowAnalysis