---
title: "Create an upload session"
method: POST
path: "/uploads/sessions"
tags: ["Uploads"]
---

# Create an upload session

`POST /uploads/sessions`

## Request

- Base URL: `https://api.invoicedataextraction.com/v1`
- URL: `https://api.invoicedataextraction.com/v1/uploads/sessions`
- Auth: HTTP bearer

Registers one or more files (1 to 6,000) and returns the part size to use when
uploading each of them. Every file needs at least one available credit at this point,
so an account with fewer available credits than files is refused with
`INSUFFICIENT_CREDITS`.

Idempotent: a retry with the same `upload_session_id` and the same files returns the
existing session. The same `upload_session_id` with different files is
`SESSION_ALREADY_INITIALIZED`.

Rate limit: 600 requests per minute per API key, shared by the upload endpoints.

## Request body

- CreateUploadSessionRequest
  - `upload_session_id` string, required: An identifier you choose: 1 to 200 characters from letters, digits, dots, underscores, colons and hyphens. Used for `upload_session_id`, `file_id` and `submission_id`.
  - `files` UploadSessionFileRequest[], required
    - `file_id` string, required: An identifier you choose: 1 to 200 characters from letters, digits, dots, underscores, colons and hyphens. Used for `upload_session_id`, `file_id` and `submission_id`.
    - `file_name` string, required: The file name with its extension, one of `.pdf`, `.jpg`, `.jpeg`, `.png`; no control characters, slashes or surrounding whitespace. Unique within the session.
    - `file_size_bytes` integer, required: The exact size in bytes. PDFs up to 150 MB (157,286,400 bytes) and up to 5,000 pages; images up to 5 MB (5,242,880 bytes); all files of a session together up to 2 GB.

## Response `200`

The session, with the part size to upload each file in.

- CreateUploadSessionResponse
  - `success` true, required
  - `upload_session_id` string, required: An identifier you choose: 1 to 200 characters from letters, digits, dots, underscores, colons and hyphens. Used for `upload_session_id`, `file_id` and `submission_id`.
  - `files` object[], required
    - `file_id` string, required: An identifier you choose: 1 to 200 characters from letters, digits, dots, underscores, colons and hyphens. Used for `upload_session_id`, `file_id` and `submission_id`.
    - `file_name` string, required
    - `part_size` integer, required: The part size in bytes to split the file into; the same for every file in the session (8,388,608 today). A file smaller than this is one part.

## Other responses

- `400`: `INVALID_INPUT` (the body does not match the schema; `details.issues` names each problem), `DUPLICATE_FILE_NAME`, `DUPLICATE_FILE_ID`, `FILE_TOO_LARGE` (a PDF over 150 MB or an image over 5 MB; `details` names the file and the limit) or `TOTAL_UPLOAD_SIZE_LIMIT_EXCEEDED` (the files together exceed 2 GB).
- `401`: `UNAUTHENTICATED`, `API_KEY_EXPIRED` or `API_KEY_REVOKED`.
- `402`: `INSUFFICIENT_CREDITS`: fewer available credits than files. `details` carries `credits_balance`, `credits_reserved` and `file_count`.
- `409`: `SESSION_ALREADY_INITIALIZED`: this `upload_session_id` is in use with different files.
- `429`: `RATE_LIMITED`: wait `details.retry_after_seconds` (also the `Retry-After` header), then retry.
- `500`: `INTERNAL_ERROR`: retry after a short delay.

---

[API](https://skmtc.dev/invoicedataextraction/apis/invoice-data-extraction-api.md) · [All operations](https://skmtc.dev/invoicedataextraction/apis/invoice-data-extraction-api/llms.txt) · [OpenAPI document](https://skmtc.dev/invoicedataextraction/apis/invoice-data-extraction-api/revisions/16d920350483?raw)