Building custom trade reports with Camtom API

Why build custom reports with the API

While Camtom's built-in reporting covers most standard use cases, organizations with complex supply chains often need custom analytics that combine trade data with internal business metrics. The Camtom REST API provides programmatic access to all your import and export data, enabling you to build custom dashboards, automated reports, and data pipelines that integrate with your existing business intelligence tools.

Step 1: Set up API authentication

All API requests require authentication using an API key. Generate your API key from the Camtom dashboard under Settings > API Keys. Each key can be scoped to specific permissions: read-only for reporting, or read-write for operations that modify data.

1. Navigate to Settings > API Keys in your Camtom dashboard
2. Click 'Generate new API key'
3. Select 'Read-only' scope for reporting purposes
4. Copy the key and store it securely in your environment variables
5. Never expose API keys in client-side code or version control

Step 2: Understand the data model

The Camtom API organizes trade data around three core entities: entries (the customs entry or pedimento), line items (individual products within an entry), and documents (supporting files like invoices and certificates). Each entity has relationships to others and can be queried independently or joined in a single request.

• Entries: contain header-level data such as entry number, date, port, importer, and total value
• Line items: contain product-level data including HTS code, description, quantity, value, and duty amounts
• Documents: linked files such as commercial invoices, bills of lading, and certificates
• Parties: importers, exporters, and suppliers referenced by entries
• Classifications: HTS/tariff classification history with confidence scores

Step 3: Query entries for your report

The entries endpoint supports filtering by date range, port of entry, importer, HTS code, and entry status. For large datasets, use pagination with cursor-based navigation. The API returns JSON responses with consistent field naming and ISO 8601 date formats.

1. Use the GET /api/v1/entries endpoint with query parameters for filtering
2. Filter by date range using date_from and date_to parameters in YYYY-MM-DD format
3. Filter by HTS code prefix to analyze specific product categories
4. Use the include parameter to embed related line items in the response
5. Paginate results using cursor and limit parameters (max 100 per page)

Step 4: Aggregate data for analytics

The API includes an aggregation endpoint that performs server-side calculations, reducing the amount of data you need to transfer and process. You can group by any field and apply sum, average, count, min, and max functions to numeric fields.

1. Use POST /api/v1/analytics/aggregate for server-side aggregation
2. Specify group_by fields: hts_code, country_of_origin, port_of_entry, month, quarter
3. Apply metrics: sum of duty_amount, average of unit_value, count of entries
4. Add filters to narrow the aggregation scope
5. Results are returned pre-sorted by the primary group_by field

Step 5: Build the report output

With the aggregated data in hand, format the output for your stakeholders. Common output formats include JSON for dashboards, CSV for spreadsheet analysis, and PDF for formal reports. The API can generate CSV and PDF directly using the Accept header, or you can process the JSON response in your own application.

Step 6: Automate report generation

Set up a scheduled job (cron, cloud function, or workflow automation tool) to call the API, generate the report, and distribute it to stakeholders. Camtom also supports webhooks that can trigger your report pipeline whenever new entries are filed, enabling near-real-time reporting.

1. Create a script or cloud function that calls the API endpoints
2. Schedule it to run daily, weekly, or monthly based on your needs
3. Store the output in your data warehouse or send it via email
4. Set up error handling and retry logic for API rate limits
5. Configure webhooks for event-driven report updates

Example report: Monthly duty analysis

A common custom report aggregates duties paid by HTS chapter, compares them month-over-month, and identifies the top 10 products by duty amount. This report helps trade compliance teams spot unusual duty spikes that might indicate classification errors or tariff changes, and helps finance teams forecast future duty obligations.

Rate limits and best practices

• The API allows 100 requests per minute per API key
• Use bulk endpoints when fetching large datasets instead of individual record requests
• Cache results locally when the data does not change frequently
• Use conditional requests with If-Modified-Since headers to reduce unnecessary data transfer
• Monitor your API usage in the Camtom dashboard under Settings > API Usage