True Fit Profile API

openapi: 3.2.0
info:
  title: True Fit - Consumer Profile API
  description: These APIs can be used to create a custom True Fit integration.
  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'
      operationId: getProfiles
      x-operation-id-source: derived
    post:
      tags:
      - Profile
      summary: Create a profile for a user.
      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'
      operationId: postProfiles
      x-operation-id-source: derived
  /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'
      operationId: getProfilesByProfileId
      x-operation-id-source: derived
    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'
      operationId: putProfilesByProfileId
      x-operation-id-source: derived
    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
      operationId: deleteProfilesByProfileId
      x-operation-id-source: derived
  /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'
      operationId: getProfilesByProfileIdFitRecommendations
      x-operation-id-source: derived
  /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.
      operationId: postProfilesByProfileIdSetActive
      x-operation-id-source: derived
  /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'
      operationId: getProfilesByProfileIdStrengthByCategory
      x-operation-id-source: derived
components:
  schemas:
    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.

            '
    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.
    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
    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
    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"}}'
    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.
    ValidationFailure:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
      description: Contains a list of ValidationErrors
    AdultProfile_age:
      required:
      - years
      type: object
      properties:
        years:
          maximum: 125
          minimum: 2
          type: integer
        months:
          maximum: 11
          minimum: 0
          type: integer
    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
    body:
      oneOf:
      - $ref: '#/components/schemas/AdultProfile'
      - $ref: '#/components/schemas/ChildProfile'
    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`.
    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.
    ProfileStrengthQuestions:
      type: string
      enum:
      - BodyShape
      - ClosetItem
    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.
    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
    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"}'
    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`.
    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'
    WeightKg:
      required:
      - uom
      - value
      type: object
      properties:
        value:
          maximum: 500
          minimum: 22
          type: integer
        uom:
          type: string
          enum:
          - Kg
      description: Weight in kilograms.
    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
  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