# Bulk index search from a CSV file

Send the API a CSV of lots or matricules (POST /v1/batches), follow the batch, then fetch the index rows as CSV. CAD 0.99 per index excluding Registre fees.

This page describes bulk index search **through the API**: a developer sends a CSV file of lots or matricules, follows the batch, then fetches the index rows as CSV. Studio has no batch upload, so this route is API only. A firm without developers uses the [managed bulk programme on fonciq.ca](https://fonciq.ca/consultation-en-lot) (in French).

## Before you start

- An API key and a Registre account for your organisation. See [Premier appel](/plateforme/demarrage) (French).
- A CSV file with a `lot` or `matricule` column, with at most **500 data rows** per request.

```csv
lot
1234567
7654321
```

## 1. Send the CSV

`POST /v1/batches` (scope `batches:write`) accepts a `text/csv` body. The `Idempotency-Key` header is required and kept for 24 hours.

```bash
curl -X POST https://api.fonciq.ca/v1/batches \
  -H "Authorization: Bearer $FONCIQ_API_KEY" \
  -H "Content-Type: text/csv" \
  -H "Idempotency-Key: 8c2a1d4e-1b6f-4a90-9e3c-2f5d7a8b9c01" \
  --data-binary @lots.csv
```

The response is `202` with a `job_id`. Above 500 lots the response is `409` with the code `batch_too_large`. With a CSV body, the batch is spread across your organisation's active Registre accounts. To pin one account, use the JSON body with `account_id`: see [Batches](/en/registry/batches).

## 2. Follow the batch

Read `GET /v1/jobs/{id}` until `succeeded`. Each account keeps its cap of 540 indexes per day: a batch larger than the remaining capacity waits (`capacity_wait`) until the account has capacity again. The day is Toronto's: the counter resets at midnight Toronto time. Each account's capacity is in the job response.

## 3. Fetch the rows as CSV

```bash
curl "https://api.fonciq.ca/v1/jobs/job_batch_01HZX/results?format=csv" \
  -H "Authorization: Bearer $FONCIQ_API_KEY" -o filings.csv
```

The CSV has one row per structured index row. Columns: `lot`, `matricule`, `inscription`, `date`, `nature`, `parties`, `document_url`, `read_method`, `confidence`, `needs_review`, `page_status`.

```csv
lot,matricule,inscription,date,nature,parties,document_url,read_method,confidence,needs_review,page_status
1234567,,"21 014 436",2024-03-12,Vente,"Vendeur: EXEMPLE, MARIE",https://api.fonciq.ca/v1/documents/42,,unscored,,
```

`confidence` is `unscored`. The PDF of each index (`document_url`) is the authoritative record. Without `format=csv`, the same route returns JSON: one block per lot in `indexes`.

### Python

```python
import os, time, uuid, requests

BASE = "https://api.fonciq.ca"
HEADERS = {"Authorization": f"Bearer {os.environ['FONCIQ_API_KEY']}"}

with open("lots.csv", "rb") as handle:
    job = requests.post(
        f"{BASE}/v1/batches",
        headers={**HEADERS, "Content-Type": "text/csv", "Idempotency-Key": str(uuid.uuid4())},
        data=handle.read(),
    ).json()

while requests.get(f"{BASE}/v1/jobs/{job['job_id']}", headers=HEADERS).json()["status"] not in ("succeeded", "failed"):
    time.sleep(30)

csv_text = requests.get(f"{BASE}/v1/jobs/{job['job_id']}/results", params={"format": "csv"}, headers=HEADERS).text
open("filings.csv", "w", encoding="utf-8").write(csv_text)
```

### Node

```js
import { readFile, writeFile } from 'node:fs/promises';

const BASE = 'https://api.fonciq.ca';
const headers = { Authorization: `Bearer ${process.env.FONCIQ_API_KEY}` };

const job = await fetch(`${BASE}/v1/batches`, {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'text/csv', 'Idempotency-Key': crypto.randomUUID() },
  body: await readFile('lots.csv'),
}).then((r) => r.json());

let state;
do {
  await new Promise((resolve) => setTimeout(resolve, 30_000));
  state = await fetch(`${BASE}/v1/jobs/${job.job_id}`, { headers }).then((r) => r.json());
} while (!['succeeded', 'failed'].includes(state.status));

await writeFile('filings.csv', await fetch(`${BASE}/v1/jobs/${job.job_id}/results?format=csv`, { headers }).then((r) => r.text()));
```

## Cost

Each index costs CAD 0.99 per lot excluding Registre fees, and always consults the Registre (CAD 1.50 per index, charged to the account holder). One consulted index therefore costs CAD 2.49. There is no volume discount.

## See also

- [How to extract index pages with the Fonciq API](/en/guides/quebec-index-json): row details and the source PDF.
- [Batches](/en/registry/batches): the reference, with the JSON body and a pinned account.