File Transfer API

The File Transfer API delivers large files generated by Judit — CSV/JSON exports from custom searches, on-demand reports, bulky aggregations — asynchronously, with auditable status (pending, available, consumed) per file.

🤖 Base URL: https://lawsuits.production.judit.io/. After generating a report (e.g. Custom Search), use this API to list pending files, download via pre-signed URL and mark as consumed to avoid reprocessing.

When to use

On-demand reports

Consume Custom Search results that arrive as files (CSV/JSON) instead of webhook.

Batch export

Receive periodic dumps of an entire portfolio (hundreds of thousands of lawsuits).

Audit

Auditable trail of who downloaded each file and when — perfect for SOX/LGPD/GDPR.

Data pipelines

Integrate Judit into your data lake/warehouse via batch file consumption.

🔐 Authentication

Every request must include a header with the company’s API key:

api-key: YOUR_API_KEY

⚠️ A user may only access files belonging to their own company’s tenant.

📂 List available files

`GET /transfer-file`

Returns a paginated list of files available for the authenticated user’s company.

Supported query params:

description: string (filters by description)
file_type: csv, json, parquet
name: string (filters by file name)
status: string or array (e.g., status=completed or status=["completed","error"])
Dates: range filters for the fields below:
- created_at, updated_at, completed_at, downloaded_at, error_at, failed_at, started_at
- Example: created_at_gte=2025-04-01T00:00:00.000Z
Pagination and sorting:
- page: page number (default: 1)
- page_size: page size (max: 100, default: 10)
- order_by: sorting field (default: created_at)
- order: asc or desc (default: desc)

Example call with `curl`:

curl -H "api-key: YOUR_API_KEY" \
  "https://lawsuits.production.judit.io/transfer-file?page=1&page_size=20&status=[\"completed\"]"

Example response:

{
  "page": 1,
  "page_data": [
    {
      "transfer_file_id": "be4ed52a-a96b-4782-a181-b7ed75cb2f21",
      "description": "ARQUIVO INICIAL - CARGA 0",
      "file_type": "parquet",
      "name": "be4ed52a-a96b-4782-a181-b7ed75cb2f21-part-00001.parquet",
      "status": "downloaded",
      "created_at": "2025-04-22T11:50:00.000Z",
      "updated_at": "2025-04-22T09:21:06.343Z",
      "completed_at": "2025-04-22T11:51:00.000Z",
      "started_at": "2025-04-22T11:50:01.000Z",
      "downloaded_at": "2025-04-22T09:21:06.343Z",
      "error_at": "2025-04-22T09:20:31.460Z",
      "error_message": "teste de erro",
      "file_size": 0.038,
      "lawsuits_count": 19
    }
  ],
  "page_count": 1,
  "all_count": 1,
  "all_pages_count": 1
}

Explanation of return fields:

page: current page number
page_data: list of files returned on this page
page_count: number of records on this page
all_count: total number of files matching the filter
all_pages_count: total number of pages available

📥 Get the download URL

`GET /transfer-file/:transfer_file_id`

Returns the file’s metadata and a pre-signed AWS URL for download (valid for 5 minutes).

Example call with `curl`:

curl -H "api-key: YOUR_API_KEY" \
  "https://lawsuits.production.judit.io/transfer-file/be4ed52a-a96b-4782-a181-b7ed75cb2f21"

Example response:

{
  "transfer_file_id": "be4ed52a-a96b-4782-a181-b7ed75cb2f21",
  "description": "ARQUIVO INICIAL - CARGA 0",
  "file_type": "parquet",
  "name": "be4ed52a-a96b-4782-a181-b7ed75cb2f21-part-00001.parquet",
  "status": "completed",
  "created_at": "2025-04-22T11:50:00.000Z",
  "updated_at": "2025-04-22T09:21:06.343Z",
  "completed_at": "2025-04-22T11:51:00.000Z",
  "started_at": "2025-04-22T11:50:01.000Z",
  "file_size": 0.038,
  "lawsuits_count": 19,
  "pre_signed_url": "https://s3.amazonaws.com/..."
}

🛠 Update a file’s status

`PATCH /transfer-file/:transfer_file_id`

Lets you mark the file as downloaded or error after attempting to use it.

Example call with `curl`:

curl -X PATCH -H "api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"status": "downloaded"}' \
     "https://lawsuits.production.judit.io/transfer-file/be4ed52a-a96b-4782-a181-b7ed75cb2f21"

Request body:

To mark as downloaded:

{
  "status": "downloaded"
}

To report an error:

{
  "status": "error",
  "error_message": "Descrição do erro, stack trace ou contexto do problema."
}

Example response - status `downloaded`:

{
  "transfer_file_id": "be4ed52a-a96b-4782-a181-b7ed75cb2f21",
  "description": "ARQUIVO INICIAL - CARGA 0",
  "file_type": "parquet",
  "name": "be4ed52a-a96b-4782-a181-b7ed75cb2f21-part-00001.parquet",
  "status": "downloaded",
  "created_at": "2025-04-22T11:50:00.000Z",
  "updated_at": "202
4-04-22T11:50:00.000Z"
}

Common errors

HTTP	Reason	How to handle
`400`	Invalid filter or status.	Validate query params before sending.
`401`	API Key missing or invalid.	Check `api-key` header.
`404`	File not found.	The `transfer_file_id` may be from another tenant.
`429`	Rate limit exceeded.	Exponential backoff.

Next steps

Custom Search — generate large reports.
Webhooks — get notified when a file is ready.

Getting Started

Core Concepts

Data Models (Schemas)

Asynchronous Requests

Synchronous Requests

Tracking

Registration Data

Criminal Records

File Transfer

Credentials Vault

Webhook

Resources

When to use

On-demand reports

Batch export

Audit

Data pipelines

🔐 Authentication

📂 List available files

`GET /transfer-file`

Supported query params:

Example call with `curl`:

Example response:

Explanation of return fields:

📥 Get the download URL

`GET /transfer-file/:transfer_file_id`

Example call with `curl`:

Example response:

🛠 Update a file’s status

`PATCH /transfer-file/:transfer_file_id`

Example call with `curl`:

Request body:

Example response - status `downloaded`:

Common errors

Next steps

​When to use

On-demand reports

Batch export

Audit

Data pipelines

​🔐 Authentication

​📂 List available files

​GET /transfer-file

​Supported query params:

​Example call with curl:

​Example response:

​Explanation of return fields:

​📥 Get the download URL

​GET /transfer-file/:transfer_file_id

​Example call with curl:

​Example response:

​🛠 Update a file’s status

​PATCH /transfer-file/:transfer_file_id

​Example call with curl:

​Request body:

​Example response - status downloaded:

​Common errors

​Next steps

When to use

🔐 Authentication

📂 List available files

`GET /transfer-file`

Supported query params:

Example call with `curl`:

Example response:

Explanation of return fields:

📥 Get the download URL

`GET /transfer-file/:transfer_file_id`

Example call with `curl`:

Example response:

🛠 Update a file’s status

`PATCH /transfer-file/:transfer_file_id`

Example call with `curl`:

Request body:

Example response - status `downloaded`:

Common errors

Next steps