Convert

Convert

Resource for converting documents to structured data using OCR. Access via client.convert.

Methods

run(params, options?)

Creates a synchronous conversion request. The API processes the document and returns the result.

const result = await client.convert.run({
  documentTypeCode: 'invoice',
  url: 'https://example.com/invoice.pdf',
});

console.log(result.data);       // extracted data
console.log(result.validation); // validation of the extracted data

Pass documentMetadata to attach your own data: the API echoes it in the conversion status and in webhooks. A failed sync conversion throws instead of returning a result.

validation is informational: it never changes the conversion outcome. See ConversionValidation.

Parameters: ConvertParams Returns: Promise<ConversionResult>

runAsync(params, options?)

Creates an asynchronous conversion request. Returns the enqueue response (conversion_id, status_url and status: 'ENQUEUED') with a .wait() method for polling.

import fs from 'fs';

const enqueued = await client.convert.runAsync({
  documentTypeCode: 'invoice',
  file: fs.readFileSync('invoice.pdf'),
});
console.log(enqueued.conversion_id);

// Poll until SUCCESS or ERROR
const result = await enqueued.wait({ onStatus: (s) => console.log(s.status) });
if (result.status === 'SUCCESS') {
  console.log(result.data);
} else {
  console.log(result.error);
}

wait() accepts WaitOptions (pollInterval, timeout, onStatus) and resolves with the final status on both SUCCESS and ERROR: it does not throw when the operation fails, so check status. It rejects only on timeout (APITimeoutError) or when a status request fails.

Parameters: ConvertParams Returns: Promise<ConversionEnqueued & { wait(options?): Promise<ConversionStatus> }>

getStatus(conversionId, options?)

Retrieves the current status of a conversion operation. wait() calls it for you.

const status = await client.convert.getStatus('conv_abc123');

Parameters: conversionId: string Returns: Promise<ConversionStatus>

Raw Responses

Access raw HTTP response details via withRawResponse:

const raw = await client.convert.withRawResponse.run({
  documentTypeCode: 'invoice',
  url: 'https://example.com/invoice.pdf',
});

console.log(raw.statusCode); // 200
console.log(raw.headers);    // Response headers
const data = await raw.parse(); // Parsed body