---
title: "Match suppliers from a freeform buyer brief + structured filters"
method: POST
path: "/suppliers/match"
---

# Match suppliers from a freeform buyer brief + structured filters

`POST /suppliers/match`

## Request

- Base URL: `https://source.reevol.com/api/v1`
- URL: `https://source.reevol.com/api/v1/suppliers/match`
- Auth: none declared

Combines Voyage semantic search (over supplier industry, HS codes, certifications, trade-fair history, and the EN summary) with structured filters. Returns ranked supplier cards each carrying a `matchExplanation` describing why it was included.

## Request body

- MatchRequest
  - `brief` string, required: Freeform description of what the buyer is sourcing.
  - `country` string: Single canonical country name.
  - `countries` string[]: Multi-country allow-list.
  - `excludeCountries` string[]
  - `hsCodes` string[]
  - `industry` string
  - `certifications` string[]
  - `employeeRange` string[]
  - `foundedAfter` integer
  - `foundedBefore` integer
  - `businessType` 'manufacturer' | 'trading_company' | 'any'
  - `exportMarkets` string[]
  - `limit` integer
  - `lang` string

## Response `200`

Ranked supplier cards

- MatchResponse
  - `results` MatchedSupplier[]
    - `id` string
    - `slug` string
    - `legalNameEn` string
    - `legalNameZh` string, nullable
    - `hqCity` string, nullable
    - `hqCountry` string
    - `industryPrimary` string
    - `hsCodes` string[]
    - `visibilityScore` number
    - `semanticScore` number: Cosine similarity, 0..1.
    - `finalScore` number: 0.7 * semantic + 0.3 * normalized_visibility.
    - `matchExplanation` string: Plain-English reason the supplier surfaced.
    - `url` string, uri
  - `debug` object
    - `semanticHits` integer
    - `filterHits` integer
    - `embeddingLatencyMs` integer
    - `searchLatencyMs` integer
    - `totalLatencyMs` integer

## Other responses

- `400`: Brief missing or too short

---

[API](https://skmtc.dev/reevol/apis/reevol-source-rest-api.md) · [All operations](https://skmtc.dev/reevol/apis/reevol-source-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/reevol/apis/reevol-source-rest-api/revisions/a7a6db37cc5a?raw)