Integrate Camtom via REST API

API Architecture Overview

The Camtom API follows REST principles and uses JSON as its data interchange format. All endpoints require authentication via an API key sent in the Authorization header. The API is versioned (currently v2) and maintains backward compatibility within the same major version. The base URL is https://api.camtom.com/v2 and all communication is encrypted over HTTPS.

Step 1: Obtain Your API Credentials

From your Camtom dashboard, navigate to Settings > API > Generate Key. You will receive a production key (sk_live_...) and a sandbox key (sk_test_...). Store the key securely — it will not be displayed again. If you lose it, generate a new one and revoke the old key immediately. The sandbox key gives full access to the test environment without affecting production data.

Step 2: Authentication

Every request must include your API key in the Authorization header using the Bearer scheme. If the key is missing, malformed, or revoked, the API returns a 401 Unauthorized response with a descriptive error message. Example header: Authorization: Bearer sk_live_your_key_here.

Step 3: Core Endpoints

• POST /v2/classify — Send a product description and receive HTS code suggestions with confidence scores.
• POST /v2/documents/extract — Upload a commercial invoice (PDF or image) and receive structured data.
• GET /v2/tariff/{code} — Look up details for a specific HTS code: duty rate, regulations, and notes.
• POST /v2/clients — Create or update a client compliance profile in KYB.
• GET /v2/clients/{id}/status — Check a client's compliance status and document expiration dates.

Step 4: Classification Request Example

To classify a product, send a POST request to /v2/classify with a JSON body containing the description field. The response includes an array of suggestions sorted by confidence, each with the HTS code, official description, duty rate, regulatory notes, and a confidence score between 0 and 1. A score above 0.85 indicates high confidence. Here is an example using Python:

import requests response = requests.post( 'https://api.camtom.com/v2/classify', headers={'Authorization': 'Bearer sk_live_your_key'}, json={'description': 'Stainless steel hex bolts, 10mm, industrial use'} ) results = response.json()['suggestions'] for r in results: print(f"{r['code']} — {r['confidence']:.0%} — {r['description']}")

Step 5: Document Extraction Example

To extract data from a commercial invoice, send a POST request to /v2/documents/extract with the file as a multipart form upload. The response includes supplier details, buyer details, invoice metadata, and a structured line-item table. For large or complex documents, processing may take a few seconds — the response includes a status field. Here is an example using JavaScript (Node.js):

const FormData = require('form-data'); const fs = require('fs'); const axios = require('axios'); const form = new FormData(); form.append('file', fs.createReadStream('invoice.pdf')); const { data } = await axios.post( 'https://api.camtom.com/v2/documents/extract', form, { headers: { ...form.getHeaders(), Authorization: 'Bearer sk_live_your_key' } } ); console.log(data.supplier, data.lineItems);

Step 6: Rate Limits and Error Handling

The API uses standard HTTP status codes: 200 for success, 400 for validation errors (check the errors array in the response), 401 for authentication failures, 429 for rate limit exceeded, and 500 for internal server errors. The default rate limit is 100 requests per minute. If you exceed it, you will receive a 429 response with a Retry-After header indicating how many seconds to wait. For higher limits, contact your account manager.

Step 7: Webhooks for Asynchronous Processing

For operations that take longer — such as complex document extraction or bulk classification — you can register a webhook URL in your dashboard under Settings > API > Webhooks. Camtom will send a POST to your endpoint when processing completes, including the full results payload. Webhook payloads are signed with an HMAC-SHA256 signature in the X-Camtom-Signature header so you can verify authenticity.

Official SDKs

If you prefer not to work directly with the REST API, Camtom offers official SDKs for Node.js, Python, and Go. The SDKs handle authentication, automatic retries with exponential backoff, pagination, and type-safe responses. Install via npm (camtom-sdk), pip (camtom), or go get (github.com/camtom/sdk-go). Each SDK includes comprehensive documentation and working examples.

Next Steps

Explore the full API reference at camtomx.com/developers for detailed endpoint documentation, request and response schemas, and interactive examples. If you run into issues, our developer support team is available via the in-app chat or at developers@camtomx.com.