> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinikapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk Operations

> Import and export large datasets in NDJSON format.

# Bulk Operations

Bulk operations let you import and export large volumes of clinical data using NDJSON (newline-delimited JSON) format.

## Bulk Export

Start an export job for one or more resource types:

```bash theme={null}
curl -X POST https://api.clinikapi.com/v1/bulk/export \
  -H "x-api-key: clk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceTypes": ["Patient", "Encounter", "Observation"],
    "since": "2025-01-01T00:00:00Z"
  }'
```

Response:

```json theme={null}
{
  "data": {
    "jobId": "job_abc123",
    "status": "pending",
    "message": "Export job started"
  }
}
```

### Poll for Completion

```bash theme={null}
curl https://api.clinikapi.com/v1/bulk/jobs/job_abc123 \
  -H "x-api-key: clk_live_abc123"
```

```json theme={null}
{
  "data": {
    "id": "job_abc123",
    "type": "export",
    "status": "completed",
    "totalRecords": 1250,
    "processedRecords": 1250,
    "downloadUrl": "https://exports.clinikapi.com/clinikapi-exports/...",
    "errors": []
  }
}
```

The `downloadUrl` is a pre-signed URL valid for 1 hour.

## Bulk Import

Import NDJSON data — one JSON resource per line, max 10,000 records per batch:

```bash theme={null}
curl -X POST https://api.clinikapi.com/v1/bulk/import \
  -H "x-api-key: clk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceType": "Patient",
    "data": "{\"firstName\":\"Jane\",\"lastName\":\"Doe\",\"gender\":\"female\"}\n{\"firstName\":\"John\",\"lastName\":\"Smith\",\"gender\":\"male\"}"
  }'
```

### Import Rules

* Max **10,000 records** per batch
* Tenant tags are automatically injected — you cannot override them
* Invalid records are skipped and reported in the job's `errors` array
* Rate limited to **5 bulk operations per hour** per tenant

## Job Statuses

| Status       | Description                       |
| ------------ | --------------------------------- |
| `pending`    | Job is queued                     |
| `processing` | Job is running                    |
| `completed`  | Job finished successfully         |
| `failed`     | Job failed (check `errors` array) |

## NDJSON Format

Each line is a complete JSON object:

```
{"firstName":"Jane","lastName":"Doe","gender":"female","birthDate":"1990-01-15"}
{"firstName":"John","lastName":"Smith","gender":"male","birthDate":"1985-06-20"}
{"firstName":"Maria","lastName":"Garcia","gender":"female","birthDate":"1978-11-03"}
```

<Warning>
  Bulk operations count against your plan's request limit. Each record in an import counts as one request.
</Warning>