True Fit Recommendations API

openapi: 3.2.0
info:
  title: True Fit Partner Recommendations API
  version: '2026-08-05'
  description: 'These APIs can be used to manage True Fit profiles on behalf of your own users and to

    request size recommendations for retailer products.'
  contact:
    name: True Fit
    email: tech@truefit.com
  license:
    name: Proprietary - (c) True Fit Corporation
servers:
- url: https://partner.truefitcorp.com/api
  description: Partner API
security:
- partnerApiKey: []
tags:
- name: Recommendations
  description: Size recommendations and general fit guidance for retailer products.
paths:
  /partner/{partnerId}/profile/{profileId}/recommendation/bulk:
    parameters:
    - $ref: '#/components/parameters/partnerId'
    - $ref: '#/components/parameters/profileId'
    - $ref: '#/components/parameters/partnerUserId'
    - $ref: '#/components/parameters/tfPartnerUserId'
    post:
      operationId: getBulkRecommendation
      tags:
      - Recommendations
      summary: Recommend sizes for up to 100 products
      description: 'Returns a recommended size per product for the given profile.


        The response array has the **same length and order as the request array**, so results

        can be matched positionally. Each result also echoes the `retailerDomain`, `productId`,

        and `locale` you sent. Failures are per item: a product that cannot be recommended

        returns `success: false` with an `error`, and does not fail the other items.


        This is a `POST` because the product list is sent in the body; it has no side effects

        and returns `201`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkRequest'
            examples:
              mixed:
                value:
                - retailerDomain: https://NYDJ.com/collections/jeans
                  productId: '7093242789933'
                  locale: en_US
                - retailerDomain: landsend.com
                  productId: '532582'
                  locale: en_US
                - retailerDomain: unknown.example.org
                  productId: abc
                  locale: en_US
      responses:
        '201':
          description: One result per requested item, in request order.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BulkRecommendationResult'
              examples:
                mixed:
                  value:
                  - retailerDomain: https://NYDJ.com/collections/jeans
                    productId: '7093242789933'
                    locale: en_US
                    success: true
                    recommendedSize: '10'
                  - retailerDomain: landsend.com
                    productId: '532582'
                    locale: en_US
                    success: false
                    error: noSizesFitTheUser
                  - retailerDomain: unknown.example.org
                    productId: abc
                    locale: en_US
                    success: false
                    error: Unsupported retailer domain
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ProfileNotFound'
  /partner/{partnerId}/general-guidance/bulk:
    parameters:
    - $ref: '#/components/parameters/partnerId'
    post:
      operationId: getBulkGeneralGuidance
      tags:
      - Recommendations
      summary: Get aggregate fit guidance for up to 100 products
      description: 'Returns crowd-sourced fit guidance for products - how the product ran for other

        shoppers - without reference to any individual user.


        Unlike every other endpoint, this one needs **no user identifier**: the partner API key

        alone authorizes it, and no `partnerUserId` or `tfPartnerUserId` query parameter is

        required. Use it for anonymous visitors and for product pages where no profile exists.


        The response array has the same length and order as the request array, and failures are

        per item.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkRequest'
            examples:
              mixed:
                value:
                - retailerDomain: nydj.com
                  productId: '7093242789933'
                  locale: en_US
                - retailerDomain: unknown.example.org
                  productId: abc
                  locale: en_US
      responses:
        '201':
          description: One result per requested item, in request order.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BulkGeneralGuidanceResult'
              examples:
                mixed:
                  value:
                  - retailerDomain: nydj.com
                    productId: '7093242789933'
                    locale: en_US
                    success: true
                    recommendationSummary: Runs small
                    recommendationMessage: Most shoppers found this ran small - consider sizing up.
                  - retailerDomain: unknown.example.org
                    productId: abc
                    locale: en_US
                    success: false
                    error: Unsupported retailer domain
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/UnsupportedPartner'
components:
  schemas:
    BulkRequest:
      type: array
      description: Between 1 and 100 items. Duplicate products are permitted and each gets its own result.
      minItems: 1
      maxItems: 100
      items:
        $ref: '#/components/schemas/BulkRequestItem'
    BulkRecommendationResult:
      description: 'One result, echoing the request item''s fields. Match results to requests by position.

        '
      oneOf:
      - title: Recommended
        allOf:
        - $ref: '#/components/schemas/BulkRequestItem'
        - type: object
          required:
          - success
          - recommendedSize
          properties:
            success:
              type: boolean
              const: true
            recommendedSize:
              type: string
              description: The recommended size label, as the retailer prints it.
              example: '10'
      - title: Not recommended
        allOf:
        - $ref: '#/components/schemas/BulkRequestItem'
        - type: object
          required:
          - success
          - error
          properties:
            success:
              type: boolean
              const: false
            error:
              type: string
              description: "Why no size was returned.\n\nDomain resolution:\n  * `Invalid retailerDomain` - the value could not be parsed as a hostname.\n  * `Unsupported retailer domain` - the hostname is not mapped to a retailer.\n  * `No recommendation returned for product` - the product is unknown to True Fit.\n\nFit outcomes:\n  * `incompleteProfile` - the profile lacks the measurements needed for this garment.\n  * `noProfile` - the profile no longer exists.\n  * `userEstimationInProgress` - body estimation is still running after a\n    profile, measurement, or closet write. Retry after a short delay.\n  * `noSizesFitTheUser` - no stocked size fits.\n  * `invalidGender` - the product's department does not apply to this profile.\n  * `unrecommendableDepartment` - the product is in a department True Fit does\n    not size, such as accessories.\n  * `productMissingData` - the product lacks the garment data needed to size it.\n  * `recommendationDisabled` - recommendations are turned off for that retailer.\n  * `error` - an unexpected failure. Safe to retry.\n"
              examples:
              - Unsupported retailer domain
              - incompleteProfile
              - userEstimationInProgress
    BulkRequestItem:
      type: object
      required:
      - retailerDomain
      - productId
      properties:
        retailerDomain:
          type: string
          minLength: 1
          description: 'The retailer the product belongs to, as a hostname. A full URL is also accepted -

            only the hostname is used, and protocol, port, path, and query string are discarded.

            `www.` is **not** stripped, so the hostname must match the mapping True Fit holds for

            that retailer. Matching is case-insensitive. Ask True Fit to register any retailer

            domain you intend to send.

            '
          examples:
          - nydj.com
          - https://NYDJ.com:443/collections/jeans?utm=x
        productId:
          type: string
          minLength: 1
          description: The retailer's own product identifier.
          example: '7093242789933'
        locale:
          type: string
          description: 'Locale for the product data and any returned copy, as `language_COUNTRY`. Defaults

            to the retailer''s primary locale when omitted.

            '
          example: en_US
    Error:
      type: object
      description: Standard error body.
      required:
      - statusCode
      - message
      properties:
        statusCode:
          type: integer
          example: 404
        message:
          type: string
          example: Profile not found
        error:
          type: string
          example: Not Found
    BulkGeneralGuidanceResult:
      description: 'One result, echoing the request item''s fields. Match results to requests by position.

        '
      oneOf:
      - title: Guidance available
        allOf:
        - $ref: '#/components/schemas/BulkRequestItem'
        - type: object
          required:
          - success
          - recommendationSummary
          - recommendationMessage
          properties:
            success:
              type: boolean
              const: true
            recommendationSummary:
              type: string
              description: Short headline describing how the product runs, localized to `locale`.
              example: Runs small
            recommendationMessage:
              type: string
              description: Longer explanation suitable for display, localized to `locale`.
              example: Most shoppers found this ran small - consider sizing up.
      - title: No guidance
        allOf:
        - $ref: '#/components/schemas/BulkRequestItem'
        - type: object
          required:
          - success
          - error
          properties:
            success:
              type: boolean
              const: false
            error:
              type: string
              description: "Why no guidance was returned.\n  * `Invalid retailerDomain` - the value could not be parsed as a hostname.\n  * `Unsupported retailer domain` - the hostname is not mapped to a retailer.\n  * `No general guidance returned for product` - the product is unknown, or\n    too few shoppers have rated it to produce guidance.\n"
              examples:
              - Unsupported retailer domain
              - No general guidance returned for product
    ValidationError:
      type: object
      description: Schema validation failure. Note this body carries no `statusCode`.
      required:
      - message
      - error
      properties:
        message:
          type: string
          example: Validation failed
        error:
          type: object
          description: Failing field path to error message.
          additionalProperties:
            type: string
  parameters:
    profileId:
      name: profileId
      in: path
      required: true
      description: 'A profile belonging to the identified user, from `GET /profile`. Profiles belonging to

        another user return `404` rather than `403`, so the endpoint cannot be used to probe

        for the existence of other users'' profiles.

        '
      schema:
        type: string
        format: uuid
      example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
    partnerUserId:
      name: partnerUserId
      in: query
      required: false
      description: 'Your own identifier for the user, as passed to `GET /id-sync`. Send either this or

        `tfPartnerUserId`; omitting both returns `400`. If both are sent, `tfPartnerUserId` wins.

        '
      schema:
        type: string
      example: acme-user-42817
    tfPartnerUserId:
      name: tfPartnerUserId
      in: query
      required: false
      description: 'True Fit''s identifier for the user, returned by `GET /id-sync`. Send either this or

        `partnerUserId`; omitting both returns `400`. Takes precedence when both are sent.

        '
      schema:
        type: string
      example: p-3f9c1a80-5d2e-4a17-9b64-8e0c2d7f1a55
    partnerId:
      name: partnerId
      in: path
      required: true
      description: Your partner identifier, issued during onboarding.
      schema:
        type: string
      example: acme
  responses:
    ProfileNotFound:
      description: 'The `profileId` does not exist or does not belong to the identified user. Also returned

        when the `partnerId` is unknown or disabled.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            profileNotFound:
              value:
                statusCode: 404
                message: Profile not found
                error: Not Found
    UnsupportedPartner:
      description: 'The `partnerId` is unknown or disabled. Returned before credentials are checked, so an

        invalid API key against an unknown partner is a `404`, not a `401`.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            unsupportedPartner:
              value:
                statusCode: 404
                message: Unsupported partner
                error: Not Found
    ValidationFailed:
      description: 'The request body or query string failed schema validation. `error` maps each failing

        field path to its message; array indices appear as the first path segment.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
          examples:
            missingField:
              value:
                message: Validation failed
                error:
                  0.retailerDomain: 'Invalid input: expected string, received undefined'
            badEnum:
              value:
                message: Validation failed
                error:
                  category: 'Invalid option: expected one of "belts"|"bottoms"|"bras"'
    Unauthorized:
      description: 'Missing or invalid Basic credentials, or a user identifier that does not match a known

        partner user.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingCredentials:
              value:
                statusCode: 401
                message: Missing Basic auth credentials
                error: Unauthorized
            invalidCredentials:
              value:
                statusCode: 401
                message: Invalid credentials
                error: Unauthorized
            unknownUser:
              summary: The identifier has no True Fit mapping - call GET /id-sync first
              value:
                statusCode: 401
                message: Unknown partner user
                error: Unauthorized
  securitySchemes:
    partnerApiKey:
      type: http
      scheme: basic
      description: 'Empty username, partner API key as the password:

        `Authorization: Basic <base64(":" + apiKey)>`.

        '