Endpoints

Convert Endpoint

Convert uploaded files to structured clinical data.

Overview

The Convert endpoint allows you to trigger the conversion of uploaded documents to structured clinical data. This endpoint processes files that have been previously uploaded via the Upload endpoint.

Endpoint Details

URL: POST /api/v1/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
`file_id`	string	Yes*	Unique identifier of the uploaded file
`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` (C-CDA, Consolidated Clinical Document Architecture)
`callback_url`	string	No	Webhook URL for job completion notifications
`process_config`	object	Yes	Configuration for the processing type
`output_config`	object	Yes	Configuration for the output format and enrichments

**Either file_id or presigned_url is required.

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.

Request Examples

1. Using file_id

curl -X POST "https://platform.curiflow.com/api/v1/convert" 
  -H "Content-Type: application/json" 
  -H "X-Client-Id: your-client-id" 
  -H "X-Client-Secret: your-client-secret" 
  -d '{
    "file_id": "uuid-file-id-12345",
    "file_type": "pdf",
    "callback_url": "https://your-callback-url.com/webhook",
    "process_config": {
      "tasks": ["clinical_extraction"]
    },
    "output_config": {
      "format": "fhir",
      "include_bbox": false
    }
  }'

const response = await fetch('https://platform.curiflow.com/api/v1/convert', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json',
		'X-Client-Id': 'your-client-id',
		'X-Client-Secret': 'your-client-secret'
	},
	body: JSON.stringify({
		file_id: 'uuid-file-id-12345',
		file_type: 'pdf',
		callback_url: 'https://your-callback-url.com/webhook',
		process_config: {
			tasks: ['clinical_extraction']
		},
		output_config: {
			format: 'fhir',
			include_bbox: false
		}
	})
});

const result = await response.json();

import requests

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

data = {
    "file_id": "uuid-file-id-12345",
    "file_type": "pdf",
    "callback_url": "https://your-callback-url.com/webhook",
    "process_config": {
        "tasks": ["clinical_extraction"]
    },
    "output_config": {
        "format": "fhir",
        "include_bbox": False
    }
}

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

2. Using presigned_url

Use this method when you want to convert a file directly from a time-limited URL (e.g., an S3 presigned URL) without a prior upload step. Setting presigned: true in output_config returns a presigned download URL in the result instead of inline FHIR JSON.

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

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

const result = await response.json();

import requests

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

data = {
    "presigned_url": "https://s3.amazonaws.com/bucket/patient-record.pdf?AWSAccessKeyId=...",
    "file_type": "pdf",
    "callback_url": "https://your-callback-url.com/webhook",
    "process_config": {
        "tasks": ["clinical_extraction"]
    },
    "output_config": {
        "format": "fhir",
        "presigned": True,
        "result_ttl": 15
    }
}

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

3. Dephi (de-identification)

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

curl -X POST "https://platform.curiflow.com/api/v1/convert" 
  -H "Content-Type: application/json" 
  -H "X-Client-Id: your-client-id" 
  -H "X-Client-Secret: your-client-secret" 
  -d '{
    "file_id": "uuid-file-id-12345",
    "file_type": "pdf",
    "callback_url": "https://your-callback-url.com/webhook",
    "process_config": {
      "tasks": ["dephi"]
    },
    "output_config": {
      "format": "pdf"
    }
  }'

const response = await fetch('https://platform.curiflow.com/api/v1/convert', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json',
		'X-Client-Id': 'your-client-id',
		'X-Client-Secret': 'your-client-secret'
	},
	body: JSON.stringify({
		file_id: 'uuid-file-id-12345',
		file_type: 'pdf',
		callback_url: 'https://your-callback-url.com/webhook',
		process_config: {
			tasks: ['dephi']
		},
		output_config: {
			format: 'pdf'
		}
	})
});

const result = await response.json();

import requests

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

data = {
    "file_id": "uuid-file-id-12345",
    "file_type": "pdf",
    "callback_url": "https://your-callback-url.com/webhook",
    "process_config": {
        "tasks": ["dephi"]
    },
    "output_config": {
        "format": "pdf"
    }
}

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

Response Format

Success Response (200 OK)

{
	"message": "Conversion job started successfully",
	"job_id": "job-uuid-12345",
	"file_id": "uuid-file-id-12345"
}

Response Fields

Field	Type	Description
`message`	string	Success message
`job_id`	string	Unique identifier for the conversion job
`file_id`	string	Unique identifier for the uploaded file

Status and Error Codes

HTTP Code	Message
`200`	Conversion job started successfully
`400`	File ID is required
`400`	File type is required
`400`	File type `{file_type}` is not supported. Supported types: `{supported_types}`
`400`	File size is too large.
`400`	File has more than 20 pages
`400`	File type mismatch
`400`	File not found
`400`	File validation failed
`400`	Insufficient credits. Please contact support to upgrade your plan.
`400`	result_ttl must be an integer between 1 and 15 minutes
`401`	X-Client-Id and X-Client-Secret are not valid
`404`	File with ID `{file_id}` was not found
`429`	Too many requests. For more details, visit the page Rate Limits
`500`	Internal error, Please try again later.
`503`	Conversion service is currently unavailable. Please try again later.
`503`	Failed to submit conversion job to processing service
`504`	API gateway timeout

Best Practices

File Validation: Ensure the file_id exists and is valid before conversion
Callback URLs: Use HTTPS for webhook URLs and ensure they’re publicly accessible
Security: Keep your client credentials secure
Bounding Boxes: Only enable include_bbox when your application requires coordinate data, as it incurs additional processing cost.

Next Steps

After successful conversion request, use the returned job_id to:

Check processing status via the Status endpoint
Retrieve results via the Results endpoint
Set up webhooks for real-time notifications via the Console