Developers

Sourcing API & MCP server

Find manufacturers and their products from your own tools — by what a part is, by HS code, or a whole bill of materials at once. Searches cover published supplier catalogues and the US customs records of about 100,000 manufacturers. The same data is available to AI assistants through an MCP server.

Quick start

Create a free account and a key at /sourcing-api. It starts with mati_ and is shown once.
Search:

export MATI_KEY=mati_…
curl -H "Authorization: Bearer $MATI_KEY" "https://www.matilogistics.com/api/v1/products?q=pvc+ball+valve"

Base URL https://www.matilogistics.com/api/v1. JSON in and out. Every response carries X-Request-Id, X-Quota-Limit and X-Quota-Remaining.

Keys

Send the key as Authorization: Bearer mati_…, or as X-Api-Key: mati_… where a tool can set a header but not an auth scheme. Keys belong to your account — up to 10 at once, each revocable — and usage is counted per account, not per key. We store only a hash of each key; a lost key cannot be shown again, only replaced. Track and Trace keys (tnt_…) are a different service and documented separately.

Pricing & limits

Plan	Price	Units a month
Free	$0, any account	1,000
Sourcing API Pro	$49 / month	25,000

One unit per request, and one per line for /bom/match; /me is free. Units reset on the 1st of each month (UTC). Separately, each account may make 60 requests a minute and 600 BOM requests an hour. For more, write to api@matilogistics.com. The Sourcing API is billed on its own subscription, separate from Track and Trace and the sourcing assistant plan.

Endpoints

GET/products

Search every published supplier catalogue by what the product is. Every word must match first; if nothing does, any word, ranked by how many matched and where — `match` says which answered.

Parameter	In	Description
q	query	Required. Plain words, e.g. `stainless steel ball valve`.
country	query	Supplier countries, comma-separated: names or ISO codes, any case (`China,VN`). Unknown values match nothing.
supplier	query	Only this supplier's products (a supplier slug).
limit	query	1–50, default 20.
cursor	query	`next_cursor` from the previous page.

curl -H "Authorization: Bearer $MATI_KEY" \
  "https://www.matilogistics.com/api/v1/products?q=pvc+ball+valve&country=CN"

{
  "data": [{
    "id": "…", "slug": "pvc-ball-valve-1-inch", "name": "PVC Ball Valve 1 inch",
    "summary": "PVC ball valve for water lines", "price": null,
    "evidence": { "photos": 3, "spec_tables": 1 },
    "supplier": { "slug": "ningbo-valve-co", "name": "Ningbo Valve Co", "country": "China",
                  "url": "https://www.matilogistics.com/supplier/ningbo-valve-co" },
    "match": "all_terms",
    "url": "https://www.matilogistics.com/supplier/ningbo-valve-co/products/pvc-ball-valve-1-inch",
    "inquiry_url": "https://www.matilogistics.com/inquiry?supplier=ningbo-valve-co&product=pvc-ball-valve-1-inch"
  }],
  "match": "all_terms",
  "next_cursor": null,
  "search_url": "https://www.matilogistics.com/supplier/search?q=pvc+ball+valve"
}

GET/suppliers

Manufacturers ranked by their US customs record — including the many with no online catalogue. Shipments filed under the HS headings you name count most, then how well their shipped goods match your words.

Parameter	In	Description
q	query	What they make. Needed unless `hs` is given.
hs	query	HS codes, comma-separated, matched on the 4-digit heading: `7318,8481.80`.
country	query	Supplier countries, comma-separated: names or ISO codes, any case (`China,VN`). Unknown values match nothing.
limit	query	1–50, default 20. Ranked, not paginated: past 50, narrow the query.

curl -H "Authorization: Bearer $MATI_KEY" "https://www.matilogistics.com/api/v1/suppliers?hs=7318&country=Vietnam"

{
  "data": [{
    "slug": "vn-bolt-works", "name": "VN Bolt Works", "country": "Vietnam",
    "customs": { "shipments": 40, "shipments_under_hs": 38, "us_buyers": 3, "top_buyer": "GRAINGER",
                 "last_shipment": "2026-08-14", "products": ["carbon steel bolts"], "hs_codes": ["731815 Screws and bolts"] },
    "catalogue_products": 0,
    "url": "https://www.matilogistics.com/supplier/vn-bolt-works",
    "rfq_url": "https://www.matilogistics.com/rfq?supplier=vn-bolt-works"
  }],
  "matched": 1,
  "search_url": null
}

GET/suppliers/{slug}

One supplier: country, industry, website and address, customs history (shipments, US buyers, HS codes), the researched company profile with key customers and key people, catalogue summary, certifications, and which contact channels are on file (counts only).

Parameter	In	Description
slug	path	From any search result.

curl -H "Authorization: Bearer $MATI_KEY" "https://www.matilogistics.com/api/v1/suppliers/ningbo-valve-co"

GET/suppliers/{slug}/products

A supplier's published catalogue, in catalogue order.

Parameter	In	Description
slug	path	The supplier.
limit	query	1–100, default 50.
cursor	query	`next_cursor` from the previous page.

curl -H "Authorization: Bearer $MATI_KEY" "https://www.matilogistics.com/api/v1/suppliers/ningbo-valve-co/products"

GET/suppliers/{slug}/products/{product}

One product in full: the supplier's description, every characteristic, standards, specification tables, part number, MOQ and lead time.

Parameter	In	Description
slug	path	The supplier.
product	path	The product slug.

curl -H "Authorization: Bearer $MATI_KEY" "https://www.matilogistics.com/api/v1/suppliers/ningbo-valve-co/products/pvc-ball-valve-1-inch"

POST/bom/match

Suppliers for each line of a bill of materials, up to 25 lines per request. For each line: catalogue products matched by part number, then by text; and suppliers whose customs record fits but who list no matching product. One unit per line.

Parameter	In	Description
lines[]	body	Each needs `description` or `part_number`; optional `ref` (echoed), `material`, `hs_code`, `quantity` (a number or `"1,500"`), `manufacturer` (echoed).
countries	body	Names or ISO codes.
per_line	body	Results per list per line, 1–5, default 3.

curl -X POST -H "Authorization: Bearer $MATI_KEY" -H "Content-Type: application/json" \
  -d '{"lines":[
        {"ref":"10","description":"Hex bolt M6x20 stainless A2","hs_code":"7318.15","quantity":500},
        {"ref":"20","part_number":"NBV-100"}
      ]}' \
  https://www.matilogistics.com/api/v1/bom/match

{
  "data": [
    { "ref": "10", "description": "Hex bolt M6x20 stainless A2", "quantity": 500,
      "products":  [{ "name": "Hex Bolt DIN 933 Stainless A2", "match": "any_terms", "supplier": { … }, "url": "…" }],
      "suppliers": [{ "name": "VN Bolt Works", "customs": { "shipments_under_hs": 38, … }, "url": "…", "rfq_url": "…" }],
      "search_url": "https://www.matilogistics.com/supplier/search?q=Hex+bolt+M6x20+stainless+A2" },
    { "ref": "20", "part_number": "NBV-100",
      "products":  [{ "name": "PVC Ball Valve 1 inch", "match": "part_number", … }],
      "suppliers": [], "search_url": null }
  ]
}

GET/me

Whose key this is, the plan, and what is left of the month. Free — use it for connection tests.

curl -H "Authorization: Bearer $MATI_KEY" "https://www.matilogistics.com/api/v1/me"

{ "email": "you@company.com", "name": "…", "plan": "free",
  "quota": { "limit": 1000, "used": 42, "remaining": 958, "resets_at": "2026-10-01T00:00:00.000Z" } }

MCP server

The same searches as tools for AI assistants, at https://www.matilogistics.com/api/mcp (Streamable HTTP). It works without a key at the level of our public pages; add a key for spec tables, certificates, website and address, and BOM matching — counted against your allowance like any other call.

Tool	What it does
search_products	Search manufacturers' published product catalogues by description, e.g. 'stainless steel hex bolt' or 'PVC ball valve'. Returns products with their supplier, a summary, price when published, and links.
search_suppliers	Find manufacturers from their US customs import records — including the many with no online catalogue. Rank is driven by shipments filed under the HS codes given, then by how well their shipped products match the query.
get_supplier	One supplier's record by slug: country, industry, customs history (shipments, US buyers, HS codes), researched company profile with key customers, catalogue summary and certifications.
get_product	One product's full record: description, characteristics, standards, images; with an account also spec tables, MOQ and lead time.
match_bom	Suppliers for each line of a bill of materials (up to 25 lines): matching catalogue products and factories whose customs record fits. Requires a Mati Logistics API key; one unit per line.

Claude Code

claude mcp add --transport http mati https://www.matilogistics.com/api/mcp \
  --header "X-Api-Key: $MATI_KEY"      # optional

Cursor, Claude Desktop and other clients (JSON config)

{
  "mcpServers": {
    "mati": {
      "url": "https://www.matilogistics.com/api/mcp",
      "headers": { "X-Api-Key": "mati_…" }
    }
  }
}

Leave out headers to use it without a key. In ChatGPT and Claude on the web, add it as a custom connector with the same URL.

Errors

Errors share one shape — branch on error.code, not the message:

{ "error": { "code": "quota_exceeded", "message": "…", "request_id": "3f9c…" }, "detail": "…" }

Code	Status	Meaning
bad_request	400	A parameter is missing or malformed; the message names it.
unauthenticated	401	No key, a key for a different API, or a revoked key.
quota_exceeded	402	This month's units are used. X-Quota-Reset says when they return.
forbidden	403	The key's account cannot use the API.
not_found	404	No such supplier or published product.
rate_limited	429	Too many requests in the window; wait Retry-After seconds.
internal_error	500	Our fault. Quote the request_id if you write to us.

Attribution & data

Every supplier and product in a response carries a urlto its page on matilogistics.com. Wherever you show our data — in a BOM, a spreadsheet, an assistant’s answer — show that link with it.

These are the short version of the Sourcing API terms, which also cover caching, limits and what the data can and cannot tell you. Supplier contact details are not available through the API. rfq_url and inquiry_urlsend a buyer to request a quote on the site, and contacts can be unlocked on each supplier’s page. Customs data comes from US ocean import records; see our data methodology. What we log about API calls and for how long is in the privacy policy.