API Documentation — PierForge

API Overview

The PierForge REST API provides programmatic access to HS code classification, tariff calculation, trade document generation, and trade intelligence alerts. All requests and responses are JSON. Authentication uses an API key in a header.

Base URL: https://api.pierforge.com

Disclaimer: Classifications and tariff calculations are indicative. They do not constitute professional customs or legal advice. All customs filings and duty payments require verification by a licensed customs broker. Band D actions (filing, payment) require human sign-off and are not executable via API alone.

Authentication

Pass your API key in the X-API-Key header on every request. API keys start with pk_live_ for production or pk_test_ for sandbox.

cURL
curl https://api.pierforge.com/v1/health \
  -H "X-API-Key: pk_live_YOUR_KEY_HERE"

Note: API access is available on Growth and Enterprise plans. Starter accounts use the dashboard interface only.

Errors

All errors return JSON with ok: false and an error object.

JSON — Error response
{
  "ok": false,
  "error": {
    "code": "INVALID_HS_INPUT",
    "message": "product.category is required",
    "status": 400
  }
}

HTTP Status	Code	Description
400	INVALID_INPUT	Missing or malformed request field
401	UNAUTHORIZED	Missing or invalid API key
402	PLAN_LIMIT	Monthly plan limit reached
429	RATE_LIMITED	Too many requests — back off and retry
500	INTERNAL_ERROR	Server error — contact support

Rate Limits

Growth plan: 60 RPM, 5,000 RPD. Enterprise: custom. Rate limit headers are included in every response.

Response headers
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1714500060

On 429, wait until X-RateLimit-Reset (Unix timestamp) before retrying. Use exponential backoff for batch jobs.

Endpoints

GET /v1/health

Health check. Returns API status and current version. No authentication required.

Response
{ "ok": true, "version": "1.0.0", "status": "operational" }

POST /v1/classify

Classify a single product. Returns HS code, regulatory status, duty rates, and required documents for the specified destination market.

Request body

Field	Type	Required	Description
market	string	Required	Destination market code: `CN` · `HK` · `SG` · `TH` · `MY`
product	object	Required	Product object — see Product Schema

cURL Example
curl -X POST https://api.pierforge.com/v1/classify \
  -H "X-API-Key: pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "market": "CN",
    "product": {
      "productId": "P-001",
      "name": "Elderflower Extract 50ml",
      "originCountry": "HK",
      "destCountry": "CN",
      "category": "herbal_extract",
      "grossWeightG": 120,
      "netWeightG": 100,
      "declaredValueCny": 420,
      "ingredients": ["elderflower", "ethanol"],
      "containsRegulatedSubstances": false,
      "shelfLifeDays": 730,
      "storageRequirements": "ambient",
      "registrationNumbers": {}
    }
  }'

Response
{
  "ok": true,
  "classification": {
    "hsCode": "1302.19.90",
    "cnCustomsCategory": "植物提取物",
    "status": "requires_registration",
    "importDutyRate": 0.10,
    "cepaRate": 0.00,
    "vatRate": 0.09,
    "cnRegistrationRequired": true,
    "cnLabel3Required": true,
    "requiredDocuments": ["CFS", "CN Label 3", "GACC registration"],
    "prohibitedIngredients": [],
    "confidence": 0.88,
    "confidenceNote": "confirmed-from-rules",
    "estimatedProcessingDays": 14
  }
}

POST /v1/classify/batch

Classify up to 50 products in a single call. Returns an array of classification results in the same order as the input products array.

Request body

Field	Type	Required	Description
market	string	Required	Destination market (applies to all products in batch)
products	array	Required	Array of product objects. Max 50 items.

Response (abbreviated)
{
  "ok": true,
  "results": [
    { "productId": "P-001", "classification": { ... } },
    { "productId": "P-002", "classification": { ... } }
  ],
  "flagged": [
    {
      "productId": "P-003",
      "reason": "confidence below 0.75 — broker review recommended",
      "confidence": 0.62
    }
  ]
}

POST /v1/tariff/calculate

Calculate landed cost for a shipment. Returns MFN duty, preferential rate (CEPA/RCEP), VAT, additional taxes, and a line-by-line landed cost breakdown.

Request body

Field	Type	Required	Description
hsCode	string	Required	HS code (6–10 digits)
fromCountry	string	Required	ISO 2-letter origin country
toCountry	string	Required	ISO 2-letter destination country
declaredValueCny	number	Required	Declared customs value in CNY
freightCny	number	Optional	Freight cost in CNY (included in CIF value)
agreementType	string	Optional	`CEPA` · `RCEP` · `MFN` · `CBEC` · auto-detected if omitted

Response
{
  "ok": true,
  "landedCost": {
    "declaredValueCny": 420.00,
    "freightCny": 65.00,
    "cifValueCny": 485.00,
    "mfnDuty": { "rate": 0.10, "amountCny": 48.50 },
    "preferentialDuty": { "type": "CEPA", "rate": 0.00, "amountCny": 0.00 },
    "appliedDutyAmountCny": 0.00,
    "vatAmountCny": 43.65,
    "totalLandedCostCny": 528.65,
    "saving": { "type": "CEPA", "amountCny": 48.50 },
    "disclaimer": "Indicative only. Verify with customs broker before filing."
  }
}

GET /v1/intelligence/alerts

Fetch trade policy change alerts for your subscribed corridors. Filter by corridor, HS heading, or alert type.

Query parameters

Param	Type	Description
corridor	string	e.g. `HK-CN` · `CN-SG` · `US-CN`
hsPrefix	string	Filter alerts affecting this HS prefix (e.g. `1108`)
type	string	`cepa` · `rcep` · `cbec` · `tariff` · `regulatory`
since	string	ISO date — only alerts after this date
limit	number	Max alerts to return (default: 20, max: 100)

Product Schema

Field	Type	Required	Description
productId	string	Required	Your internal product identifier
name	string	Required	Product name (used for audit trail)
originCountry	string	Required	ISO 2-letter country of origin
destCountry	string	Required	ISO 2-letter destination country
category	string	Required	Product category — see category list in API reference
declaredValueCny	number	Required	Declared customs value in CNY
ingredients	string[]	Required	Ingredient or material list (used for regulatory checks)
grossWeightG	number	Optional	Gross weight in grams
hsCode	string	Optional	Known HS code — if provided, skips classification, validates only
containsRegulatedSubstances	boolean	Optional	Flag for additional regulated-substance checks
registrationNumbers	object	Optional	Known registration numbers by market: `{ "CN": "SC..." }`