The Matching Sets API takes a product ID or other identifying information and returns a list of matching sets. Each matching set is a curated group of coordinated products — typically sharing the same fabric/material and color — organized as pairings specific to each client. The API can be called directly from your servers or via the browser through JavaScript. It returns complete display information to show products.
Unlike the Complete the Look API, which returns full multi-category outfit recommendations, the Matching Sets API focuses on coordinated product pairings within the same material or collection, helping customers find the matching piece to what they're already viewing.
The API handles stock filtering server-side using live inventory data, so parameters like product_in_stock and product_on_sale are not required or supported.
You will find comprehensive syntactical examples at the bottom of this article.
<aside> 💡
If you are implementing Matching Sets using our JavaScript widget, you do not need to implement this API; the widget takes care of all the work.
</aside>
<https://api.findmine.com/api/v3/matching-sets>
Get
In JavaScript browser integrations, the GET method provides significantly faster responses by avoiding slow browser cross-origin security checking requests. All API parameters are passed as HTTP GET arguments.
Post
For other integrations, the POST method may be preferable. Posts must be content-type: application/json and the passed data must be in JSON format. Otherwise, all parameter names and semantics remain the same. The responses are plain JSON.
| Parameter | Required | Type | Description |
|---|---|---|---|
| application | Yes | String | The application parameter is a unique identifier provided to you at the start of integration. This identifier is not an authorization secret, it is safe and required to embed in your public HTML. Example: application=AB1212CDABCD |
| product_* | Yes | String(s) | Product identifying information. One or more strings that uniquely identify each visually distinct product, most often a product identifier and a color identifier. The exact parameter names will be configured for your integration during onboarding, and reflect the specific product variation structure of your catalog. These parameters must match identifiers in the product catalog feed exactly. Example: product_id=P-12 Example: product_id=P-12&product_color_id=C-34 |
| return_pdp_item | No | Boolean | When true, the response includes the PDP item's data in a separate pdp_item field. Example: return_pdp_item=true |
| max_matching_sets | No | Integer | Number of matching sets to return. Must be between 1 and 10. Defaults to 1. Example: max_matching_sets=3 |
| Parameter | Required | Type | Description |
|---|---|---|---|
| customer_session_id | Yes | String | The session ID your website uses for analytics tracking of your customers. Providing this value to the API enables our analytics system to accurately match your internal analytics systems, and reports generated by FindMine will more closely track with internal numbers. Example: customer_session_id=FD041FE1986C4C47FEE1 |
| customer_id | No* | String | The logged-in user id of a customer, when available. This information can be used for targeted recommendations based on prior purchase data, and enables more FindMine reporting capabilities. This should be a durable, cross-device identifier for a customer such as an external ID from your ecommerce platform that represents a logged in user. Do not send PII in this string. * - While this identifier is not required, this parameter is valuable for analytics and learning algorithms. Example: customer_id=129428 |
| region | No* | String | Two letter ISO Country code. * - required for multi-region implementations. Example: region=us |
| language | No* | String | Two letter ISO language code. * - required for multi-language implementations. Example: language=en |
<aside> 💡
region and language must be provided together. Passing one without the other will return a validation error.
</aside>
At a high level, the Matching Sets API returns a list of matching_sets, each matching set contains a uid and a list of items. Each item in the items list has common product display information: item_id, title, item_url, image_url, price, category, and uni. Your integration may include other data points as necessary, such as advanced details data. Successful requests will have a top level "result": "success" property.
Items within each matching set are ordered in a sequence specific to your implementation. Typically, the sequence begins with the opposite category of the PDP item. For example, if the PDP item is a Bottom, the first item returned will be a Top.