Skip to main content

Extraction API

Upload documents for AI-powered data extraction.

Submit Extraction​

Upload a file for AI extraction. Returns a job ID for polling.

POST /api/v1/extract
Content-Type: multipart/form-data

Request​

FieldTypeRequiredDescription
fileFileYesThe document to extract (PDF, PNG, JPG, TIFF, XLS, XLSX)
shipment_idstringNoAssociate with an existing shipment

Response​

{
  "job_id": "job_ext_a1b2c3d4",
  "status": "processing",
  "created_at": "2026-03-31T10:00:00Z"
}

Get Extraction Status​

Poll the extraction job until it completes.

GET /api/v1/extract/:jobId

Response (Processing)​

{
  "job_id": "job_ext_a1b2c3d4",
  "status": "processing",
  "created_at": "2026-03-31T10:00:00Z"
}

Response (Completed)​

{
  "job_id": "job_ext_a1b2c3d4",
  "status": "completed",
  "result": {
    "exporter": {
      "name": { "value": "Acme Corp", "confidence": 0.95 },
      "address": { "value": "123 Export St", "confidence": 0.88 },
      "country": { "value": "US", "confidence": 0.97 }
    },
    "importer": {
      "name": { "value": "Global Trade GmbH", "confidence": 0.93 },
      "country": { "value": "DE", "confidence": 0.96 }
    },
    "goods": {
      "line_items": [
        {
          "description": { "value": "Electronic components", "confidence": 0.91 },
          "hs_code": { "value": "8542.31.0000", "confidence": 0.72 },
          "quantity": { "value": 500, "confidence": 0.94 },
          "unit_price": { "value": 50, "confidence": 0.89 }
        }
      ]
    }
  },
  "completed_at": "2026-03-31T10:00:15Z"
}

Response (Failed)​

{
  "job_id": "job_ext_a1b2c3d4",
  "status": "failed",
  "error": {
    "code": "KLV_EXTRACT_002",
    "message": "Could not extract data from the uploaded document"
  }
}

Polling Strategy​

Poll every 2 seconds for up to 60 seconds:

async function waitForExtraction(jobId) {
  for (let i = 0; i < 30; i++) {
    const res = await fetch(`/api/v1/extract/${jobId}`, {
      headers: { Authorization: `Bearer ${apiKey}` }
    });
    const job = await res.json();

    if (job.status === 'completed') return job.result;
    if (job.status === 'failed') throw new Error(job.error.message);

    await new Promise(r => setTimeout(r, 2000));
  }
  throw new Error('Extraction timed out');
}