Exports

Lists page at up to 100 rows per request, which is right for an app and wrong for a BI load. Exports produce one file with the complete filtered dataset of an entity (processes, actuaciones or defendants), up to 100,000 rows, and hand you a download URL.

POST https://api.legal.usecroma.com/v1/exports

Because a large portfolio takes longer than a single request should hold, an export runs as an async job: the same request can resolve three ways, and you choose which fits your app.

Small exports feel synchronous. By default the request waits up to 20 seconds and, if the file is ready, returns 200 { data } with the URL. The other modes are opt-in, for when you’d rather not hold the connection open.

The request

{
  "entity": "processes",
  "format": "csv",
  "filters": { "status": "TRACKING", "date_from": "2024-01-01" }
}

Field	Required	Meaning
`entity`	yes	`processes`, `actions` or `defendants`.
`format`	no	`csv` (default; UTF-8 with BOM so Excel renders accents) or `jsonl` (one JSON object per line, best for scripts).
`filters`	no	Same names as the list endpoints’ query params, in one flat object. Filters that don’t apply to the chosen entity are ignored. See ExportFilters.
`callback_url`	no	Public HTTPS URL to `POST` the result to. Turns on callback mode.

Unknown fields in the body (or in filters) are rejected with 400. The result, once the file exists:

{
  "data": {
    "url": "https://files.usecroma.com/legal-exports/processes-2026-08-21.csv",
    "entity": "processes",
    "format": "csv",
    "rows": 1280,
    "bytes": 418233,
    "truncated": false,
    "expires_at": "2026-08-22T14:03:10.000Z"
  }
}

url is unguessable but not authenticated: anyone holding it can download the file. It is guaranteed until expires_at (24 hours after completion) and removed shortly after; download promptly and don’t post it anywhere public.
truncated: true means the 100,000-row cap was hit and the file is not the complete dataset. Narrow the filters (for instance by date range) and export again.

The three ways to get the result

Mode	You send	You get back
Wait inline (default)	nothing extra, or `Prefer: wait=N`	`200 { data }` if it finishes in time, else `202`
Poll	`Prefer: wait=0`	`202` now, then `GET /jobs/:id` until done
Callback	`callback_url` in the body	`202` now, then a `POST` to your URL when done

All three are backed by the same job, so pick per request.

Mode 1: Wait inline (default)

Just call the endpoint. The request holds open until the file is ready (up to 20 seconds by default) and returns { data }.

curl -X POST https://api.legal.usecroma.com/v1/exports \
  -H "Authorization: Bearer $CROMA_LEGAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "entity": "defendants", "format": "jsonl" }'

const res = await fetch("https://api.legal.usecroma.com/v1/exports", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CROMA_LEGAL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ entity: "defendants", format: "jsonl" }),
});

if (res.status === 200) {
  const { data } = await res.json(); // data.url is ready to download
} else if (res.status === 202) {
  // not ready in time; poll the status URL (see Mode 2)
}

Control how long to wait with the standard Prefer: wait=N header (seconds, clamped to 55):

curl -X POST https://api.legal.usecroma.com/v1/exports \
  -H "Authorization: Bearer $CROMA_LEGAL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=50" \
  -d '{ "entity": "processes", "format": "csv" }'

200: done. Body is { "data": … } as above.
202: not done within the wait. Body is a job envelope; follow its status_url to poll. The X-Job-Id header carries the job id.

Always handle both 200 and 202. A 202 is not an error; it just means “still generating, come back for it.” A portfolio of tens of thousands of actuaciones routinely takes longer than the default 20-second wait.

Mode 2: Poll

Send Prefer: wait=0 to get a 202 immediately, then GET the job’s status_url until it reaches a terminal state.

# 1. Start the export (returns 202 immediately)
curl -i -X POST https://api.legal.usecroma.com/v1/exports \
  -H "Authorization: Bearer $CROMA_LEGAL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=0" \
  -d '{ "entity": "actions", "filters": { "since": "2026-01-01" } }'

# 2. Poll the status_url from the response (or the Location header)
curl https://api.legal.usecroma.com/jobs/run_abc123def456 \
  -H "Authorization: Bearer $CROMA_LEGAL_API_KEY"

// 1. Start the export
const start = await fetch("https://api.legal.usecroma.com/v1/exports", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CROMA_LEGAL_API_KEY}`,
    "Content-Type": "application/json",
    Prefer: "wait=0",
  },
  body: JSON.stringify({ entity: "actions", filters: { since: "2026-01-01" } }),
});
const { job } = await start.json();

// 2. Poll until terminal
async function poll(statusUrl: string) {
  while (true) {
    const res = await fetch(statusUrl, {
      headers: { Authorization: `Bearer ${process.env.CROMA_LEGAL_API_KEY}` },
    });
    const body = await res.json();
    if (body.job.status === "completed") return body.data;
    if (["failed", "canceled", "expired"].includes(body.job.status)) {
      throw new Error(body.error?.message ?? body.job.status);
    }
    // honor Retry-After; defaults to 2s while running
    const wait = Number(res.headers.get("Retry-After") ?? 2) * 1000;
    await new Promise((r) => setTimeout(r, wait));
  }
}

const { url } = await poll(job.status_url);

GET /jobs/:id always returns 200 with the envelope. While the job is still running it includes a Retry-After header (seconds); use it to pace your polling. Polling has its own generous rate-limit bucket. Jobs are scoped to your organization; a job belonging to another organization reads as 404.

Mode 3: Callback (webhook)

Include a callback_url in the request body. You get a 202 right away, and Croma POSTs the result to your URL once the file is ready, with no polling.

curl -i -X POST https://api.legal.usecroma.com/v1/exports \
  -H "Authorization: Bearer $CROMA_LEGAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "entity": "processes",
        "format": "csv",
        "callback_url": "https://your-app.com/webhooks/croma-legal"
      }'

callback_url must be an absolute HTTPS URL on a public host (localhost and private ranges are rejected). When the job finishes, Croma sends a POST to it:

Body: the same job envelope as the poll endpoint.
x-croma-job-id: the job id.
x-croma-signature: sha256=<hmac>, an HMAC-SHA256 of the raw request body, so you can verify the payload’s integrity.

POST /webhooks/croma-legal HTTP/1.1
content-type: application/json
x-croma-job-id: run_abc123def456
x-croma-signature: sha256=9f86d081…

{ "job": { "id": "run_abc123def456", "status": "completed", … }, "data": { "url": "…" }, "error": null }

Signature verification uses a shared secret issued by Croma; reach out if you want it enabled for your callbacks. Respond 2xx quickly; non-2xx responses are retried.

The job envelope

The 202 response, GET /jobs/:id, and the callback body all share one shape:

{
  "job": {
    "id": "run_abc123def456",
    "status": "completed",
    "endpoint": "/v1/exports",
    "created_at": "2026-08-21T14:03:10.000Z",
    "finished_at": "2026-08-21T14:03:41.000Z",
    "status_url": "https://api.legal.usecroma.com/jobs/run_abc123def456"
  },
  "data": { "url": "…", "entity": "processes", "format": "csv", "rows": 1280, "bytes": 418233, "truncated": false, "expires_at": "2026-08-22T14:03:41.000Z" },
  "error": null
}

data is populated only when status is completed. Otherwise it’s null.
error is populated only when the job has failed, as { "type", "code", "message" } with code: "job_failed".

Statuses

`status`	Terminal?	Meaning
`queued`	no	Accepted, waiting to run.
`running`	no	Generating the file.
`completed`	yes	Done. Read `data.url`.
`failed`	yes	The export errored. Read `error`; create it again.
`canceled`	yes	The run was canceled.
`expired`	yes	The run expired before completing.

What’s in the file

Columns are the same whether you pick csv or jsonl. Nested values (metadata) are serialized as JSON text in CSV cells.

processes
actions
defendants

id, registration_number, plaintiff_name, defendant_name, defendant_id, office, status, registration_date, last_discovery_date, is_private, latest_action_message, latest_action_date, metadata.The two latest_action_* columns carry the most recent actuación of each case, so the file reads like the portfolio view in the dashboard.

id, process_id, registration_number, message, note, registration_date, action_created_at, source, publication_url, document_url, plaintiff_name, defendant_name, defendant_id, defender_name, office, priority, is_private, last_discovery_date, metadata.This is the largest dataset: filter by since, date_from / date_to, office or defendant to stay under the row cap.

id, identification_number, name, process_count, metadata, created_at.

Headers reference

Header	Where	Meaning
`Prefer: wait=N`	request	Seconds to wait inline before returning `202`. Default 20, clamped to 55. `wait=0` returns `202` immediately.
`Preference-Applied: wait=N`	`200` response	Echoes the wait that was applied.
`Location`	`202` response	The job’s `status_url`.
`Retry-After`	`202` / running poll	Suggested seconds before polling again.
`X-Job-Id`	`202` / `200` response	The job id.

POST /v1/exports

Full request and response schema, with the filters per entity.

Errors

How failures and the error object work.

Get Started

Guides

API Reference

The request

The three ways to get the result

Mode 1: Wait inline (default)

Mode 2: Poll

Mode 3: Callback (webhook)

The job envelope

Statuses

What’s in the file

Headers reference

POST /v1/exports

Errors

​The request

​The three ways to get the result

​Mode 1: Wait inline (default)

​Mode 2: Poll

​Mode 3: Callback (webhook)

​The job envelope

​Statuses

​What’s in the file

​Headers reference

POST /v1/exports

Errors

The request

The three ways to get the result

Mode 1: Wait inline (default)

Mode 2: Poll

Mode 3: Callback (webhook)

The job envelope

Statuses

What’s in the file

Headers reference