How it works
Submit shipment details including item descriptions, declared HS codes, country of origin, customs values, and destination details. Each check is a separate mutation you can run independently or together:
Misrepresentation risk
These mutations compare declared values against AI predictions and return probability scores as decimals between 0.0 and 1.0. For these checks, higher = higher risk:
- HS code verification (
classificationsCalculate) - Compares declared HS codes against AI-predicted classifications via Classify. Returns aconfidenceScore— note that this score is inverted: higher = more confident in the HS code, so higher = less risk. Also returnshsCodeProvidedValidationshowing whether the provided code is coherent, valid, or invalid at the chapter, heading, and subheading level. - Country of origin validation (
countryOfOriginValidate) - Verifies declared manufacturing origin against AI-predicted origin via Zonos Country of Origin. ReturnsprobabilityOfMisrepresentation— higher values indicate the declared origin is more likely inaccurate. - Customs value verification (
valueValidate) - Compares declared values against AI-estimated market values via Customs Value. ReturnsprobabilityOfUnderValuationand avalueEstimateRangeto help catch undervaluation.
Restriction checks
These mutations screen items and recipients against known restriction lists:
- Product restriction screening (
restrictionApply) - Checks whether the item faces import restrictions in the destination country, export restrictions from the origin country, or carrier-specific restrictions via Restrict. Returns restrictions with acategory,summary, andconfidencescore. - Denied party screening (
partyScreen) - Screens the shipment recipient against international denied party lists via Screen. Returns anaction(NO_MATCHES,REVIEW, orBLOCK) and match details with name, location, and overall scores.
Modular by design
Clients include only the mutations relevant to their workflow. If you don't need denied party screening or product restrictions, omit partyScreen and restrictionApply—nothing breaks. The name field is required for classificationsCalculate, countryOfOriginValidate, restrictionApply, and valueValidate. If you only have a commodity description and no separate name, map the description to name.
Interpreting scores
Scores are returned as decimals between 0.0 and 1.0 and can be rendered as percentages. Score direction is not uniform across all checks:
probabilityOfUnderValuationonvalueValidate,probabilityOfMisrepresentationoncountryOfOriginValidate, party-match scores (location,name,overall) onpartyScreen, andconfidenceonrestrictionApply: higher = more riskconfidenceScoreonclassificationsCalculate: inverted — higher = more confident in the HS code = less risk
There is no universal LOW/MED/HIGH threshold built into the API—the right cutoffs depend on your risk tolerance, traffic mix, and use case. The recommended approach is to pilot on real shipment traffic and calibrate thresholds against known-good versus known-bad shipments.
Use cases
Customs brokers: Run Greenlight on every shipment before submission to identify misclassified items, incorrect origin declarations, or undervalued goods. Catch compliance issues before they result in delays, penalties, or audits.
Package forwarders: Assess each incoming package for export readiness without requiring specialized trade knowledge from intake staff. Greenlight surfaces exactly which items need attention and why, enabling faster processing with fewer errors.
Carriers and logistics providers: Integrate Greenlight into shipment acceptance workflows to screen packages at the point of pickup or intake. Reject or flag non-compliant shipments before they enter your network, reducing the risk of customs holds and associated costs.
Customs agencies: Use Greenlight to prioritize inspections by focusing on shipments with high misrepresentation risk scores. Low-risk shipments can be fast-tracked, improving throughput while maintaining enforcement accuracy.
API guide
The example below runs all five Greenlight checks in a single operation. Include only the mutations relevant to your workflow.
mutation Greenlight { partyScreen( input: { location: { countryCode: US line1: "123 Haywood Dr" administrativeArea: "Texas" administrativeAreaCode: "TX" locality: "Midland" postalCode: "79707" } person: { firstName: "John" lastName: "Doe" email: "doe11@gmail.com" phone: "4326614277" } } ) { action matches { deniedParty { aliases } scores { location name overall } } } classificationsCalculate( input: { configuration: { hsCodeProvidedTreatment: CHECK_COHERENCE shipToCountries: [CN, IT] hsCodeProvided: "6200.00" } name: "Lumber" description: "A bunch of wood for my treehouse" } ) { hsCode { code countryCode } hsCodeProvidedValidation { code result type } confidenceScore } valueValidate( input: { currency: USD, name: "ball", value: 10.75, material: "plastic" } ) { description name value valueEstimateRange { high low width } probabilityOfUnderValuation } restrictionApply( input: { items: { name: "Flashlight" hsCode: "6211.32" description: "Blue plastic flashlight" restrictionCategories: PROHIBITED } shipFromCountry: CN shipToCountry: US } ) { id items { restrictions { category summary confidence } } } countryOfOriginValidate( input: { amount: 12 currencyCode: USD countryOfOrigin: CN name: "Flashlight" } ) { amount countryOfOrigin probabilityOfMisrepresentation primaryTargetCountryCode }}Getting started
Zonos Greenlight requires a subscription. To learn more about access, pricing, and API integration, contact sales.
Zonos Greenlight
Verify that shipments are compliant and ready for export.
Zonos Greenlight provides a comprehensive export readiness assessment for international shipments. It runs AI-powered checks across five areas: HS code accuracy, country of origin validation, customs value verification, product restrictions, and denied party screening.
Greenlight is a workflow of five independent mutations—you include only the checks you need. Each mutation returns its own shape and score, giving you per-check results to interpret and act on however fits your system.