API Documentation

Authentication

All API requests require an API key in the X-API-Key header. API keys are secured with SHA-256 hashing and one-time retrieval tokens.

curl -X POST https://api.auditable.app/v1/uk/calculate-liability \
  -H "X-API-Key: hmrc_standard_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "hsCode": "7601",
    "originCountry": "CN",
    "massKg": 1000.0
  }'

Calculate Liability

Calculate UK CBAM liability for a single shipment. Returns a final, HMRC-ready submission payload in the exact format required for direct filing.

POST /v1/uk/calculate-liability

{
  "hsCode": "7601",
  "originCountry": "CN",
  "massKg": 1000.0,
  "overseasCarbonPricePaidGbp": null
}

Response:
{
  "embodiedEmissionsTco2e": 2.5,
  "liabilityGbp": 187.50,
  "confidence": {
    "level": "HIGH",
    "liabilityLowerBoundGbp": 187.50,
    "liabilityUpperBoundGbp": 187.50,
    "emissionsLowerBoundTco2e": 2.5,
    "emissionsUpperBoundTco2e": 2.5
  }
}

JavaScript Example

const response = await fetch(
  'https://api.auditable.app/v1/uk/calculate-liability',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'hmrc_standard_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      hsCode: '7601',
      originCountry: 'CN',
      massKg: 1000.0,
    }),
  }
);

const result = await response.json();
console.log('Liability:', result.liabilityGbp);
console.log('Confidence:', result.confidence.level);

Batch Calculations

Process multiple shipments in a single request. Returns final, HMRC-ready submission payloads for each shipment, ready for batch filing.

POST /v1/uk/calculate-liability/batch

{
  "requests": [
    {
      "hsCode": "7601",
      "originCountry": "CN",
      "massKg": 1000.0
    },
    {
      "hsCode": "7207",
      "originCountry": "CN",
      "massKg": 2000.0
    }
  ]
}

Submission-Ready Payloads

Important Notes

• All results are final, HMRC-ready submission payloads ready for direct filing
• Every calculation generates an immutable audit log for regulatory compliance
• Batch calculations produce submission-ready payloads for multiple shipments
• Rate limits apply per subscription tier
• Audit logs are retained for 7 years to meet regulatory requirements

Testing & Validation