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

# Upload, scan & save an invoice

> Uploads an invoice file together with its metadata. The system will automatically scan the document, extract relevant data, and create or update the invoice in the database. If any step of the process (upload, scan, or save) fails, an exception is thrown.




## OpenAPI

````yaml /openapi.json post /api/v1/invoices/upload-invoice
openapi: 3.0.3
info:
  title: Manglai Public API
  description: Manglai API for Carbon Footprint Management
  contact:
    email: admin@manglai.io
    name: Manglai Support
    url: https://manglai.io
  termsOfService: https://manglai.io/privacy
  version: '1.0'
servers:
  - url: https://www.manglai.io
    description: Production
security:
  - apiTokenAuth: []
tags: []
paths:
  /api/v1/invoices/upload-invoice:
    post:
      tags:
        - invoices
      summary: Upload, scan & save an invoice
      description: >
        Uploads an invoice file together with its metadata. The system will
        automatically scan the document, extract relevant data, and create or
        update the invoice in the database. If any step of the process (upload,
        scan, or save) fails, an exception is thrown.
      parameters:
        - in: query
          name: id
          required: false
          description: Unique identifier of the invoice.
          schema:
            type: string
        - in: query
          name: companyId
          required: true
          description: >-
            Company associated with the invoice. If the ai found a best match
            company, this will be ignored.
          schema:
            type: string
        - in: query
          name: buildingId
          required: false
          description: >-
            Used to associate the invoice with a building by default if the
            invoice does not contain it or ai cannot extract it. If the ai found
            a best match building, this will be ignored.
          schema:
            type: string
        - in: query
          name: externalId
          required: false
          description: External identifier for the invoice (optional).
          schema:
            type: string
        - in: query
          name: model
          required: false
          description: Model used for processing (optional).
          schema:
            type: string
        - in: query
          name: documentType
          required: false
          description: Type of document (optional).
          schema:
            type: string
        - in: query
          name: prompt
          required: false
          description: Prompt for processing (optional).
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                invoice:
                  type: string
                  format: binary
                  description: Invoice file to be uploaded and scanned.
              required:
                - invoice
      responses:
        '200':
          description: Invoice successfully uploaded, scanned, and stored.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  invoice:
                    type: object
                    description: The invoice object
        '400':
          description: >-
            Bad request — missing required fields, invalid metadata, or file not
            provided.
        '409':
          description: Conflict — invoice with the same ID already exists.
        '422':
          description: Unprocessable entity — scan or validation failed.
        '500':
          description: Internal server error during upload, scan, or save operation.
components:
  securitySchemes:
    apiTokenAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````