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

POST

/v1/recommendation_handles

const url = 'https://api.tryyoursize.com/v1/recommendation_handles';
const options = {
  method: 'POST',
  headers: {
    'TYS-Publishable-Key': '<TYS-Publishable-Key>',
    'Content-Type': 'application/json'
  },
  body: '{"basics":{"sex":"female","age_years":1,"height_mm":1,"weight_kg":1},"measurements":[{"code":"neck_girth","value_mm":1,"source":"tape_self"}],"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/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" } ], "body_state": [ 1 ] }'

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

application/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

string

Allowed values: tape_self tape_helper flat_garment estimated

body_state

required

Array<number>

>= 1 items <= 64 items

Responses

201

Created

application/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

application/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

application/json

object

error

required

string

status

required

integer

code

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

application/json

object

error

required

string

status

required

integer

code

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)

application/json

object

error

required

string

status

required

integer

code

string

doc_url

string format: uri

request_id

string

Example

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

Was this page helpful?

Need help?[email protected]What changed?ChangelogUsing an AI assistant?llms.txt

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

Authorizations

Request Bodyrequired

Responses

201

Example

400

Example

401

Example

403

Example

422

Example

Request Body^required