Virtual Sizer

Virtual Sizer API

The Virtual Sizer is a single stateless GET call that returns size recommendations plus tailor-accurate body measurements 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 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

200: OK See code snippet

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
},
"dimensions": {
  "acromion_height": 58.57,
  "acromion_radial_len": 13.40,
  "acromion_radial_stylion_len": 24.19,
  ...
},
"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": []
},
}

400: Bad Request Bad Request

401: Unauthorized Unauthorized `client_id` and/or `user_key`

404: Not Found Not Found

500: Internal Server Error Internal Server Error

429: Too Many Requests Too Many Requests

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
},
"dimensions": {
  "acromion_height": 58.57,
  "acromion_radial_len": 13.40,
  "acromion_radial_stylion_len": 24.19,
  ...
},
"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.

Body Measurements

See Body Measurements.

Response Object

The size recommendations returned by the Virtual Sizer gives us a few values in the response:

• dimensions: a list of body measurements

• 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 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.

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 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.

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.

Add The Analytics Script

To add analytics to your PDP, please follow the documentation here. 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. 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.