Skip to main content

API Setup

Integrate Klervex into your workflow with the REST API.

Get Your API Key​

  1. Go to Settings > API Keys in the Klervex dashboard
  2. Click Create API Key
  3. Give it a descriptive name (e.g., "ERP Integration")
  4. Copy the key — it's only shown once
caution

Store your API key securely. Never commit it to version control or expose it in client-side code.

Base URL​

https://app.klervex.com/api/v1

Authentication​

Include your API key in the Authorization header:

Authorization: Bearer klv_your_api_key_here

Your First API Call​

Create and Validate a Shipment​

curl -X POST https://app.klervex.com/api/v1/shipments/validate \
  -H "Authorization: Bearer klv_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "exporter": {
      "name": "Acme Corp",
      "address": "123 Export St",
      "city": "Los Angeles",
      "country": "US",
      "tax_ids": { "ein": "12-3456789" }
    },
    "importer": {
      "name": "Global Trade GmbH",
      "address": "456 Import Str",
      "city": "Hamburg",
      "country": "DE",
      "tax_ids": { "eori": "DE123456789012345" }
    },
    "route": {
      "origin_country": "US",
      "destination_country": "DE",
      "transport_mode": "sea",
      "incoterms": "CIF",
      "port_of_loading": "USLAX",
      "port_of_discharge": "DEHAM"
    },
    "goods": {
      "currency": "USD",
      "total_value": 25000,
      "line_items": [
        {
          "description": "Electronic components",
          "hs_code": "8542.31.0000",
          "quantity": 500,
          "unit": "PCS",
          "unit_price": 50,
          "origin_country": "US",
          "net_weight_kg": 25
        }
      ]
    },
    "packaging": {
      "total_packages": 5,
      "total_gross_weight_kg": 30,
      "packages": [
        {
          "type": "CARTON",
          "quantity": 5,
          "gross_weight_kg": 6
        }
      ]
    }
  }'

Response​

{
  "valid": true,
  "score": 100,
  "results": [],
  "validated_at": "2026-03-31T10:00:00Z"
}

If validation fails, the response includes specific error details:

{
  "valid": false,
  "score": 75,
  "results": [
    {
      "rule": "hs_code_exists",
      "category": "HS Code",
      "severity": "error",
      "message": "HS code 9999.99.9999 not found in US HTS schedule",
      "field": "goods.line_items[0].hs_code"
    }
  ]
}

Next Steps​