Complete the Look API Guide

Usage Guide

The Complete the Look API takes a product id or other identifying information and returns a list of looks. It can be called directly from your servers, or called via the browser through Javascript. It returns complete display information to show products.

The latest state of the product can be passed into the API, to support realtime updates for rapidly changing product information like price, stock level and sale status. These parameters are required on PDP views for accurate information if your only integration points are API-only, but not required from background jobs or secondary integrations like email campaigns.

Full examples are available at the bottom.

API Endpoint

Endpoint: https://api.findmine.com/api/v2/complete-the-look

GET

For browser integrations, the GET method provides significantly faster responses. It avoids 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 posted data must be in the JSON format. Otherwise, all parameter names and semantics are the same. Response are plain JSON.

Required Parameters

  • application (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

    Don't know your application identifier? Please contact support@findmine.com if you're missing or don't know your application identifier.

  • product_* (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&product_color_id=C_34 Example: product_color_id=P_12_C_3 Example: product_id=P_12&product_color_id=C_34&product_pattern=stripes

    The specific parameters necessary for your site will be discussed and agreed upon at the start of integration with Findmine

If you do not know the correct parameters, or if a complication is discovered during integration please contact support@findmine.com with any questions or concerns.

Required for Product Detail Page (PDP) integrations

These parameters are required for integrations on PDP pages, to provide Findmine with a constant stream of updates to frequently changed data about products.

These parameters are optional for other integration points, for example other channels like email, chat bots or in-store experiences.t

  • product_price (number): The price of the product in USD, including any currently running sales.

    Example: product_price=29.99

  • product_in_stock (boolean): Is the product in stock and available for purchase? true if in stock and available for purchase. false if out of stock or otherwise unavailable for purchase.

    Example: product_in_stock=false

  • product_on_sale (boolean): Is the product currently on sale? true if an original price and discounted price are being shown, false if the product is still at the original price.

    Example: product_on_sale=true

Optional Customer Information

  • customer_session_id (string): The session id your website uses for analytics tracking of your customers. When provided to the API, this allows 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 (string): The logged-in user id of a customer, when available. This information can be used for targeted outfits based on prior purchase data, and enables more Findmine reporting capabilities.

    Example: customer_id=129428

  • customer_gender (string) "M" | "W" | "U": If the gender of the customer is known or inferable, then Findmine is able to generate gender-specific recomendations for unisex products.

    • "M": Return Men's looks.
    • "W": Return Women's looks.
    • "U": Customer gender unknown, Findmine will infer gender from product information where applicable.

    Example: customer_gender=W

Optional Response Control

  • response_language (string): Controls internationalization and localization of product fields in the response. Usually an ISO 639-1 code, but the specific values are custom tailored to your integration. Only available if translated product catalog feeds are provided.

    Example: response_language=es

  • response_callback (string, default: "onFindmineLooks"): The name of the JSONP callback function, when the API is called as a GET method.

Response Format

At a high level, the Complete the Look API returns a list of generated looks, each look contains a look_id and a list of items. Each item in the items list has common product display information: item_id, title, item_url, image_url and price. Your integration may include other data points as necessary, such as advanced sale data. Succesful requests will have a top level "result": "success" property.

If the API was unable to generate looks it will instead return a "result": "error" top level propery with a reason property that explains why the service was unable to generate a look. For example, this could be "excluded:category" if the passed in item has been excluded from Findmine results for business reasons. These strings change as the service evolves, and can include client-specific reason strings.

If the API request was fundamentally malformed, you'll see a list of the missing or mistyped arguments, indicating in plain text why we were unable to attempt to generate looks from the given request. Errors are most often a result of malformed or missing input parameters.

Reasons for Empty Looks in Response

More empty response reasons will be added over time, as the service continues to add new methods for generating looks. These strings are most useful for analytics purposes, or troubleshooting integration issues.

  • Could not find specified item: The product passed in the request was not found in our system.
  • product-excluded:{reason}: The product passed in is explicitly excluded from looks, generally due to business rules. The {reason} section will contain a specific reason for why the product was excluded, a client-integration specific string.
  • No matching looks found: The product was eligible for generated looks, but the service was unable to generate any.

Testing Implementation

If you want to test your implementation while our team is preparing the ingestion scripts for your product feed, you can leverage the fake_result flag. All you need to do is pass a fake_result=true on the GET params or fake_result: true on the POST json body. You will get a randomly generated set of matched items.

If you don't have an application id yet, you can pass any string in the parameter and you will get a set of random products. Otherwise, you will get a random set of products from your own store.

Here's a sample POST request with the fake_result flag:

{
  "application": "xxx",
  "product_price": 15.99,
  "product_in_stock": true,
  "product_on_sale": true,
  "fake_result": true
}

And here's one for a GET request: https://api.findmine.com/api/v2/complete-the-look?application=xxx&product_price=122.22&product_in_stock=true&product_on_sale=true&fake_result=true

You will get a response similar to this:

{
  "looks": [
    {
      "items": [
        {
          "image_url": "https://source.unsplash.com/600x600/?woman,jacket",
          "item_id": 651,
          "item_url": "https://example.com/product-jacket",
          "price": 26.18,
          "title": "Jacket"
        },
        {
          "image_url": "https://source.unsplash.com/600x600/?woman,shirt",
          "item_id": 475,
          "item_url": "https://example.com/product-shirt",
          "price": 31.82,
          "title": "Shirt"
        },
        {
          "image_url": "https://source.unsplash.com/600x600/?woman,pants",
          "item_id": 217,
          "item_url": "https://example.com/product-pants",
          "price": 91.62,
          "title": "Pants"
        }
      ],
      "look_id": 172
    }
  ],
  "response_uuid": "70ea705f-2621-402d-88ed-8ddb4e6fcb37",
  "result": "success"
}

You can also test error conditions, like omitting the application parameter to ensure proper error handling.

Example Requests and Responses

Successful Request: Looks Generated

Method: POST

Endpoint: https://api.findmine.com/api/v2/complete-the-look

Request Body:

{
  "application": "AB1212CDABCD",
  "product_id": "PID123",
  "product_price": 15.99,
  "product_in_stock": true,
  "product_on_sale": true
}

Response:

{
  "looks": [
    {
      "look_id": 123,
      "items": [
        {
          "item_id": 101,
          "title": "Jacket",
          "item_url": "https://example.com/product-jacket",
          "image_url": "https://example.com/product-jacket-small.jpeg",
          "price": 89.99
        },
        {
          "item_id": 134,
          "title": "Shirt",
          "item_url": "https://example.com/product-shirt",
          "image_url": "https://example.com/product-shirt-small.jpeg",
          "price": 24.99
        },
        {
          "item_id": 158,
          "title": "Pants",
          "item_url": "https://example.com/product-pants",
          "image_url": "https://example.com/product-pants-small.jpeg",
          "price": 49.99
        }
      ]
    }
  ],
  "response_uuid": "e6d1726f-3edb-4f5d-a9ee-66ef0000aab1",
  "result": "success"
}

Request:

GET https://api.findmine.com/api/v2/complete-the-look
        ?application=AB1212CDABCD
        &product_id=PID123p
        &roduct_price=29.99
        &product_in_stock=true
        &product_on_sale=true

Response:

{
  "looks": [
    {
      "look_id": 123,
      "items": [
        {
          "item_id": 101,
          "title": "Jacket",
          "item_url": "https://example.com/product-jacket",
          "image_url": "https://example.com/product-jacket-small.jpeg",
          "price": 89.99
        },
        {
          "item_id": 134,
          "title": "Shirt",
          "item_url": "https://example.com/product-shirt",
          "image_url": "https://example.com/product-shirt-small.jpeg",
          "price": 24.99
        },
        {
          "item_id": 158,
          "title": "Pants",
          "item_url": "https://example.com/product-pants",
          "image_url": "https://example.com/product-pants-small.jpeg",
          "price": 49.99
        }
      ]
    }
  ],
  "response_uuid": "e6d1726f-3edb-4f5d-a9ee-66ef0000aab1",
  "result": "success"
}

Successful Request: No Looks Generated

Request: GET https://api.findmine.com/api/v2/complete-the-look?product_id=PID123&application=AB1212CDABCD

Response:

{
  "result": "error",
  "looks": [],
  "empty_reason": "excluded-category",
  "response_uuid": "e6d1726f-3edb-4f5d-a9ee-66ef0000aab1"
}

Unsuccessful Request: Error

Request: GET https://api.findmine.com/api/v2/complete-the-look?product_id=PID123

{
    "response_uuid": "c1661798-0ddd-4813-8f2f-096c5f7bf127",
    "looks": [],
    "reason": "{'application': ['Missing data for required field.']}",
    "result": "error"
}
← JavaScript Module GuidePixel: Interaction Analytics Guide →