Endpoints

Bulk Convert Endpoint

Submit multiple files for conversion to structured clinical data in a single request.

Overview

The Bulk Convert endpoint allows you to trigger the conversion of multiple documents simultaneously. This is designed for high-volume workflows, bulk data imports, allowing you to manage hundreds of files without making individual API calls for each document.

Enterprise only

The Bulk Convert endpoint is only available for Enterprise customers. Please contact our support team to enable this feature for your organization.

Endpoint Details

URL: POST /api/v1/bulk-convert Content-Type: application/json

Request Parameters

Headers

Header	Type	Required	Description
`X-Client-Id`	string	Yes	Client ID from the API keys
`X-Client-Secret`	string	Yes	Client secret from the API keys
`Content-Type`	string	Yes	Must be `application/json`

Request Body

Parameter	Type	Required	Description
`files`	array	Yes	Array of file objects to process.
`process_config`	object	Yes	Configuration for the processing type. Applied to all files in the batch.
`output_config`	object	Yes	Configuration for the output format and enrichments. Applied to all files in the batch.
`batch_callback_url`	string	Optional	A single webhook URL to receive notifications for all files in this batch.

*Note: You can provide either a batch_callback_url at the root level OR a callback_url for every individual file in the files array.

File limit per request: Maximum of 30 files per request.

Process Config

Parameter	Type	Required	Description
`tasks`	array of strings	Yes	A one-item list containing the processing type to run

Processing types - tasks is a one-item list naming the type to run:

Type	Input	Output	Description
`clinical_extraction`	`pdf`, `ccda`	`fhir` or `json`	Extract structured clinical data from the document.
`dephi`	`pdf`	`pdf` (presigned URL only)	De-identify a PDF by removing protected health information (PHI).

A dephi result is a binary PDF, delivered only through a presigned URL. At request time, set output_config.presigned to true or omit it (false is invalid), then retrieve the file from the Results endpoint with presigned=true.

Output Config

Parameter	Type	Required	Default	Description
`format`	string	Yes	-	Output format for the result. Accepted values: `fhir`, `json`, `pdf`
`include_bbox`	boolean	Not required	`false`	Whether to include bounding box coordinates for extracted entities. Incurs additional cost when enabled.
`presigned`	boolean	Not required	`false`	If `true`, the webhook callback includes a presigned download URL instead of the result in the body. If `false` or omitted, the structured result is returned inline (default).
`result_ttl`	integer	Not required	`5` (minutes)	When `presigned` is `true`, controls how long the presigned result URL in the success webhook callback remains valid. Integer minutes in the inclusive range `1` to `15`. When omitted, the default is five minutes. Applied to all files in the batch.

File Object Structure

Parameter	Type	Required	Description
`presigned_url`	string	Yes	The fully-qualified, time-limited URL (such as an S3 presigned URL) to securely access and download the source file to be converted. The URL must be accessible by the platform and valid for the duration of processing.
`file_type`	string	Yes	Type of file: `pdf` or `ccda`
`callback_url`	string	Optional	Specific webhook URL for this individual file’s completion event.

Request Examples

1. Batch Callback Only

Provide a batch_callback_url if you want to receive job notifications for all files in the bulk request at the same callback URL. Job notifications for each individual file will be sent separately to the callback URL (either the batch or per-file webhook), ensuring that you receive a distinct notification for each conversion job upon its completion.

curl -X POST "https://platform.curiflow.com/api/v1/bulk-convert" 
  -H "Content-Type: application/json" 
  -H "X-Client-Id: your-client-id" 
  -H "X-Client-Secret: your-client-secret" 
  -d '{
    "batch_callback_url": "https://your-callback-url.com/webhook",
    "process_config": {
      "tasks": ["clinical_extraction"]
    },
    "output_config": {
      "format": "fhir",
      "include_bbox": false,
      "presigned": true,
      "result_ttl": 15
    },
    "files": [
      {
        "presigned_url": "https://s3.amazonaws.com/bucket/file1.pdf",
        "file_type": "pdf"
      },
      {
        "presigned_url": "https://s3.amazonaws.com/bucket/file2.pdf",
        "file_type": "pdf"
      }
    ]
  }'

const response = await fetch('https://platform.curiflow.com/api/v1/bulk-convert', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json',
		'X-Client-Id': 'your-client-id',
		'X-Client-Secret': 'your-client-secret'
	},
	body: JSON.stringify({
		batch_callback_url: 'https://your-callback-url.com/webhook',
		process_config: {
			tasks: ['clinical_extraction']
		},
		output_config: {
			format: 'fhir',
			include_bbox: false,
			presigned: true,
			result_ttl: 15
		},
		files: [
			{ presigned_url: 'https://s3.amazonaws.com/bucket/file1.pdf', file_type: 'pdf' },
			{ presigned_url: 'https://s3.amazonaws.com/bucket/file2.pdf', file_type: 'pdf' }
		]
	})
});

const result = await response.json();

import requests

url = "https://platform.curiflow.com/api/v1/bulk-convert"
headers = {
    "Content-Type": "application/json",
    "X-Client-Id": "your-client-id",
    "X-Client-Secret": "your-client-secret"
}

payload = {
    "batch_callback_url": "https://your-callback-url.com/webhook",
    "process_config": {
        "tasks": ["clinical_extraction"]
    },
    "output_config": {
        "format": "fhir",
        "include_bbox": False,
        "presigned": True,
        "result_ttl": 15
    },
    "files": [
        { "presigned_url": "https://s3.amazonaws.com/bucket/file1.pdf", "file_type": "pdf" },
        { "presigned_url": "https://s3.amazonaws.com/bucket/file2.pdf", "file_type": "pdf" }
    ]
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()

2. Individual Callbacks Only

Use this method when each file in your bulk request needs to trigger its own callback URL, by specifying a callback_url for every file.

curl -X POST "https://platform.curiflow.com/api/v1/bulk-convert" 
  -H "Content-Type: application/json" 
  -H "X-Client-Id: your-client-id" 
  -H "X-Client-Secret: your-client-secret" 
  -d '{
    "process_config": {
      "tasks": ["clinical_extraction"]
    },
    "output_config": {
      "format": "fhir",
      "include_bbox": false
    },
    "files": [
      {
        "presigned_url": "https://s3.amazonaws.com/bucket/file1.pdf",
        "file_type": "pdf",
        "callback_url": "https://specific-callback.com/file1"
      },
      {
        "presigned_url": "https://s3.amazonaws.com/bucket/file2.pdf",
        "file_type": "pdf",
        "callback_url": "https://specific-callback.com/file2"
      }
    ]
  }'

const response = await fetch('https://platform.curiflow.com/api/v1/bulk-convert', {
    method: 'POST',
    headers: {
		'Content-Type': 'application/json',
		'X-Client-Id': 'your-client-id',
		'X-Client-Secret': 'your-client-secret'
	},
    body: JSON.stringify({
        process_config: {
            tasks: ['clinical_extraction']
        },
        output_config: {
            format: 'fhir',
            include_bbox: false
        },
        files: [
            {
                presigned_url: 'https://s3.amazonaws.com/bucket/file1.pdf',
                file_type: 'pdf',
                callback_url: 'https://specific-callback.com/file1'
            },
            {
                presigned_url: 'https://s3.amazonaws.com/bucket/file2.pdf',
                file_type: 'pdf',
                callback_url: 'https://specific-callback.com/file2'
            }
        ]
    })
});

const result = await response.json();

import requests

url = "https://platform.curiflow.com/api/v1/bulk-convert"
headers = {
    "Content-Type": "application/json",
    "X-Client-Id": "your-client-id",
    "X-Client-Secret": "your-client-secret"
}
payload = {
    "process_config": {
        "tasks": ["clinical_extraction"]
    },
    "output_config": {
        "format": "fhir",
        "include_bbox": False
    },
    "files": [
        {
            "presigned_url": "https://s3.amazonaws.com/bucket/file1.pdf",
            "file_type": "pdf",
            "callback_url": "https://specific-callback.com/file1"
        },
        {
            "presigned_url": "https://s3.amazonaws.com/bucket/file2.pdf",
            "file_type": "pdf",
            "callback_url": "https://specific-callback.com/file2"
        }
    ]
}
response = requests.post(url, headers=headers, json=payload)
result = response.json()

3. Mixed (batch + individual)

If a file specifies its own callback_url, that URL will be used for notifications for that file. For files without an explicit callback_url, the batch_callback_url is used as the default.

In this example: file1 uses priority-webhook for notifications, while file2 falls back to the fallback-webhook.

curl -X POST "https://platform.curiflow.com/api/v1/bulk-convert" 
  -H "Content-Type: application/json" 
  -H "X-Client-Id: your-client-id" 
  -H "X-Client-Secret: your-client-secret" 
  -d '{
    "batch_callback_url": "https://fallback-webhook.com/general",
    "process_config": {
      "tasks": ["clinical_extraction"]
    },
    "output_config": {
      "format": "fhir",
      "include_bbox": false
    },
    "files": [
      {
        "presigned_url": "https://s3.amazonaws.com/bucket/file1.pdf",
        "file_type": "pdf",
        "callback_url": "https://priority-webhook.com/file1"
      },
      {
        "presigned_url": "https://s3.amazonaws.com/bucket/file2.pdf",
        "file_type": "pdf"
      }
    ]
  }'

const response = await fetch('https://platform.curiflow.com/api/v1/bulk-convert', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json',
		'X-Client-Id': 'your-client-id',
		'X-Client-Secret': 'your-client-secret'
	},
	body: JSON.stringify({
		batch_callback_url: 'https://fallback-webhook.com/general',
		process_config: {
			tasks: ['clinical_extraction']
		},
		output_config: {
			format: 'fhir',
			include_bbox: false
		},
		files: [
			{ presigned_url: 'https://s3.amazonaws.com/bucket/file1.pdf', file_type: 'pdf', callback_url: 'https://priority-webhook.com/file1' },
			{ presigned_url: 'https://s3.amazonaws.com/bucket/file2.pdf', file_type: 'pdf' }
		]
	})
});

const result = await response.json();

import requests

url = "https://platform.curiflow.com/api/v1/bulk-convert"
headers = {
    "Content-Type": "application/json",
    "X-Client-Id": "your-client-id",
    "X-Client-Secret": "your-client-secret"
}

payload = {
    "batch_callback_url": "https://fallback-webhook.com/general",
    "process_config": {
        "tasks": ["clinical_extraction"]
    },
    "output_config": {
        "format": "fhir",
        "include_bbox": False
    },
    "files": [
        {
            "presigned_url": "https://s3.amazonaws.com/bucket/file1.pdf",
            "file_type": "pdf",
            "callback_url": "https://priority-webhook.com/file1"
        },
        {
            "presigned_url": "https://s3.amazonaws.com/bucket/file2.pdf",
            "file_type": "pdf"
        }
    ]
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()

4. Dephi (de-identification)

Submit a batch of dephi requests to de-identify PDFs - each removes protected health information (PHI) and returns a de-identified PDF. Retrieve each result from the Results endpoint with presigned=true.

curl -X POST "https://platform.curiflow.com/api/v1/bulk-convert" 
  -H "Content-Type: application/json" 
  -H "X-Client-Id: your-client-id" 
  -H "X-Client-Secret: your-client-secret" 
  -d '{
    "batch_callback_url": "https://your-callback-url.com/webhook",
    "process_config": {
      "tasks": ["dephi"]
    },
    "output_config": {
      "format": "pdf"
    },
    "files": [
      {
        "presigned_url": "https://s3.amazonaws.com/bucket/file1.pdf",
        "file_type": "pdf"
      },
      {
        "presigned_url": "https://s3.amazonaws.com/bucket/file2.pdf",
        "file_type": "pdf"
      }
    ]
  }'

const response = await fetch('https://platform.curiflow.com/api/v1/bulk-convert', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json',
		'X-Client-Id': 'your-client-id',
		'X-Client-Secret': 'your-client-secret'
	},
	body: JSON.stringify({
		batch_callback_url: 'https://your-callback-url.com/webhook',
		process_config: {
			tasks: ['dephi']
		},
		output_config: {
			format: 'pdf'
		},
		files: [
			{ presigned_url: 'https://s3.amazonaws.com/bucket/file1.pdf', file_type: 'pdf' },
			{ presigned_url: 'https://s3.amazonaws.com/bucket/file2.pdf', file_type: 'pdf' }
		]
	})
});

const result = await response.json();

import requests

url = "https://platform.curiflow.com/api/v1/bulk-convert"
headers = {
    "Content-Type": "application/json",
    "X-Client-Id": "your-client-id",
    "X-Client-Secret": "your-client-secret"
}

payload = {
    "batch_callback_url": "https://your-callback-url.com/webhook",
    "process_config": {
        "tasks": ["dephi"]
    },
    "output_config": {
        "format": "pdf"
    },
    "files": [
        { "presigned_url": "https://s3.amazonaws.com/bucket/file1.pdf", "file_type": "pdf" },
        { "presigned_url": "https://s3.amazonaws.com/bucket/file2.pdf", "file_type": "pdf" }
    ]
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()

Response Format

Success Response (200 OK)

{
	"message": "Bulk conversion requests submitted",
	"count": 2,
	"jobs": [
		{
			"job_id": "job-uuid-1",
			"presigned_url": "https://s3.amazonaws.com/bucket/file1.pdf"
		},
		{
			"job_id": "job-uuid-2",
			"presigned_url": "https://s3.amazonaws.com/bucket/file2.pdf"
		}
	]
}

Response Fields

Field	Type	Description
`message`	string	Success confirmation message
`count`	integer	Total number of jobs successfully queued
`jobs`	array	List of created job_ids along with source URLs

Status and Error Codes

HTTP Code	Message
`200`	Bulk conversion requests submitted
`400`	Invalid request payload
`400`	files array is required
`400`	files array cannot be empty
`400`	File at index `{index}` must be a valid JSON object/dictionary
`400`	presigned_url is required for file at index `{index}`
`400`	result_ttl must be an integer between 1 and 15 minutes
`401`	X-Client-Id and X-Client-Secret are not valid
`429`	Too many requests. For more details, visit the page Rate Limits
`500`	Internal error processing bulk request
`500`	Failed to submit batch to processor

Best Practices

URL Validity: Provide a minimum one-hour expiration window for the presigned_url to ensure all the files in a batch are processed.
Async Workflow: Do not poll for status for large batches; rely on webhooks to trigger downstream processing in your application.
Bounding Boxes: Only enable include_bbox when your application requires coordinate data, as it incurs additional processing cost across all files in the batch.

Next Steps

After submitting a bulk request:

Monitor individual job progress via the Status endpoint.
Retrieve results via the Results endpoint
Query individual job details using the returned job_id via the Status endpoint.