# Virtual Sizer ## Virtual Sizer API The Virtual Sizer is a single stateless GET call that returns customer inputs, garment size recommendations, and fit feedback, in one response. Optimized for AI Agents, the Virtual Sizer API is up to 10x faster than MCP, and requires no session management, no streaming, and no orchestration layer. See [Common API Topics](/common-api-topics.md) for global patterns across all endpoints. ### API Integration: eCommerce Site - Direct Integration ### Virtual Sizer API `GET` `https://api.boldmetrics.io/virtualsizer/get?` Please note the `client_id` and `user_key` requirements, along with the minimum required inputs. **Path Parameters** | Name | Type | Description | | -------------------------------------- | ------ | ------------------ | | Host\* | String | api.boldmetrics.io | **Query Parameters** | Name | Type | Description | | ---------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | client\_id\* | String | Your account ID provided by Bold Metrics | | user\_key\* | String | Your secret key provided by Bold Metrics | | desired\_brand\* | String | Brand of garments to return | | desired\_garment\_type\* | String | Type/category of garments to return | | weight\* | Integer | Weight in pounds | | height\* | Integer | Height in inches | | waist\_circum\_preferred\* | Integer | **\[required for male garments]** Waist circumference at preferred in inches | | bra\_size\* | String | **\[required for female garments]** Bra size of client, such as 30B | | age\* | Integer | Age in years | | anon\_id\* | String | Your identifier for the customer being fitted | | chest\_circum | Float | Chest circumference in inches | | jean\_inseam | Float | Inseam of trousers in inches | | shoe\_size\_us | Float | Shoe size (American sizes) | | jacket\_size | String | Jacket size; e.g. 38R | | sleeve | Float | Length of sleeve based on sleeve\_type in inches | | sleeve\_type | String | Type of sleeve measurement for given sleeve input. Choices include `ARS` : the `acromion-radial-styloid` length or nape-to-wrist for values larger than 29 inches, or `SO` : `sleeve outseam` length. | | fm\_shoulder | Float | Shoulder width in inches | | hip\_circum | Float | Hip circumference in inches | | overarm | Float | Shoulder circumference in inches | | sleeve\_inseam | Float | Inseam of sleeve in inches | | thigh | Float | Thigh circumference in inches | | waist\_circum\_stomach | Float | Thigh circumference in inches | | waist\_height\_preferred | Float | Waist height in preferred inches | | neck\_circum\_base | Float | Neck circumference at base of neck, usual collar size in inches | | locale | String | Two-letter country code for user locale, modifies **bra\_size** | | product\_id\* | String | The parent/style identifier for the garment | | model\_id | String | An identifier for a specific model. Used for testing & in specific production instances. This will not be used unless you are notified by Bold Metrics. | > **For agents collecting inputs conversationally:** Start with `height`, `weight`, `age`, and either `waist_circum_preferred` (men) or `bra_size` (women). These 4–5 fields are the minimum viable call. Pass `product_id` and `desired_garment_type` directly from cart or PDP context — no need to ask the customer. Fields like `jean_inseam`, `chest_circum`, and `jacket_size` are worth asking for when confidence is low (see Outlier Detection). `anon_id` should be set from your session token, not collected from the user. ## API Integration: AI Agent #### Minimum Viable Call Pass `height`, `weight`, `age`, `anon_id`, `desired_brand`, `desired_garment_type`, `product_id`, and either `waist_circum_preferred` or `bra_size`. The API returns actionable size recommendations from these inputs alone. #### Reading the Response for Agent Decisions Check `good_matches` first. If the array is non-empty, surface the first result's `garment.size` and `fit_description`. If `good_matches` is empty, the `message` field will explain why (no matching sizes). Check `outlier` before presenting results. If `outlier: true`, inspect `outlier_messages.specifics` to decide whether to ask the customer to re-enter a specific measurement before re-calling. #### Using fit\_score as a Confidence Signal `fit_score` values near 0 mean the garment fits the customer's predicted measurements precisely. Use this to decide whether to suggest the first match or offer the customer a choice: | fit\_score range | Agent behavior | | ---------------- | ------------------------------------------------------------- | | Within ±0.2 | Present as the recommended size with confidence | | ±0.2 to ±0.5 | Present with "should fit well, slightly snug/loose" | | Beyond ±0.5 | Surface `fit_description` to the customer and let them decide | #### Passing Product Context `product_id` activates garment-specific sizing using size chart or tech pack data. Always pass it when the customer has a specific item in mind. If the customer is browsing generally, `desired_garment_type` alone returns a general recommendation. **Concurrent Calls** The API is stateless. If an agent is helping multiple customers simultaneously or comparing sizes across multiple products, fan out parallel requests using distinct `anon_id` values per customer. **Headers** | Name | Type | Description | | ---------------------------------------- | ------ | ---------------------------------------------------- | | Accept\* | String | the response content type depends on *Accept* header | {% tabs %} {% tab title="200: OK See code snippet" %} ```javascript HTTP/1.1 200 OK Vary: Accept Content-Type: text/javascript { "code": 200, "customer": { "desired_brand": "farah", "desired_garment_type": "t_shirt", "height": 72.00, "waist_circum_preferred": 30.00, "weight": 150.00 }, "message": { "overall": "OK" }, "size_recommendations": { "good_matches": [ { "fit_description": { "chest": "just right", "garment": "just right" }, "fit_score": { "chest": 0.01, "garment": 0.01 }, "garment": { "brand": "farah", "category": "shirt", "fit": "", "size": "s", "style": "", "type": "t_shirt" } }, ... ], "poor_matches": [ { "fit_description": { "chest": "too loose", "garment": "too loose" }, "fit_score": { "chest": -1.98, "garment": -1.98 }, "garment": { "brand": "farah", "category": "shirt", "fit": "", "size": "l", "style": "", "type": "t_shirt" } }, ... ] }, "outlier": false, "outlier_messages": { "overall": "All good", "specifics": [] }, } ``` {% endtab %} {% tab title="400: Bad Request Bad Request" %} ```javascript { // Response } ``` {% endtab %} {% tab title="401: Unauthorized Unauthorized `client_id` and/or `user_key`" %} ```javascript { // Response } ``` {% endtab %} {% tab title="404: Not Found Not Found" %} ```javascript { // Response } ``` {% endtab %} {% tab title="500: Internal Server Error Internal Server Error" %} ```javascript { // Response } ``` {% endtab %} {% tab title="429: Too Many Requests Too Many Requests" %} {% endtab %} {% endtabs %} ### **Example response** ``` HTTP/1.1 200 OK Vary: Accept Content-Type: text/javascript { "code": 200, "customer": { "desired_brand": "farah", "desired_garment_type": "t_shirt", "height": 72.00, "waist_circum_preferred": 30.00, "weight": 150.00 }, "message": { "overall": "OK" }, "size_recommendations": { "good_matches": [ { "fit_description": { "chest": "just right", "garment": "just right" }, "fit_score": { "chest": 0.01, "garment": 0.01 }, "garment": { "brand": "farah", "category": "shirt", "fit": "", "size": "s", "style": "", "type": "t_shirt" } }, ... ], }, "outlier": false, "outlier_messages": { "overall": "All good", "specifics": [] }, } ``` ### **product\_id and desired\_garment\_type** Your size recommendation will be based on the following two fields: * **desired\_garment\_type***: The product category* * **product\_id:** *The product identifier or SKU* Your account manager will work with you to insure your team is using the correct `desired_garment_type`'s. ### Response Object The size recommendations returned by the Virtual Sizer gives us a few values in the response: * *size\_recommendations*: a list of `good_matches` containing garment and fit score objects outlined below * *code*: the return status code * *message*: any details of result that may need attention, e.g. the number of body inputs is low. * *outlier\_status*: whether the input triggered an outlier warning. * *outlier\_messages*: the specific fields causing an outlier warning to trigger. See [Common API Topics](/common-api-topics.md) for global patterns across all endpoints. #### **Garment Response Object** The garment object contains the *fit* and *size* of the garment. Use these attributes to match to garments carried by your store. Each field is generated from information specific to your customer's inputs. #### **Fit Score and Description Response Objects** The fit score and fit descriptions provide information on how the garment fits on the customer based on their measurement predictions and the corresponding garment dimensions. Garment dimensions are provided to Bold Metrics either via size charts or tech pack data. Occasionally, additional data goes into determining the fit of the garment. Fit model or body block data help capture the intended fit by design. The fit description scores are mapped on a dimensionless scale centered at 0 for the best fit. Negative values represent a snug or shorter garment dimension and positive values represent a loose or longer garment dimension. The fit description score is on a relative scale for a particular garment. Categorical responses for fit\_description are: * just right * slightly snug * slightly loose * snug * loose * very snug * very loose ``` very snug snug slightly snug just right slightly loose loose very loose ----|---------|------------|--------------|----------------|------------|----------|----- <- negative scale -> 0 <- positive scale -> ``` #### Outlier Detection See [Outlier Detection.](/common-api-topics.md#outlier-detection) In addition to Outlier Detection for catching hard to discover errors in inputs, the API will notify for several other edge cases. If no sizes for a garment are found, the *good\_matches* array will be empty and the *message* field will indicate that no sizes fit well\_.\_ ### How to Use vSizer for eCommerce Sites If you're looking to add Virtual Sizer (vSizer) to your eCommerce page, this is the recommended way to integrate the API with your platform. This can be accomplished in three easy steps: 1. Setup the API 2. Add the Analytics Script 3. Add the Purchase Script #### Setup the API Follow the [documentation above](#virtual-sizer-api) to implement the API. Please note you'll receive the `client_id`, `user_key`, `desired_brand` and `desired_garment_type` from your Bold Metrics Representative. {% hint style="info" %} There's an additional parameter that is required and is important with this integration: `anon_id`. This is a user identifier that should not be PII (Personal Identifiable Information, e.g. email, phone, name, etc). The Analytics script in the next section will outline a potential solution regarding `anon_id.` {% endhint %} #### Add The Analytics Script To add analytics to your PDP, please follow the [documentation here](/analytics-script.md). This will tag several elements on your page, and collect usage information to help Bold Metrics identify usage and conversion metrics. Additionally, the analytics script will also add a cookie value and generate a user ID on your behalf. The cookie name is `bm`. **Different User ID Patterns** The recommended pattern is to use the user ID cookie value generated by the analytics script for your `anon_id` parameter value when calling the API. This simplifies tracking, and avoids issues where you may have multiple user IDs. If you have other user IDs, it's recommended to collect the Bold Metrics user ID to make potential dataset matches. This allows for joins between the Bold Metrics data and any user profile data you may collect on your end. #### Add The Purchase Script To implement the Purchase Script, please follow the [documentation here.](/purchase-script.md) Note that the purchase script will collect the user ID from the cookie set by the Analytics script, which allows Bold Metrics to match analytics, recommendations, and purchases. It is recommended to collect the user ID cookie value with your purchase data, but is not a requirement. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.boldmetrics.io/virtual-sizer.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.