True Fit Profile API
Information about the person being shopped for.
OpenAPI Specification
openapi: 3.2.0
info:
title: True Fit - Consumer Profile API
description: "These APIs can be used to create a custom True Fit integration.\n\n# Getting Started\n\nHere are some general concepts - please see further below for the specific endpoint documentation.\n\n## Cookies\nThese APIs leverage third party cookies to enable users to receive recommendations across sites. In order for this to work correctly, when calling the APIs in the context of your website, you must configure the XMLHttpRequest object to use withCredentials=true. If you do not do this, True Fit users may not see recommendations when arriving on your site. For more information on the withCredentials flag, please see the [XMLHttpRequest spec](https://xhr.spec.whatwg.org/#the-withcredentials-attribute).\n\n## Tokens\n\nTrue Fit uses a token to identify the user and their associated session information. True Fit generates and manages tokens on the server side, while the client device is responsible for persisting tokens. Generally, a single token should be used to identify a single client device. The token will be cycled as a user interacts with True Fit to provide increased security and privacy. The token is required to be passed as a header on every endpoint (except the `/token` endpoint).\n\n## Profiles\n\nA profile is the entity that contains information about the person being shopped for. The profile entity itself can contain information such as gender, height, weight and age. When a profile is created, it is assigned an ID. That ID can be used in the path of other endpoints, such as adding closet items and requesting fit recommendations for that profile.\n\n## Creating a profile\n\nIn order to get a fit recommendation, a profile must be created. \nA profile is created by sending POST request to the `/profiles` endpoint. The created profile will be returned on the response, with the addition of an `id` field. A profile can be updated/modified by sending a PUT request to the `/profiles/{profileId}` endpoint.\n\nWhen shopping for other adults or children, a recipient profile should be created. These profiles will be created by sending POST requests to the same `/profiles` endpoint. The token on the request will be used to identify the shopper profile and associate recipients accordingly. \nPlease note that one kids recipient profile can be unnamed (no alias) and no kids recipient profile can have the same alias as another kids recipient profile. Adult recipient profiles must be named (has alias) and cannot have the same alias as another adult recipient profile. \n\n### Adding closet items\n\nIn addition to the fields on the Profile object itself, closet items can also be added for a profile. A closet item is an example article of clothing that the person already wears and likes, which True Fit uses to inform fit recommendations. Closet items are added by sending a POST request to `/profiles/{profileId}/closet` endpoint. Similar to Profiles, the created closet item is returned on the response, with the addition of an `id` field. A closet item can be updated by sending a PUT request to `/profiles/{profileId}/closet/{closetId}`.\n\nChild profiles can only have one closet item per category. In the event that a second closet item is saved, a validation error will be returned.\n\n## Getting a fit recommendation for a product\n\nIf the product is recommendable (see `GET /products`), and there is a profile on the session (see `GET /profiles`), then a fit recommendation request can be made for that profile and product. A fit recommendation request can be made by a GET request to the `/profiles/{profileId}/fit-recommendations` endpoint. The information required to get a recommendation varies by the gender of the Profile and the Category of the style in question. If True Fit is able to provide a recommendation, the `status` will be `success`. Otherwise, the `status` will indicate why the recommendation wasn't able to be produced.\n\n## Example Flow - Product Page\n1. Check if token has already been persisted (in a cookie, perhaps) - if not, make a GET request to the `/token` endpoint to get one, then persist it.\n1. Make a GET request to `/products/{styleId}` to get the product info.\n1. In parallel, make a GET request to `/profiles` to get the current profiles on the session (if any)\n1. If the product info shows that the product is not recommendable, then stop here. Otherwise continue.\n1. If the profiles request returns an empty list of profiles then give the user an opportunity to register for True Fit.\n1. If the user begins to register, update the token and use the information from the product info to determine the gender, age group, and category that is of interest.\n1. Have the user answer questions to create a profile and add a closet item for the category.\n1. Request a fit recommendation from the `/profiles/{profileId}/fit-recommendations` endpoint and present the recommendation to the user.\n\n## General API Behavior\n* A `404 - Not Found` will be returned when an unspecified endpoint is hit.\n* If a valid endpoint is hit with a method it doesn't support, a `405 -\nMethod Not Allowed` will be returned.\n* If a request has an invalid value, a `400 - Bad Request` will be returned \n* It is possible for any endpoint to return a `500 - Internal Server Error` if an unexpected error is encountered.\n* When True Fit is performing maitenence on the system, a `404 - Not Found` with the response header `X-TF-Disabled: StoreDisabled` will be returned for all endpoints. \n"
version: '3.0'
servers:
- url: /profile/public/v3/{tla}
tags:
- name: Profile
description: Information about the person being shopped for.
paths:
/profiles:
get:
tags:
- Profile
summary: Retrieve the profiles on the current session.
parameters:
- name: X-TF-UserToken
in: header
description: The session token for the current user.
required: true
style: simple
explode: false
schema:
type: string
responses:
'200':
description: A list of profiles that the user has created. Will be empty if the user has not interacted with True Fit yet.
headers:
X-TF-UserToken:
description: The updated token for the user. This updated token should be used on all following requests. This header is only present when the token has cycled.
style: simple
explode: false
schema:
type: string
X-TF-UserTokenMaxAge:
description: This will be most useful when storing the token as a cookie. The value is the suggested max age of the token (in seconds).
style: simple
explode: false
schema:
type: integer
content:
application/json:
schema:
type: array
items:
oneOf:
- $ref: '#/components/schemas/AdultProfile'
- $ref: '#/components/schemas/ChildProfile'
post:
tags:
- Profile
summary: 'Create a profile for a user. Or, link a Store User ID and retrieve the profiles for the current session.
'
parameters:
- name: X-TF-UserToken
in: header
description: The session token for the current user.
required: true
style: simple
explode: false
schema:
type: string
- name: X-TF-StoreUserId
in: header
description: 'Use this header when retrieving the profiles for the current session, while associating the session with a Store User ID. This is required to support features like Instant Profiles and Store Credentials.
If the user is not currently logged in to a store account, `null` or `undefined` must be passed as the value. The Store User ID must be an anonymous unique identifier for the current user. (not a name or email address, for example)
**If this header is on the request, the request body must be empty. The response will be a (potentially empty) list of Profiles.**
'
required: false
style: simple
explode: false
schema:
type: string
- name: s
in: query
description: Store Style IDs to request an Instant Profile for. Only used when passing the X-TF-StoreUserId header, not when creating a new profile.
required: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: locale
in: query
description: 'Identifier specifying the locale to use when retrieving suggested brands or any type of sizes e.g. sizes, bra sizes, inseams or sleeve lengths. This attribute is only required when the store supports multiple locales. Use an ISO 639 language code followed by an ISO 3166 country code, e.g. en_US. '
required: false
style: form
explode: true
schema:
type: string
requestBody:
description: The profile to create.
content:
application/json:
schema:
$ref: '#/components/schemas/body'
responses:
'200':
description: "Profile successfully created. \n\nOr, profiles on the session successfully retrieved (see `X-TF-StoreUserId` header description). If `X-TF-StoreUserId` is passed, the response will be a (potentially empty) list of Profiles.\n"
headers:
X-TF-UserToken:
description: The updated token for the user. This updated token should be used on all following requests. This header is only present when the token has cycled.
style: simple
explode: false
schema:
type: string
X-TF-UserTokenMaxAge:
description: This will be most useful when storing the token as a cookie. The value is the suggested max age of the token (in seconds).
style: simple
explode: false
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/body'
'400':
description: Profile not created due to bad data
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationFailure'
/profiles/{profileId}:
get:
tags:
- Profile
summary: Retrieve a specific profile by id
parameters:
- name: X-TF-UserToken
in: header
description: The session token for the current user.
required: true
style: simple
explode: false
schema:
type: string
- name: profileId
in: path
required: true
style: simple
explode: false
schema:
type: string
responses:
'200':
description: Profile successfully retrieved
headers:
X-TF-UserToken:
description: The updated token for the user. This updated token should be used on all following requests. This header is only present when the token has cycled.
style: simple
explode: false
schema:
type: string
X-TF-UserTokenMaxAge:
description: This will be most useful when storing the token as a cookie. The value is the suggested max age of the token (in seconds).
style: simple
explode: false
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/body'
put:
tags:
- Profile
summary: Update a profile
parameters:
- name: X-TF-UserToken
in: header
description: The session token for the current user.
required: true
style: simple
explode: false
schema:
type: string
- name: profileId
in: path
required: true
style: simple
explode: false
schema:
type: string
requestBody:
$ref: '#/components/requestBodies/Profile'
responses:
'200':
description: Profile successfully updated
headers:
X-TF-UserToken:
description: The updated token for the user. This updated token should be used on all following requests. This header is only present when the token has cycled.
style: simple
explode: false
schema:
type: string
X-TF-UserTokenMaxAge:
description: This will be most useful when storing the token as a cookie. The value is the suggested max age of the token (in seconds).
style: simple
explode: false
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/body'
'400':
description: Profile not updated due to bad data
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationFailure'
delete:
tags:
- Profile
summary: Delete a recipient from a shopper's profile.
parameters:
- name: X-TF-UserToken
in: header
description: The session token for the current user.
required: true
style: simple
explode: false
schema:
type: string
- name: profileId
in: path
required: true
style: simple
explode: false
schema:
type: string
responses:
'200':
description: Profile successfully deleted
headers:
X-TF-UserToken:
description: The updated token for the user. This updated token should be used on all following requests. This header is only present when the token has cycled.
style: simple
explode: false
schema:
type: string
X-TF-UserTokenMaxAge:
description: This will be most useful when storing the token as a cookie. The value is the suggested max age of the token (in seconds).
style: simple
explode: false
schema:
type: integer
'400':
description: A shopper user cannot be deleted
/profiles/{profileId}/fit-recommendations:
get:
tags:
- Profile
summary: Get a Fit Recommendation for the given styles.
parameters:
- name: X-TF-UserToken
in: header
description: The session token for the current user.
required: true
style: simple
explode: false
schema:
type: string
- name: profileId
in: path
required: true
style: simple
explode: false
schema:
type: string
- name: locale
in: query
description: 'Identifier specifying the locale to use when retrieving suggested brands or any type of sizes e.g. sizes, bra sizes, inseams or sleeve lengths. This attribute is only required when the store supports multiple locales. Use an ISO 639 language code followed by an ISO 3166 country code, e.g. en_US. '
required: false
style: form
explode: true
schema:
type: string
- name: integrationPlatform
in: query
description: Specifies whether the call is being made from inside the context of an app or the web.
required: false
style: form
explode: true
schema:
type: string
enum:
- App
- Web
- name: s
in: query
description: Store Style IDs to request Fit Recommendations for.
required: true
style: form
explode: true
schema:
minItems: 1
type: array
items:
type: string
responses:
'200':
description: The Fit Recommendation results for the requested styles.
headers:
X-TF-UserToken:
description: The updated token for the user. This updated token should be used on all following requests. This header is only present when the token has cycled.
style: simple
explode: false
schema:
type: string
X-TF-UserTokenMaxAge:
description: This will be most useful when storing the token as a cookie. The value is the suggested max age of the token (in seconds).
style: simple
explode: false
schema:
type: integer
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FitDetailsResultSet'
/profiles/{profileId}/set-active:
post:
tags:
- Profile
summary: Change the active profile on the session.
description: Set the `profileId` on the path as an active profile.
parameters:
- name: X-TF-UserToken
in: header
description: The session token for the current user.
required: true
style: simple
explode: false
schema:
type: string
- name: profileId
in: path
required: true
style: simple
explode: false
schema:
type: string
responses:
'200':
description: The profile was successfully set as active.
headers:
X-TF-UserToken:
description: The updated token for the user. This updated token should be used on all following requests. This header is only present when the token has cycled.
style: simple
explode: false
schema:
type: string
X-TF-UserTokenMaxAge:
description: This will be most useful when storing the token as a cookie. The value is the suggested max age of the token (in seconds).
style: simple
explode: false
schema:
type: integer
'400':
description: The profile ID passed is invalid or cannot be used to set the active profile.
/profiles/{profileId}/strength/{category}:
get:
tags:
- Profile
summary: Get a category specific profile strength for a profile.
parameters:
- name: X-TF-UserToken
in: header
description: The session token for the current user.
required: true
style: simple
explode: false
schema:
type: string
- name: profileId
in: path
required: true
style: simple
explode: false
schema:
type: string
- name: category
in: path
required: true
style: simple
explode: false
schema:
type: string
responses:
'200':
description: The Profile Strength result for the requested category.
headers:
X-TF-UserToken:
description: The updated token for the user. This updated token should be used on all following requests. This header is only present when the token has cycled.
style: simple
explode: false
schema:
type: string
X-TF-UserTokenMaxAge:
description: This will be most useful when storing the token as a cookie. The value is the suggested max age of the token (in seconds).
style: simple
explode: false
schema:
type: integer
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ProfileStrength'
components:
schemas:
HeightFtIn:
required:
- secondValue
- uom
- value
type: object
properties:
value:
maximum: 8
minimum: 2
type: integer
secondValue:
maximum: 11
minimum: 0
type: integer
uom:
type: string
enum:
- FtIn
description: Height in feet and inches.
example:
value: 5
secondValue: 6
uom: FtIn
ProfileStrength:
type: object
properties:
strength:
type: integer
description: Value ranges from 0 to 100.
readOnly: true
example: 85
remainingQuestions:
type: array
readOnly: true
items:
$ref: '#/components/schemas/ProfileStrengthQuestions'
example:
strength: 70
remainingQuestions:
- BodyShape
- ClosetItem
FitDetailsResultSet:
required:
- status
- styleId
type: object
properties:
styleId:
type: string
description: The store style ID that this result corresponds to.
status:
type: string
description: If the status is success, render the fit details page. If the status is estimationinprogress, a refershAfter should also come back on the FitDetailsResultSet, and another call for a fit rec should be made after the refreshAfter delay. For any other status, don't render the fit details page.
enum:
- error
- incompletegarment
- incompleteprofile
- invaliddepartment
- success
- estimationinprogress
- sizenotavailable
- unrecommendabledepartment
bestSize:
$ref: '#/components/schemas/FitDetails'
sizeUp:
$ref: '#/components/schemas/FitDetails'
sizeDown:
$ref: '#/components/schemas/FitDetails'
refreshAfter:
type: integer
description: If we can't provide a recommendation at the moment, the amount of time in milliseconds to wait before trying to retrieve a recommendation again.
AdultProfile_inseam:
type: object
properties:
exact:
$ref: '#/components/schemas/AdultProfile_inseam_exact'
general:
type: string
enum:
- Short
- Regular
- Long
- ExtraLong
description: Exactly one field either `exact` or `general` should be included on this object
example: '{"exact":{"value":30,"uom":"In"}}'
AdultProfile_sleeveLength:
type: object
properties:
exact:
$ref: '#/components/schemas/AdultProfile_sleeveLength_exact'
general:
type: string
enum:
- WayTooShort
- TooShort
- JustRight
- TooLong
- WayTooLong
description: Exactly one field either `exact` or `general` should be included on this object
example: '{"general":"WayTooShort"}'
WeightStLb:
required:
- secondValue
- uom
- value
type: object
properties:
value:
maximum: 89
minimum: 3
type: integer
secondValue:
maximum: 13
minimum: 0
type: integer
uom:
type: string
enum:
- StLb
description: Weight in stones and pounds.
FitDetails:
required:
- size
type: object
properties:
size:
type: string
recommended:
type: boolean
score:
maximum: 5
minimum: 1
type: number
description: A value between 1.0 and 5.0 that determines how good the overall fit of an item is.
overallFit:
maximum: 7
minimum: 0
type: number
description: A value between 0 - 7 that represents how good the overall fit of an item is. 0 represents snuggest, 3 or 4 represent an ideal fit, and 7 represents loosest. This should only come back if the list of poms are empty.
poms:
type: array
items:
$ref: '#/components/schemas/FitMeasurementPoint'
AdultProfile_age:
required:
- years
type: object
properties:
years:
maximum: 125
minimum: 2
type: integer
months:
maximum: 11
minimum: 0
type: integer
AdultProfile_inseam_exact:
required:
- uom
- value
type: object
properties:
uom:
type: string
description: The `uom` from the Available Length object returned from the available inseams endpoint.
value:
type: integer
description: One of the values from the Available Length object from the available inseams endpoint that corresponds to the given `uom`.
ChildProfile:
required:
- gender
- id
type: object
properties:
id:
type: string
description: This field is populated by the server, never created by the client.
readOnly: true
example: someProfileId
gender:
type: string
enum:
- Female
- Male
age:
$ref: '#/components/schemas/AdultProfile_age'
ageGroup:
type: string
default: Adult
enum:
- Adult
- Child
alias:
type: string
description: The name given to this profile by the user.
isActive:
type: boolean
description: Is this profile active on the session. Only one profile in each ageGroup can be active at a time.
readOnly: true
isShopper:
type: boolean
description: Is this the shopper profile on the session. Only one profile in can be the shopper.
readOnly: true
body:
oneOf:
- $ref: '#/components/schemas/AdultProfile'
- $ref: '#/components/schemas/ChildProfile'
WeightKg:
required:
- uom
- value
type: object
properties:
value:
maximum: 500
minimum: 22
type: integer
uom:
type: string
enum:
- Kg
description: Weight in kilograms.
AdultProfile_sleeveLength_exact:
required:
- uom
- value
type: object
properties:
uom:
type: string
description: The `uom` from the Available Length object returned from the available sleeve length endpoint.
value:
type: integer
description: One of the values from the Available Length object from the available sleeve length endpoint that corresponds to the given `uom`.
WeightLb:
required:
- uom
- value
type: object
properties:
value:
maximum: 1250
minimum: 50
type: integer
uom:
type: string
enum:
- Lb
description: Weight in pounds.
example:
value: 145
uom: Lb
ProfileStrengthQuestions:
type: string
enum:
- BodyShape
- ClosetItem
FitMeasurementPoint:
required:
- measurementPoint
- pomType
- value
type: object
properties:
measurementPoint:
type: string
enum:
- Bust
- Chest
- FootLength
- FootWidth
- Inseam
- LowHip
- NaturalWaist
- Neck
- Shoulders
- SleeveLength
- Thigh
- Waist
pomType:
type: string
enum:
- Girth
- Length
- Width
value:
maximum: 7
minimum: 0
type: number
description: 'A value between 0 - 7 that represents how good of a fit an item is at a specific point. 0 represents snuggest, 3 or 4 represent an ideal fit, and 7 represents loosest.
'
ValidationError:
type: object
properties:
reason:
type: string
description: The specific reason for why the request failed.
enum:
- HeightOutOfRange
- WeightOutOfRange
- AgeOutOfRange
- AliasLength
- InvalidAlias
- DuplicateAlias
- UnexpectedError
message:
type: string
description: 'A message explaining what went wrong, and if possible, how to correct the error. NOT localized - do not display to the user - only for developer usage.
'
description: An error that occurred as a result of sending bad data.
HeightCm:
required:
- uom
- value
type: object
properties:
value:
maximum: 260
minimum: 60
type: integer
uom:
type: string
enum:
- Cm
description: Height in centimeters.
example:
value: 175
uom: Cm
AdultProfile:
required:
- gender
- id
type: object
properties:
id:
type: string
description: This field is populated by the server, never created by the client.
readOnly: true
example: someProfileId
gender:
type: string
enum:
- Female
- Male
height:
example:
value: 5
secondValue: 6
uom: FtIn
oneOf:
- $ref: '#/components/schemas/HeightFtIn'
- $ref: '#/components/schemas/HeightCm'
weight:
example:
value: 145
uom: Lb
oneOf:
- $ref: '#/components/schemas/WeightLb'
- $ref: '#/components/schemas/WeightStLb'
- $ref: '#/components/schemas/WeightKg'
age:
$ref: '#/components/schemas/AdultProfile_age'
braSizeId:
type: string
description: The `id` from the Size object for the bra size the user selected.
inseam:
$ref: '#/components/schemas/AdultProfile_inseam'
sleeveLength:
$ref: '#/components/schemas/AdultProfile_sleeveLength'
ageGroup:
type: string
default: Adult
enum:
- Adult
- Child
alias:
type: string
description: The name given to this profile by the user.
isActive:
type: boolean
description: Is this profile active on the session. Only one profile in each ageGroup can be active at a time.
readOnly: true
isShopper:
type: boolean
description: Is this the shopper profile on the session. Only one profile in can be the shopper.
ValidationFailure:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ValidationError'
description: Contains a list of ValidationErrors
requestBodies:
Profile:
description: Profile object that represents the person being shopped for.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/AdultProfile'
- $ref: '#/components/schemas/ChildProfile'
required: true
x-explorer-enabled: false