True Fit Identity API

openapi: 3.2.0
info:
  title: True Fit Partner Identity 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: Identity
  description: Establishing a True Fit user for one of your users.
paths:
  /id-sync:
    get:
      operationId: syncIds
      tags:
      - Identity
      summary: Create a True Fit user for one of your users
      description: 'Creates a True Fit user and maps one of your user identifiers to it. Call this once per

        user, before any other endpoint.


        **Sync each user exactly once and store the returned `tfPartnerUserId`.** Re-syncing a

        `partnerUserId` that has already been synced is not supported: it issues a new

        `tfPartnerUserId` and detaches the profiles, measurements, and closet items written

        under the previous one.


        ### Signing the request


        Requests are signed with HMAC-SHA256 using the shared partner secret issued during

        onboarding. Build the canonical string from every query parameter **except** `hash`,

        sorted by parameter name, URL-encoding each value:


        ```

        canonical = "partnerId=&partnerUserId=" # sorted, hash excluded

        hash = hex(hmac_sha256(partnerSecret, canonical))

        ```


        `redirectUri`, when present, participates in the signature like any other parameter.

        The comparison is timing-safe and the hash must be lowercase hex.


        This endpoint does **not** use Basic authentication - do not send an `Authorization`

        header.'
      security: []
      parameters:
      - name: partnerId
        in: query
        required: true
        description: Your partner identifier, issued during onboarding.
        schema:
          type: string
        example: acme
      - name: partnerUserId
        in: query
        required: true
        description: Your own stable identifier for the user.
        schema:
          type: string
        example: acme-user-42817
      - name: redirectUri
        in: query
        required: false
        description: 'When supplied, the response is a `302` redirect to this URI instead of a JSON body.

          Intended for browser-based flows; server-to-server integrations should omit it.

          '
        schema:
          type: string
          format: uri
      - name: hash
        in: query
        required: true
        description: Lowercase hex HMAC-SHA256 signature over the other query parameters.
        schema:
          type: string
          pattern: ^[0-9a-f]{64}$
      responses:
        '200':
          description: The newly created user mapping.
          content:
            application/json:
              schema:
                type: object
                required:
                - tfPartnerUserId
                properties:
                  tfPartnerUserId:
                    type: string
                    description: 'True Fit''s identifier for this partner user. Prefixed with `p-`. Store it

                      and send it as the `tfPartnerUserId` query parameter on later requests.

                      '
                    example: p-3f9c1a80-5d2e-4a17-9b64-8e0c2d7f1a55
        '302':
          description: Returned instead of `200` when `redirectUri` was supplied.
          headers:
            Location:
              schema:
                type: string
                format: uri
        '400':
          $ref: '#/components/responses/MissingIdSyncParams'
        '401':
          description: The `hash` parameter is missing or the signature does not match.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalidSignature:
                  value:
                    statusCode: 401
                    message: Invalid HMAC signature
                    error: Unauthorized
        '404':
          $ref: '#/components/responses/UnsupportedPartner'
components:
  schemas:
    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
  responses:
    MissingIdSyncParams:
      description: '`partnerId` or `partnerUserId` was not supplied.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingParams:
              value:
                statusCode: 400
                message: Missing required params
                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
  securitySchemes:
    partnerApiKey:
      type: http
      scheme: basic
      description: 'Empty username, partner API key as the password:

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

        '