Seal the signed-in shopper's body into a handle for the brand's server

POST

/v1/recommendation_handles

curl --request POST \
  --url https://api.tryyoursize.com/v1/recommendation_handles \
  --header 'Content-Type: application/json' \
  --header 'TYS-Publishable-Key: <TYS-Publishable-Key>' \
  --data '{ "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 } ], "fit": { "preference": "tight", "preference_tops": "tight", "preference_bottoms": "tight", "usual_sizes": [ { "brand": "example", "line": "tops", "sex": "female", "size": "example" } ] }, "body_state": [ 1 ] }'

• Production (test and live mode are chosen by the key)

Key: publishable (pk_test_… / pk_live_…), from an origin registered for the key.

Called by the TryYourSize window (the SDK’s invisible status frame), never by a brand’s code: it needs the shopper’s session (Authorization: Bearer tys_sess_…), which only our origin can read, plus the store’s publishable key. The answer is an encrypted handle bound to the store, the mode and the shopper; the page passes it to the brand’s server for POST /v1/recommendations. Nothing is stored: the handle itself is the sealed body, and neither the page nor the brand’s server can read it. Expires after an hour.

Authorizations

• PublishableKey

Request Body^required

Media typeapplication/json

The signed-in shopper’s body as the TryYourSize window holds it (the same fields as POST /v1/tryon, without the product). Sent only by our window (status frame) or SDKs, never by a brand’s page or server.

object

basics

required

object

sex

required

string

Allowed values: female male

age_years

required

integer

>= 1

height_mm

required

number format: double

weight_kg

required

number format: double

measurements

Array<object>

<= 64 items

object

code

required

Body measurement from set v1.

string

Allowed values: neck_girth shoulder_width arm_length armscye_girth upper_arm_girth wrist_girth chest_girth underbust_girth bust_point_to_bust_point shoulder_to_bust_point back_length waist_girth front_waist_arc high_hip_girth abdomen_girth hip_girth front_hip_arc thigh_girth knee_girth calf_girth ankle_girth inseam outseam crotch_length

value_mm

required

Measured value in millimetres.

number format: double

source

required

How the value was obtained. bra_size: derived from the shopper’s bra size (underbust and bust only).

string

Allowed values: tape_self tape_helper flat_garment estimated bra_size

sd_mm

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.

number format: double

<= 150

fit

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

preference

string

Allowed values: tight regular loose

preference_tops

string

Allowed values: tight regular loose

preference_bottoms

string

Allowed values: tight regular loose

usual_sizes

Array<object>

<= 20 items

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

id

string format: uuid

brand

required

A brand key from GET /v1/usual-size-brands.

string

>= 1 characters <= 40 characters

line

required

string

Allowed values: tops bottoms

sex

The brand’s women’s (female) or men’s (male) line. Defaults to the shopper’s own.

string

Allowed values: female male

size

required

The size label as the brand writes it (one of the brand’s sizes for this line).

string

>= 1 characters <= 16 characters

source

string

Allowed values: declared kept_purchase

created_at

string format: date-time

updated_at

string format: date-time

body_state

required

Array<number>

>= 1 items <= 64 items

Responses

201

Created

Media typeapplication/json

An opaque, sealed handle for one signed-in shopper on one store and mode. Pass it to your server, which sends it to POST /v1/recommendations with a secret key. It is encrypted: neither your page nor your server can read anything from it, and it never carries the shopper’s email. It expires after an hour.

object

handle

required

Starts with tys_rh_. Up to 4 KB.

string

expires_at

required

string format: date-time

mode

required

string

Allowed values: test live

Example

{
  "handle": "tys_rh_AbC…",
  "mode": "test"
}

400

Invalid request

Media typeapplication/json

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

error

required

string

status

required

integer

code

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.

string

doc_url

string format: uri

request_id

string

Example

{
  "code": "not_found",
  "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found"
}

401

Missing or invalid credentials

Media typeapplication/json

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

error

required

string

status

required

integer

code

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.

string

doc_url

string format: uri

request_id

string

Example

{
  "code": "not_found",
  "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found"
}

403

Not allowed

Media typeapplication/json

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

error

required

string

status

required

integer

code

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.

string

doc_url

string format: uri

request_id

string

Example

{
  "code": "not_found",
  "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found"
}

422

The content is rejected (e.g. a body that cannot be rebuilt)

Media typeapplication/json

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

error

required

string

status

required

integer

code

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.

string

doc_url

string format: uri

request_id

string

Example

{
  "code": "not_found",
  "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found"
}