Buyers API

Discover potential buyers worldwide and access their import history and purchasing patterns.

POST/api/v1/buyers/discover

Find potential buyers based on product categories, markets, and import history.

Request Body

{
  "hsCode": "8517",
  "markets": ["US", "EU", "JP"],
  "minImportValue": 100000,
  "dateFrom": "2024-01-01",
  "limit": 50
}

Response

{
  "success": true,
  "data": {
    "buyers": [
      {
        "id": "buyer_123456",
        "name": "Electronics Import Corp",
        "country": "US",
        "city": "Los Angeles",
        "importHistory": {
          "totalImports": 45,
          "totalValue": 5600000,
          "averageValue": 124444,
          "lastImport": "2024-11-15"
        },
        "products": [
          {
            "hsCode": "8517",
            "description": "Telephones",
            "frequency": 32
          }
        ],
        "contactInfo": {
          "website": "example.com",
          "verified": true
        }
      }
    ],
    "total": 234,
    "limit": 50
  }
}

GET/api/v1/buyers/:id

Get detailed information about a specific buyer including complete import history.

Path Parameters

Parameter	Type	Description
id	string	Unique buyer identifier

Response

{
  "success": true,
  "data": {
    "id": "buyer_123456",
    "name": "Electronics Import Corp",
    "country": "US",
    "city": "Los Angeles",
    "address": "123 Import Street",
    "contactInfo": {
      "email": "contact@example.com",
      "phone": "+1-555-0123",
      "website": "example.com",
      "verified": true
    },
    "importHistory": {
      "totalShipments": 45,
      "totalValue": 5600000,
      "firstImport": "2023-03-15",
      "lastImport": "2024-11-15",
      "averageShipmentValue": 124444
    },
    "topProducts": [
      {
        "hsCode": "8517",
        "description": "Telephones",
        "shipments": 32,
        "value": 4200000
      }
    ],
    "topSuppliers": [
      {
        "name": "Tech Exports Ltd",
        "country": "CN",
        "shipments": 18
      }
    ]
  }
}

GET/api/v1/buyers/search

Search for buyers by name or company identifier.

Query Parameters

Parameter	Type	Description
q	string	Search query (company name)
country	string	Filter by country (optional)

Response

{
  "success": true,
  "data": {
    "results": [
      {
        "id": "buyer_123456",
        "name": "Electronics Import Corp",
        "country": "US",
        "city": "Los Angeles",
        "verified": true
      }
    ],
    "total": 1
  }
}