Skip to main content

​
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: 
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: 
{
  "data": {
    "jobId": "job_abc123",
    "status": "pending",
    "message": "Export job started"
  }
}

​
Poll for Completion

curl https://api.clinikapi.com/v1/bulk/jobs/job_abc123 \
  -H "x-api-key: clk_live_abc123"

{
  "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: 
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

StatusDescription
pendingJob is queued
processingJob is running
completedJob finished successfully
failedJob 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"}
Bulk operations count against your plan’s request limit. Each record in an import counts as one request.