# Send a file and read it
> Send a file, send it again safely, wait until it is read, read its documents, get the original, delete it.
>
> Before: [Keys and scopes](https://ocost.io/docs/en/authentication.md)

Send a PDF, an image or an e-invoice, wait until Ocost has read it, then read its documents. One file can hold several documents. A scan of three invoices is one file with three documents.

## Send the file

Post the file as `multipart/form-data` to `POST /public/v1/files`. The key needs the scope [`documents:write`](https://ocost.io/docs/en/authentication.md).

```bash
curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  -F "file=@scan.pdf" -F "name=scan.pdf" -F "external_ref=account.move,42"
```

| Field | Meaning |
| --- | --- |
| `file` | Required. A PDF, an image (JPEG, PNG, TIFF, WebP), a Word file (.docx, .doc) or an e-invoice's XML (XRechnung, UBL, CII), up to 25 MB. |
| `name` | The file name. Without it, Ocost takes the upload's. |
| `external_ref` | Your own id, up to 200 characters, given back with the file. |

The API refuses spreadsheets (.xls, .xlsx) and archives (.zip, .7z) with `415`. Upload them in Ocost instead. There Ocost reads an invoice in a spreadsheet of one sheet, up to 200 rows and 30 columns. It unpacks an archive once, in the company it lands in. Other XML and HTML are stored, but end `not_read` with `nothing_found`.

A new file answers `202 Accepted` with `"status": "received"`, and reading starts at once:

```json
{ "id": "01a1b08c-6e3a-7562-8f4a-7924722667b1", "name": "scan.pdf", "status": "received", "external_ref": "account.move,42", "external_refs": ["account.move,42"], "documents": [] }
```

Every answer carries `X-Ocost-Documents-Left`, the documents your plan has left this month. [Limits and errors](https://ocost.io/docs/en/limits.md) lists the refusals.

## Send it again safely

Ocost knows a file by the SHA-256 of its bytes, not by its name. The same bytes again answer `200 OK` with that file as it is now. Ocost doesn't read or count it again. So after a timeout, send the file again.

A file keeps every `external_ref` sent with its bytes. `external_ref` stays the first, and `external_refs` lists them all, the first first, each once, up to 50. So when two of your records carry the same PDF, send it for each: both ids come back with the one file. A 51st new id is refused with `422`.

## Wait until it is read

Ask for the file with `GET /public/v1/files/{file_id}`, scope `documents:read`. Poll every 2 to 3 seconds for half a minute, then every 10 to 30 seconds. Most PDFs take under a minute, long ones a few.

```python
def wait_for(session, file_id, timeout=300):
    started = time.monotonic()
    while time.monotonic() - started < timeout:
        file = session.get(f"{API}/files/{file_id}", timeout=15).json()
        if file["status"] not in ("received", "reading"):
            return file
        time.sleep(3 if time.monotonic() - started < 30 else 15)
    return file
```

The file is done when its `status` is `read`, `not_read` or `failed`. [Statuses and reasons](https://ocost.io/docs/en/statuses.md) explains each. For many files at once, [stay in sync](https://ocost.io/docs/en/sync.md) instead of polling each one.

## Read its documents

A `read` file lists its documents in `documents`, each with its `id`, `kind`, `number` and `pages`. `GET /public/v1/files/{file_id}/document` answers the first one. `GET /public/v1/documents/{document_id}` answers any of them.

```bash
curl -sS https://api.ocost.io/public/v1/documents/01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11 \
  -H "Authorization: Bearer $OCOST_KEY"
```

The answer is the document as `ocost.document.v1`. [The document](https://ocost.io/docs/en/document.md) shows a whole one and explains every field.

## Get the original

`GET /public/v1/files/{file_id}/content` answers the bytes as you sent them.

```bash
curl -sS -o scan.pdf https://api.ocost.io/public/v1/files/$FILE_ID/content \
  -H "Authorization: Bearer $OCOST_KEY"
```

## Delete a file

`DELETE /public/v1/files/{file_id}` erases the file at once and for good. That includes its documents, what was read, its search index and the original. The key needs `documents:write`.

```bash
curl -sS -X DELETE https://api.ocost.io/public/v1/files/$FILE_ID \
  -H "Authorization: Bearer $OCOST_KEY"
```

Ocost answers `204`, and `404` from then on. It refuses in two cases:

| Answer | What to do |
| --- | --- |
| `409 urn:ocost:file:reading` | The file is being read. Try again later. |
| `409 urn:ocost:file:linked` | Ocost still needs the file, for a booked invoice, a bank statement, an open question or a project. `detail` says which. Delete it in Ocost once nothing needs it. |

## See also

- [Statuses and reasons](https://ocost.io/docs/en/statuses.md): A file's statuses and the reasons it wasn't read, and what to do for each.
- [The document](https://ocost.io/docs/en/document.md): The ocost.document.v1 schema in EN 16931 terms (maps to UBL and CII): an example, kind and direction, sources, checks, versions, and every field and value.
- [Stay in sync](https://ocost.io/docs/en/sync.md): Collect every changed file with one call: GET /public/v1/files with updated_since, a cursor and a status filter.
- [Company groups](https://ocost.io/docs/en/groups.md): Company groups: which companies a key reaches, the Ocost-Business header, routing by the document’s identifiers, needs_company, and files across the group.
- On ocost.io: [Invoice processing](https://ocost.io/en/product/invoice-processing)
