---
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

---

[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)