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

# Upload a bill to a company

> Upload a PDF or image to a company when you do not know which of its organisations the bill belongs to. The document is read asynchronously and the delivery address printed on it is matched against the company's organisations. A confident match is assigned automatically; anything else waits in the company's inbox to be assigned. The identifier returned here is the bill's identifier and does not change when it is assigned.

**Authentication.** An API key (`x-dolfin-api-key`) **or** a JWT Bearer token. When your credential grants access to more than one client, select one with the `x-dolfin-client-id` header.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/companies/{companyId}/bills
openapi: 3.1.1
info:
  title: Dolfin API
  description: >-
    Dolfin API for AR & AP. Each operation documents its accepted credentials
    under **Authentication** — typically an `x-dolfin-api-key` header (with
    `x-dolfin-organisation-id`) or a JWT Bearer token.
  version: v1
servers:
  - url: https://api.dolfinai.co
    description: Production
security: []
tags:
  - name: Users
  - name: TaxRates
  - name: Suppliers
  - name: Supplier Credit Notes
  - name: Bills
  - name: Payables
  - name: RecurringInvoices
  - name: Receivables
  - name: Purchase Orders
  - name: Products
  - name: Payments
  - name: Invoices
  - name: Organisations
  - name: Clients
  - name: MCP
  - name: Matching
  - name: Invoice Reminders
  - name: Industries
  - name: Gmail
  - name: Delivery Notes
  - name: Customers
  - name: Currencies
  - name: Credit Notes
  - name: Companies
  - name: BankPayments
  - name: Bank details
  - name: Auth
  - name: ApprovalPolicies
  - name: Agent
paths:
  /v1/companies/{companyId}/bills:
    post:
      tags:
        - Companies
      summary: Upload a bill to a company
      description: >-
        Upload a PDF or image to a company when you do not know which of its
        organisations the bill belongs to. The document is read asynchronously
        and the delivery address printed on it is matched against the company's
        organisations. A confident match is assigned automatically; anything
        else waits in the company's inbox to be assigned. The identifier
        returned here is the bill's identifier and does not change when it is
        assigned.


        **Authentication.** An API key (`x-dolfin-api-key`) **or** a JWT Bearer
        token. When your credential grants access to more than one client,
        select one with the `x-dolfin-client-id` header.
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: x-dolfin-client-id
          in: header
          description: >-
            Target client. Required when your credential grants access to more
            than one client; omit when it resolves a single client.
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  $ref: '#/components/schemas/IFormFile'
        required: true
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyBillCreatedResponse'
        '400':
          description: >-
            Company.MissingClientId — client ID is required


            Bill.FileTooLarge — uploaded file exceeds the 20 MB maximum


            Bill.UnsupportedFileType — file type is not supported; accepted:
            PDF, PNG, JPEG, TIFF, GIF, BMP, WEBP
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: >-
            Module.NotEntitled — the client's plan does not include the module
            this endpoint requires
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: >-
            Company.NotFound — the company does not exist or belongs to a
            different client
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      security:
        - ApiKey: []
        - Bearer: []
components:
  schemas:
    IFormFile:
      type: string
      format: binary
    CompanyBillCreatedResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/CompanyInboxBillStatus'
    ProblemDetails:
      type: object
      properties:
        type:
          type:
            - 'null'
            - string
        title:
          type:
            - 'null'
            - string
        status:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
            - 'null'
            - integer
            - string
          format: int32
        detail:
          type:
            - 'null'
            - string
        instance:
          type:
            - 'null'
            - string
    CompanyInboxBillStatus:
      enum:
        - Extracting
        - ExtractionFailed
        - AwaitingOrganisation
        - Discarded
  securitySchemes:
    ApiKey:
      type: apiKey
      description: >-
        An API key issued to your client. It carries the client's scope;
        org-scoped calls also require the `x-dolfin-organisation-id` header.
        Keys are created and revoked by a client administrator.
      name: x-dolfin-api-key
      in: header
    Bearer:
      type: http
      description: >-
        A session JWT obtained via the OAuth flow (`POST /auth/codes` → `POST
        /auth/exchange`). Its claims carry the caller's organisation and/or
        client scope.
      scheme: bearer
      bearerFormat: JWT

````