True Fit Profiles API

openapi: 3.2.0
info:
  title: True Fit Partner Profiles 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: Profiles
  description: Creating and managing fit profiles belonging to a partner user.
paths:
  /partner/{partnerId}/profile:
    parameters:
    - $ref: '#/components/parameters/partnerId'
    - $ref: '#/components/parameters/partnerUserId'
    - $ref: '#/components/parameters/tfPartnerUserId'
    get:
      operationId: listProfiles
      tags:
      - Profiles
      summary: List the user's profiles
      description: 'Returns every profile belonging to the user, oldest first is not guaranteed - treat the

        order as unspecified and address profiles by `profileId`. A user with no profiles yet

        returns an empty array.'
      responses:
        '200':
          description: The user's profiles.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Profile'
              examples:
                single:
                  value:
                  - profileId: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                    alias: Primary
                    department: womens
                    isActive: false
                    estimatedDob: '1994-03-01T00:00:00.000Z'
                    originStore: acme
                    originLocale: null
                    createdAt: '2026-07-14T09:12:44.000Z'
                    updatedAt: '2026-07-31T16:02:10.000Z'
                empty:
                  value: []
        '400':
          $ref: '#/components/responses/MissingUserIdentifier'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/UnsupportedPartner'
    post:
      operationId: createProfile
      tags:
      - Profiles
      summary: Create a profile
      description: 'Creates a profile for the user. The created profile records your `partnerId` as its

        `originStore`. An empty object is a valid body; both fields are optional.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProfileRequest'
            examples:
              withDepartment:
                value:
                  alias: Primary
                  department: womens
              minimal:
                value: {}
      responses:
        '201':
          description: The created profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/UnsupportedPartner'
  /partner/{partnerId}/profile/{profileId}:
    parameters:
    - $ref: '#/components/parameters/partnerId'
    - $ref: '#/components/parameters/profileId'
    - $ref: '#/components/parameters/partnerUserId'
    - $ref: '#/components/parameters/tfPartnerUserId'
    put:
      operationId: updateProfile
      tags:
      - Profiles
      summary: Update a profile
      description: 'Partially updates the profile. Only the fields you send are changed. Updating a profile

        re-runs body estimation, so a subsequent recommendation may briefly return

        `userEstimationInProgress`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProfileRequest'
            examples:
              rename:
                value:
                  alias: Weekend
      responses:
        '204':
          description: Updated. No response body.
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ProfileNotFound'
    delete:
      operationId: deleteProfile
      tags:
      - Profiles
      summary: Delete a profile
      responses:
        '204':
          description: Deleted. No response body.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ProfileNotFound'
components:
  schemas:
    Department:
      type: string
      description: 'Garment department. Matched case-insensitively - `Womens` and `womens` are both accepted

        - and stored lowercased.

        '
      enum:
      - baby
      - boys
      - donotrecommend
      - girls
      - maternity
      - mens
      - not apparel
      - other
      - unisexkids
      - womens
      - unisex
      example: womens
    CreateProfileRequest:
      type: object
      properties:
        department:
          allOf:
          - $ref: '#/components/schemas/Department'
          description: The department the user primarily shops.
        alias:
          type: string
          description: A label for the profile, shown to the user. Not required to be unique.
          example: Primary
    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
    Profile:
      type: object
      required:
      - profileId
      - isActive
      - estimatedDob
      - originStore
      - originLocale
      - createdAt
      - updatedAt
      properties:
        profileId:
          type: string
          format: uuid
        alias:
          type: string
          example: Primary
        department:
          allOf:
          - $ref: '#/components/schemas/Department'
        userId:
          type: string
          description: True Fit's internal user identifier. Not required for any partner call.
        isActive:
          type: boolean
          description: 'Whether this is the active profile in a browser session. Always `false` for partner

            requests, which carry no browser session - ignore it.

            '
        estimatedDob:
          type:
          - string
          - 'null'
          format: date-time
          description: Date of birth inferred from the profile's age measurement, when available.
        originStore:
          type:
          - string
          - 'null'
          description: 'Where the profile was created. Profiles you create through this API carry your

            `partnerId`.

            '
          example: acme
        originLocale:
          type:
          - string
          - 'null'
          example: en_US
        registeredAt:
          type:
          - string
          - 'null'
          format: date-time
        savedAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type:
          - string
          - 'null'
          format: date-time
        updatedAt:
          type:
          - string
          - 'null'
          format: date-time
    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
    UpdateProfileRequest:
      type: object
      description: Every field is optional; only the fields you send are changed.
      properties:
        department:
          allOf:
          - $ref: '#/components/schemas/Department'
        alias:
          type: string
          example: Weekend
        registeredAt:
          type: string
          format: date-time
          description: When the user registered with you. Set once when the user creates an account.
        savedAt:
          type: string
          format: date-time
          description: When the user last explicitly saved the profile.
  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
    MissingUserIdentifier:
      description: Neither `partnerUserId` nor `tfPartnerUserId` was supplied.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingIdentifier:
              value:
                statusCode: 400
                message: tfPartnerUserId or partnerUserId query parameter is required
                error: Bad Request
    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
    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
    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"'
  securitySchemes:
    partnerApiKey:
      type: http
      scheme: basic
      description: 'Empty username, partner API key as the password:

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

        '