API Documentation

Overview

The Maxline REST API allows Enterprise plan subscribers to integrate customs automation directly into their systems. Process declarations, classify goods, and retrieve historical data programmatically.

Base URL

https://api.maxlinesez.com/v1

All API requests must use HTTPS. HTTP requests are rejected.

Authentication

All API requests require authentication using a Bearer token. Generate your API key in your Maxline account settings.

Request Header:

Authorization: Bearer $MAXLINE_API_KEYxxxxxxxx

Keep your API key secret. Never commit it to version control or share it publicly.

Rate Limits

Rate limits depend on your subscription plan:

Starter

100/min

1,000 requests per day

Professional

500/min

5,000 requests per day

Enterprise

2000/min

Custom limits available

Rate limit status is returned in response headers: X-RateLimit-Remaining

API Endpoints

POST/declarations

Create a new customs declaration.

Request Body:

{
  "declaration_type": "IM5",
  "office_code": "SC001",
  "importer_name": "John's Imports Ltd",
  "exporter_name": "Shanghai Trading Co.",
  "goods": [
    {
      "description": "Laptop computers",
      "hs_code": "847130",
      "quantity": 50,
      "unit": "pcs",
      "unit_price": 800,
      "origin": "CN"
    }
  ],
  "freight": 500,
  "insurance": 150,
  "incoterms": "CIF"
}

Response (201 Created):

{
  "id": "decl_abc123",
  "status": "draft",
  "total_duties_scr": 2450,
  "total_vat_scr": 3675,
  "grand_total_scr": 6125,
  "created_at": "2026-03-22T10:30:00Z"
}

GET/declarations/{id}

Retrieve declaration details and status.

Request:

GET /declarations/decl_abc123

Response (200 OK):

{
  "id": "decl_abc123",
  "status": "released",
  "risk_lane": "green",
  "goods_items": 1,
  "total_value_scr": 40000,
  "total_duties_scr": 2450,
  "submitted_at": "2026-03-22T11:15:00Z",
  "released_at": "2026-03-22T12:00:00Z"
}

POST/documents/process

Process a shipping document and extract data.

Request (multipart/form-data):

POST /documents/process
Content-Type: multipart/form-data

file: [binary PDF/JPEG]
document_type: "invoice"

Response (200 OK):

{
  "id": "doc_xyz789",
  "document_type": "invoice",
  "extracted_data": {
    "shipper": {
      "name": "Shanghai Trading Co.",
      "confidence": 0.95
    },
    "goods_description": "Laptop computers",
    "quantity": 50,
    "unit_price": 800,
    "currency": "USD"
  }
}

GET/hs-codes/classify

Classify goods using AI and get HS code recommendations.

Request:

GET /hs-codes/classify?description=Laptop+computers&origin=CN

Response (200 OK):

{
  "suggestions": [
    {
      "hs_code": "847130",
      "description": "Automatic data processing machines",
      "duty_rate": 0.05,
      "confidence": 0.92,
      "reasoning": "Matches laptop computer specifications"
    }
  ]
}

Error Handling

Errors are returned with appropriate HTTP status codes and error messages:

400

Bad Request

Invalid parameters or malformed request body

401

Unauthorized

Missing or invalid API key

429

Rate Limited

Request quota exceeded. Check X-RateLimit-Reset header.

500

Server Error

Unexpected error. Retry with exponential backoff.

Code Examples

TypeScript/Node.js

import axios from 'axios';

const api = axios.create({
  baseURL: 'https://api.maxlinesez.com/v1',
  headers: {
    'Authorization': 'Bearer $MAXLINE_API_KEY'
  }
});

// Create a declaration
const response = await api.post('/declarations', {
  declaration_type: 'IM5',
  office_code: 'SC001',
  importer_name: 'John's Imports',
  goods: [{
    description: 'Laptops',
    hs_code: '847130',
    quantity: 50,
    unit: 'pcs',
    unit_price: 800
  }]
});

console.log('Declaration ID:', response.data.id);
console.log('Total duties:', response.data.total_duties_scr);

cURL

curl -X POST https://api.maxlinesez.com/v1/declarations \
  -H "Authorization: Bearer $MAXLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "declaration_type": "IM5",
    "office_code": "SC001",
    "importer_name": "Johns Imports",
    "goods": [{
      "description": "Laptops",
      "hs_code": "847130",
      "quantity": 50,
      "unit_price": 800
    }]
  }'

Ready to Integrate?

The Maxline API is available for Enterprise plan subscribers. Contact our sales team to discuss your integration requirements.

Contact Sales