See a product on the shopper's body
const url = 'https://api.tryyoursize.com/v1/tryon?view=full&start=true';const options = { method: 'POST', headers: { 'TYS-Publishable-Key': '<TYS-Publishable-Key>', 'Content-Type': 'application/json' }, body: '{"product":"example","basics":{"sex":"female","age_years":1,"height_mm":1,"weight_kg":1},"measurements":[{"code":"neck_girth","value_mm":1,"source":"tape_self","sd_mm":1}],"feet":{"source":"paper","length_mm":1,"width_mm":1,"girth_mm":1,"reference":{"brand":"example","system":"eu","size":"example"}},"fit":{"preference":"tight","preference_tops":"tight","preference_bottoms":"tight","usual_sizes":[{"brand":"example","line":"tops","sex":"female","size":"example"}]},"body_state":[1]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url 'https://api.tryyoursize.com/v1/tryon?view=full&start=true' \ --header 'Content-Type: application/json' \ --header 'TYS-Publishable-Key: <TYS-Publishable-Key>' \ --data '{ "product": "example", "basics": { "sex": "female", "age_years": 1, "height_mm": 1, "weight_kg": 1 }, "measurements": [ { "code": "neck_girth", "value_mm": 1, "source": "tape_self", "sd_mm": 1 } ], "feet": { "source": "paper", "length_mm": 1, "width_mm": 1, "girth_mm": 1, "reference": { "brand": "example", "system": "eu", "size": "example" } }, "fit": { "preference": "tight", "preference_tops": "tight", "preference_bottoms": "tight", "usual_sizes": [ { "brand": "example", "line": "tops", "sex": "female", "size": "example" } ] }, "body_state": [ 1 ] }'Key: publishable (pk_test_… / pk_live_…), from an origin registered for the key.
Shows every size of the product’s published garment on the body and recommends a size (from a few seconds to about 2 minutes). A body already shown with this garment version answers 200 at once; otherwise 202 and a job to poll. Every answer carries a new viewer_token, the only way (with the shopper’s session) to read the job. With a shopper session (Authorization: Bearer tys_sess_…) the try-on is linked to the shopper and, in live mode, delivering a done result records the store connection and the size the store receives.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”full (default) answers with the whole result (meshes for every size, MBs). summary leaves result out and answers summary instead (the recommended size and the sizes that can be worn, a few bytes): for the size-guide button and the store’s recommended-size event, which never need the meshes.
false answers only with an existing result and never queues a simulation: a done or running try-on of this body, or 404 (“not simulated yet”). With view=summary, a miss may answer 200 with a size estimate instead (status: done, empty id, summary.method: estimate). Page views (the size-guide and inline elements) use it; a full simulation starts only on an explicit shopper action (“See it on you”).
Request Bodyrequired
Section titled “Request Bodyrequired”The product and the shopper’s body as on screen: the same body as /v1/bodies/preview, with the preview’s body_state (required for garments; opaque). For a footwear product, feet is what counts (without it the answer is 404: no shoe size without feet) and body_state may be omitted.
object
The product’s SKU / style ID in the store (what the shop passes to the element).
object
object
Body measurement from set v1.
Measured value in millimetres.
How the value was obtained. bra_size: derived from the shopper’s bra size (underbust and bust only).
The value’s uncertainty (one standard deviation, mm), when known: set for values from a bra size; a tape measured twice may send its own. Omitted: the default for its source.
The shopper’s feet: the larger foot, in millimetres. paper: traced at home (heel against a wall, both feet, measured twice). reference: implied by a size the shopper wears (reference; length_mm is then derived). estimated: from height and sex (less precise; length_mm is derived from the request’s basics).
object
Heel to the longest toe. Required for paper.
Optional width at the widest point (the ball).
Optional ball (instep) girth.
object
A shoe size system: eu (Paris points), uk, us_men, us_women, or mondopoint (foot length in mm).
The shopper’s fit preference and usual sizes (optional). Without it, a signed-in shopper’s saved profile is used; a guest gets sizes for a regular fit.
object
A size the shopper usually wears in another brand (“M in Uniqlo tops”, “30 in Levi’s bottoms”). declared: typed by the shopper. kept_purchase: filled in from a purchase the shopper kept in a store that uses TryYourSize (read-only for the shopper apart from deleting it).
object
A brand key from GET /v1/usual-size-brands.
The brand’s women’s (female) or men’s (male) line. Defaults to the shopper’s own.
The size label as the brand writes it (one of the brand’s sizes for this line).
The body_state of the body preview on screen.
Responses
Section titled “Responses”Done (an existing result)
A try-on: every size of the product’s published garment shown on the body. Poll GET /v1/tryon/{tryon_id} every ~2 s until status is done or failed. A repeated try-on of the same garment version and body answers at once.
object
The try-on’s id (uuid). Empty only for a size estimate (POST ?start=false&view=summary answered with no try-on of this body); there is nothing to poll.
Only in the answer to POST /v1/tryon: the window’s proof that it may read this try-on. Send it as Authorization: Bearer tys_view_… to GET /v1/tryon/{tryon_id}. Stored hashed; never sent again.
object
Present when status is done, and while it runs: the sizes computed so far, each with method (simulated) and state (preview: shown early, may still change; settled; refining: still being computed, no mesh yet; simulated). The try-on result for the window: body mesh and body_state (no basics, no tape measurements), garment with its fabric and estimated POMs, recommended size and per-size meshes, pressure kPa, ease mm and zones. Binary arrays are base64 little-endian; per-vertex values are rounded to display precision.
object
Present when status is done and the request asked for view=summary: what a store may receive (sizes only, never measurements). Size labels are the garment’s (Studio) sizes; map them with shop_sizes from GET /v1/products/{product}/tryon.
object
The recommended size; absent when no size can be worn.
Sizes that can be worn on this body (judged on this body), smallest to largest.
Footwear only - the two sizes the foot sits between (see footwear.between).
How the size was determined (measured: a footwear size from the shopper’s measured feet): estimate (a size estimate, no try-on of this body yet) or simulated (from the try-on of this body). A coarse informational label: do not build logic on its values.
The size answer with its method. On the first answer of a try-on it may already be there (method: estimate) while the 3D view is computed; once done it is the try-on’s own size. An estimate is final (ready or none) only when it is certain for this body; otherwise the status is computing, no size is named, and the try-on’s 3D view gives it.
object
Same as summary.method. A coarse informational label; do not build logic on its values.
Two adjacent sizes when they are genuinely close (smaller first), or, for footwear, the two sizes the foot sits between.
Calibrated probability (0-1) that the shopper keeps the recommended size (either size of between). Present on some estimates.
Facts for the explanation, per zone - the body girth the answer rests on (measured or estimated, with its uncertainty) and the room (garment girth minus body girth, mm; negative is smaller than the body) in the recommended size and its neighbours.
object
object
The numbers behind a footwear size, per size of the chart. Lengths in millimetres, rounded to 0.1 mm. Facts only: the room in front of the toes and how the width compares, never a verdict.
object
The typical measuring uncertainty of the foot length.
Two sizes when the foot sits at their boundary within its measuring uncertainty (the recommended size is the longer one); for an estimate, the range of sizes it may be. Absent when the size is clear.
The recommended width fitting, when the chart has fittings.
True when the brand’s chart gives foot lengths (then chart_foot_mm is the foot length each size is made for) rather than the shoe’s inside length.
object
Room in front of the longest toe (negative - shorter than the foot).
The size’s width minus the foot’s (negative - narrower than the foot).
The toe room is within the shoe type’s usual range.
Present when status is failed.
object
INVALID_BODY, UNSUPPORTED_CATEGORY, MISSING_POM, INVALID_POM, INVALID_FABRIC, NO_SIZES, UNAVAILABLE or ENGINE_ERROR.
Example
{ "status": "queued", "summary": { "method": "estimate" }, "recommendation": { "method": "estimate", "status": "ready", "facts": [ { "body_source": "measured" } ] }, "footwear": { "source": "paper" }}Queued or running; poll GET /v1/tryon/{tryon_id}
A try-on: every size of the product’s published garment shown on the body. Poll GET /v1/tryon/{tryon_id} every ~2 s until status is done or failed. A repeated try-on of the same garment version and body answers at once.
object
The try-on’s id (uuid). Empty only for a size estimate (POST ?start=false&view=summary answered with no try-on of this body); there is nothing to poll.
Only in the answer to POST /v1/tryon: the window’s proof that it may read this try-on. Send it as Authorization: Bearer tys_view_… to GET /v1/tryon/{tryon_id}. Stored hashed; never sent again.
object
Present when status is done, and while it runs: the sizes computed so far, each with method (simulated) and state (preview: shown early, may still change; settled; refining: still being computed, no mesh yet; simulated). The try-on result for the window: body mesh and body_state (no basics, no tape measurements), garment with its fabric and estimated POMs, recommended size and per-size meshes, pressure kPa, ease mm and zones. Binary arrays are base64 little-endian; per-vertex values are rounded to display precision.
object
Present when status is done and the request asked for view=summary: what a store may receive (sizes only, never measurements). Size labels are the garment’s (Studio) sizes; map them with shop_sizes from GET /v1/products/{product}/tryon.
object
The recommended size; absent when no size can be worn.
Sizes that can be worn on this body (judged on this body), smallest to largest.
Footwear only - the two sizes the foot sits between (see footwear.between).
How the size was determined (measured: a footwear size from the shopper’s measured feet): estimate (a size estimate, no try-on of this body yet) or simulated (from the try-on of this body). A coarse informational label: do not build logic on its values.
The size answer with its method. On the first answer of a try-on it may already be there (method: estimate) while the 3D view is computed; once done it is the try-on’s own size. An estimate is final (ready or none) only when it is certain for this body; otherwise the status is computing, no size is named, and the try-on’s 3D view gives it.
object
Same as summary.method. A coarse informational label; do not build logic on its values.
Two adjacent sizes when they are genuinely close (smaller first), or, for footwear, the two sizes the foot sits between.
Calibrated probability (0-1) that the shopper keeps the recommended size (either size of between). Present on some estimates.
Facts for the explanation, per zone - the body girth the answer rests on (measured or estimated, with its uncertainty) and the room (garment girth minus body girth, mm; negative is smaller than the body) in the recommended size and its neighbours.
object
object
The numbers behind a footwear size, per size of the chart. Lengths in millimetres, rounded to 0.1 mm. Facts only: the room in front of the toes and how the width compares, never a verdict.
object
The typical measuring uncertainty of the foot length.
Two sizes when the foot sits at their boundary within its measuring uncertainty (the recommended size is the longer one); for an estimate, the range of sizes it may be. Absent when the size is clear.
The recommended width fitting, when the chart has fittings.
True when the brand’s chart gives foot lengths (then chart_foot_mm is the foot length each size is made for) rather than the shoe’s inside length.
object
Room in front of the longest toe (negative - shorter than the foot).
The size’s width minus the foot’s (negative - narrower than the foot).
The toe room is within the shoe type’s usual range.
Present when status is failed.
object
INVALID_BODY, UNSUPPORTED_CATEGORY, MISSING_POM, INVALID_POM, INVALID_FABRIC, NO_SIZES, UNAVAILABLE or ENGINE_ERROR.
Example
{ "status": "queued", "summary": { "method": "estimate" }, "recommendation": { "method": "estimate", "status": "ready", "facts": [ { "body_source": "measured" } ] }, "footwear": { "source": "paper" }}Invalid request
Every error has this shape. error is a human-readable message, status the HTTP status. code is stable and machine-readable; doc_url links its explanation; request_id identifies the request (also in the X-Request-ID response header): quote it to support.
object
Stable error code, e.g. invalid_request, unauthorized, reauth_required, payment_required, forbidden, not_found, conflict, unprocessable, rate_limited, internal_error, not_implemented, unavailable, invalid_api_version, idempotency_key_in_use, idempotency_key_reused, invalid_idempotency_key, handle_expired, handle_invalid.
Example
{ "code": "not_found", "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found"}Missing or invalid credentials
Every error has this shape. error is a human-readable message, status the HTTP status. code is stable and machine-readable; doc_url links its explanation; request_id identifies the request (also in the X-Request-ID response header): quote it to support.
object
Stable error code, e.g. invalid_request, unauthorized, reauth_required, payment_required, forbidden, not_found, conflict, unprocessable, rate_limited, internal_error, not_implemented, unavailable, invalid_api_version, idempotency_key_in_use, idempotency_key_reused, invalid_idempotency_key, handle_expired, handle_invalid.
Example
{ "code": "not_found", "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found"}Not allowed
Every error has this shape. error is a human-readable message, status the HTTP status. code is stable and machine-readable; doc_url links its explanation; request_id identifies the request (also in the X-Request-ID response header): quote it to support.
object
Stable error code, e.g. invalid_request, unauthorized, reauth_required, payment_required, forbidden, not_found, conflict, unprocessable, rate_limited, internal_error, not_implemented, unavailable, invalid_api_version, idempotency_key_in_use, idempotency_key_reused, invalid_idempotency_key, handle_expired, handle_invalid.
Example
{ "code": "not_found", "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found"}No published garment for the product, or (start=false) this body was not simulated yet
Every error has this shape. error is a human-readable message, status the HTTP status. code is stable and machine-readable; doc_url links its explanation; request_id identifies the request (also in the X-Request-ID response header): quote it to support.
object
Stable error code, e.g. invalid_request, unauthorized, reauth_required, payment_required, forbidden, not_found, conflict, unprocessable, rate_limited, internal_error, not_implemented, unavailable, invalid_api_version, idempotency_key_in_use, idempotency_key_reused, invalid_idempotency_key, handle_expired, handle_invalid.
Example
{ "code": "not_found", "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found"}The content is rejected (e.g. a body that cannot be rebuilt)
Every error has this shape. error is a human-readable message, status the HTTP status. code is stable and machine-readable; doc_url links its explanation; request_id identifies the request (also in the X-Request-ID response header): quote it to support.
object
Stable error code, e.g. invalid_request, unauthorized, reauth_required, payment_required, forbidden, not_found, conflict, unprocessable, rate_limited, internal_error, not_implemented, unavailable, invalid_api_version, idempotency_key_in_use, idempotency_key_reused, invalid_idempotency_key, handle_expired, handle_invalid.
Example
{ "code": "not_found", "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found"}A dependency is temporarily unavailable; retry later
Every error has this shape. error is a human-readable message, status the HTTP status. code is stable and machine-readable; doc_url links its explanation; request_id identifies the request (also in the X-Request-ID response header): quote it to support.
object
Stable error code, e.g. invalid_request, unauthorized, reauth_required, payment_required, forbidden, not_found, conflict, unprocessable, rate_limited, internal_error, not_implemented, unavailable, invalid_api_version, idempotency_key_in_use, idempotency_key_reused, invalid_idempotency_key, handle_expired, handle_invalid.
Example
{ "code": "not_found", "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found"}Was this page helpful?
Thank you. We read every answer.