Skip to main content
Use this endpoint to import large volumes of clinical records in NDJSON (newline-delimited JSON) format. Each line of the data field must be a complete, valid JSON object for the specified resource type. Invalid records are skipped and reported in the job’s errors array rather than failing the entire batch. The endpoint returns a jobId immediately; poll the job status endpoint to track progress.

​
Request

POST https://api.clinikapi.com/v1/bulk/import

​
Headers

​
x-api-key
string
required
Your ClinikAPI secret key (clk_live_* or clk_test_*).
​
Content-Type
string
required
Must be application/json.

​
Body

​
resourceType
string
required
The FHIR resource type for all records in this batch (e.g. "Patient"). All lines in data must be valid records of this type.
​
data
string
required
NDJSON payload — one complete JSON object per line, separated by newline characters (\n). Maximum 10,000 records per batch.

​
Response

Returns 202 Accepted immediately. The import job runs asynchronously.
​
data.jobId
string
Unique job identifier (e.g. job_xyz789). Use this to poll for status and check for import errors.
​
data.status
string
Initial job status. Always pending at the time of creation.
​
data.message
string
Human-readable confirmation message.
​
meta
object
Standard response metadata including requestId, timestamp, status, and rate-limit fields.

​
Import rules

  • Maximum 10,000 records per batch.
  • Your tenant tag is automatically injected into each record — you cannot override it.
  • Invalid records are skipped and reported in the job’s errors array.
  • Bulk operations are rate-limited to 5 per hour per tenant.
  • Each imported record counts against your plan’s request limit.

​
Examples

​
curl

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\"}"
  }'

{
  "data": {
    "jobId": "job_xyz789",
    "status": "pending",
    "message": "Import job started"
  }
}

​
TypeScript SDK

import { Clinik } from '@clinikapi/sdk';

const clinik = new Clinik(process.env.CLINIKAPI_SECRET_KEY!);

const ndjson = [
  JSON.stringify({ firstName: 'Jane', lastName: 'Doe', gender: 'female', birthDate: '1990-01-15' }),
  JSON.stringify({ firstName: 'John', lastName: 'Smith', gender: 'male', birthDate: '1985-06-20' }),
].join('\n');

const { data } = await clinik.bulk.import({
  resourceType: 'Patient',
  data: ndjson,
});

console.log(data.jobId); // "job_xyz789"