---
title: "Create invoice from file upload or URL download"
method: POST
path: "/invoices/upload"
tags: ["invoices"]
---

# Create invoice from file upload or URL download

`POST /invoices/upload`

Creates a new invoice by uploading a file directly or downloading from a URL. This endpoint combines file processing, S3 storage, and invoice creation in a single API call.

### File Processing
- Multiple formats supported: PDF, JPG, PNG, TIFF
- Direct file upload via multipart form data
- URL-based file download and ingestion
- Automatic format and size validation
- Secure S3 storage integration

### Invoice Creation Features
- Single-step upload and creation process
- Custom metadata support for tracking
- Location assignment
- Email sender tracking
- Integration with existing document processing pipeline

### Use Cases
- Email attachment processing
- Mobile application file uploads
- Webhook-based ingestion from vendor portals
- Programmatic batch processing

### Technical Specifications
- File size limit: 25MB per file
- Supported formats: PDF, JPG, JPEG, PNG, TIFF
- Authentication: API key required
- Access control: Location-level validation
- Storage: Automatic S3 upload with encryption

## Headers

- `Authorization` string, required
- `X-Api-Key` string, required
- `X-API-Version` string
- `Idempotency-Key` string

## Response `200`

Invoice created successfully. Returns the reference ID for the uploaded document. Invoice processing happens asynchronously.

- InvoiceCreationResponse
  - `version` string, required — API response version
  - `reference_id` string, required — The reference ID for the uploaded document. Use this to track the invoice through processing.

## Other responses

- `400` — Bad request - Invalid request data or file format. Common causes include missing required fields, invalid file format, file too large, or invalid location ID.
- `401` — Unauthorized - Authentication required or invalid credentials
- `403` — Forbidden - Access denied or insufficient permissions
- `413` — Payload too large - File exceeds maximum size limit of 25MB.
- `422` — Unprocessable entity - Request validation failed
- `500` — Internal server error - Server-side processing error

## Changes

- **2026-08-22** `75aab60eedc9` — 2 breaking, 1 warning
  - for the `header` request parameter `Idempotency-Key`, the minLength was increased from `0` to `1`
  - added the pattern `^[A-Za-z0-9._\-+=/]{1,128}$` to the `header` request parameter `Idempotency-Key`
  - for the `header` request parameter `Idempotency-Key`, the maxLength was set to `128`
- **2026-08-17** `c231509a03cf` — 6 breaking, 12 info
  - the `message` response's property type/format changed from `string`/`` to ``/`` for status `400`
  - the `message` response's property type/format changed from `string`/`` to ``/`` for status `401`
  - the `message` response's property type/format changed from `string`/`` to ``/`` for status `403`
  - the `message` response's property type/format changed from `string`/`` to ``/`` for status `413`
  - …14 more
- **2026-08-13** `1f089f3e34d9` — 18 breaking
  - the response property `code` became optional for the status `400`
  - the response property `code` became optional for the status `401`
  - the response property `code` became optional for the status `403`
  - the response property `code` became optional for the status `413`
  - …14 more

[Change history](https://skmtc.dev/ottimate/apis/api-reference/changes/invoices/upload/post.md)

---

[API](https://skmtc.dev/ottimate/apis/api-reference.md) · [All operations](https://skmtc.dev/ottimate/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ottimate/api-reference/revisions/ba91ff4c6969/schema)