InteractiveDescriptionGuidance.yaml

openapi: 3.1.0
info:
  title: Interactive Description Guidance
  description: |
    The Interactive Commodity Description API will guide an International shipper through a series of 
      multiple-choice questions in order to improve the commodity description such that it can be tied to a full, 
      destination country specific Harmonized Tariff Schedule code (HTS). The tariff code is used for expediting customs 
      clearance, avoiding customs holds, and ensuring accurate assessing of duties and taxes. Both an updated, natural 
      language description and tariff code will be returned. The chargeable event is the return of the full tariff code.

    For more information on the Interactive Description API, please visit the <a href="https://developer.ups.com/api/reference/exportassure/product-info" target="_blank" rel="noopener">Product Info</a> page.
    
    <br/><p>Try out UPS APIs with example requests using Postman and learn more about the UPS Postman Collection by visiting our <a href="https://developer.ups.com/api/reference/postman/guide"
    target="_blank" rel="noopener">Postman Guide</a>. Explore API documentation and sample applications through GitHub.</p>
    
    <a href="https://god.gw.postman.com/run-collection/29542085-1a9d5822-0333-4bec-b1a5-c2ec6b5a81da?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D29542085-1a9d5822-0333-4bec-b1a5-c2ec6b5a81da%26entityType%3Dcollection%26workspaceId%3D7e7595f0-4829-4f9a-aee1-75c126b9d417" target="_blank" rel="noopener noreferrer">
      <img src="https://run.pstmn.io/button.svg" alt="Run In Postman" style="width: 128px; height: 32px;"></a>
    <a href="https://github.com/UPS-API" target="_blank" rel="noopener noreferrer">
      <img src="https://www.ups.com/assets/resources/webcontent/images/gitHubButton.svg" alt="Open in GitHub" style="width: 128px; height: 32px;">
    </a>
  version: "1.0"
servers:
  - url: https://wwwcie.ups.com/api/export-assure/{version}
    description: Customer Integration Environment URL
    variables:
      version:
        default: v1
        enum:
          - v1
  - url: https://onlinetools.ups.com/api/export-assure/{version}
    description: Production URL
    variables:
      version:
        default: v1
        enum:
          - v1
security:
  - OAuth2: []
tags:
  - name: Interactive Description
    description: Operations for interactively generating detailed product descriptions and HTC codes.
  - name: Feedback
    description: Operations for providing feedback using the 'id' of a question.
paths:
  /interactive:
    post:
      tags:
        - Interactive Description
      summary: Initiates an interactive description session for a product.
      description: Initiates an interactive description session for a product.
      security:
        - OAuth2: [] 
      operationId: start_interactive_post
      parameters:
        - name: transId
          in: header
          required: true
          description: A 128 bit GUID.
          schema:
            type: string
            maxLength: 32
        - name: transactionSrc
          in: header
          required: true
          description: The consuming application or user name.
          schema:
            type: string
        - name: version
          in: path
          description: version
          required: true
          schema:
            type: string
            default: v1
            enum:
                - v1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StartRequest"
      responses:
        "200":
          description: Successful Response
          headers: 
            x-api-success-count:
              description: |- 
                UPS monetization header indicating the full completion of the API service. 
                A value of 1 would indicate a completed transaction, while a value of 0 would be the default for uncomplete.
                A value of 1 should be present whenever the "noMoreQuestions" field is set to true.
              schema: 
                type: integer
                example: 1
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InteractiveResponse"
        "400":
          description: Bad Request
          headers:
            APIErrorMsg:
              description: Error message describing the error
              schema:
                type: string
                example: "Invalid input provided"
            APIErrorCode:
              description: Error code indicating the type of error
              schema:
                type: string
                example: "4000"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomErrorResponse"
              examples: 
                E4000:
                  value:
                    response:
                      errors:
                        - code: "4000"
                          message: "Invalid input provided"
                E7001:
                  value:
                    response:
                        errors:
                          - code: "7001"
                            message: "Unsupported Country"
                E7002:
                  value:
                    response:
                      errors:
                        - code: "7002"
                          message: "Unsupported Language"
                E7004:
                  value:
                    response:
                      errors:
                        - code: "7004"
                          message: "Session Expired or Does Not Exist"
                E7008:
                  value:
                    response:
                      errors:
                        - code: "7008"
                          message: "Invalid Commodity HTS Code"
                E7011:
                  value:
                    response:
                      errors:
                        - code: "7011"
                          message: "Insufficient Description"
                E7015:
                  value:
                    response:
                      errors:
                        - code: "7015"
                          message: "Selected Locale Does Not Match Description Language"
        "401":
          description: Unauthorized
          headers:
            APIErrorMsg:
              description: Error message describing the error
              schema:
                type: string
                example: "Invalid token or token is not present"
            APIErrorCode:
              description: Error code indicating the type of error
              schema:
                type: string
                example: "UJ0001"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomErrorResponse"
              examples: 
                UJ0001:
                  value:
                    response:
                      errors:
                        - code: "UJ0001"
                          message: "Invalid token or token is not present"
        "415":
          description: Unsupported Media Type
          headers:
            APIErrorMsg:
              description: Error message describing the error
              schema:
                type: string
                example: "Unsupported Media Type"
            APIErrorCode:
              description: Error code indicating the type of error
              schema:
                type: string
                example: "4015"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomErrorResponse"
              examples: 
                  E4015:
                    value:
                      response:
                        errors:
                          - code: "4015"
                            message: "Unsupported Media Type"
        "422":
          description: Unprocessable Entity
          headers:
            APIErrorMsg:
              description: Error message describing the error
              schema:
                type: string
                example: "Unprocessable Entity"
            APIErrorCode:
              description: Error code indicating the type of error
              schema:
                type: string
                example: "4022"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomErrorResponse"
              examples: 
                E4022:
                  value:
                    response:
                      errors:
                        - code: "4022"
                          message: "Unprocessable Entity"
        "500":
          description: Internal Server Error
          headers:
            APIErrorMsg:
              description: Error message describing the error
              schema:
                type: string
                example: "Internal Server Error"
            APIErrorCode:
              description: Error code indicating the type of error
              schema:
                type: string
                example: "5000"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomErrorResponse"
              examples: 
                E5000:
                  value:
                    response:
                      errors:
                        - code: "5000"
                          message: "Internal Server Error"
  /interactive/{sessionId}:
    post:
      tags:
        - Interactive Description
      summary: Continues refinement of product description and HTS code via questions and answers.
      description: |
        This endpoint facilitates the ongoing interactive process for refining a product description and determining its corresponding Harmonized Tariff Schedule (HTS) code. 
        
        After initiating a session with the initial product description using the /interactive endpoint, users can continue their interaction via this endpoint by providing answers to the questions returned from the previous interaction. Each interaction refines the product description further, helping the system to accurately identify the correct HTS code. The {sessionId} parameter uniquely identifies the user's session and ensures that the interaction is continued seamlessly.
      security:
        - OAuth2: [] 
      operationId: iterate_interactive__sessionId__post
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
        - name: transId
          in: header
          required: true
          description: A 128 bit GUID.
          schema:
            type: string
            maxLength: 32
        - name: transactionSrc
          in: header
          required: true
          schema:
            type: string
        - name: version
          in: path
          description: version
          required: true
          schema:
            type: string
            default: v1
            enum:
                - v1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IterateRequest"
      responses:
        "200":
          description: Successful Response
          headers: 
            x-api-success-count:
              description: |- 
                UPS monetization header indicating the full completion of the API service. 
                A value of 1 would indicate a completed transaction, while a value of 0 would be the default for uncomplete.
                A value of 1 should be present whenever the "noMoreQuestions" field is set to true.
              schema: 
                type: integer
                example: 1
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InteractiveResponse"
        "400":
          description: Bad Request
          headers:
            APIErrorMsg:
              description: Error message describing the error
              schema:
                type: string
                example: "Invalid input provided"
            APIErrorCode:
              description: Error code indicating the type of error
              schema:
                type: string
                example: "4000"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomErrorResponse"
              examples: 
                E4000:
                  value:
                    response:
                      errors:
                        - code: "4000"
                          message: "Invalid input provided"
                E7005:
                  value:
                    response:
                      errors:
                        - code: "7005"
                          message: "Unknown Question"
                E7006:
                  value:
                    response:
                      errors:
                        - code: "7006"
                          message: "Invalid Sequence"
                E7007:
                  value:
                    response:
                      errors:
                        - code: "7007"
                          message: "Option Index Out of Range"
        "401":
          description: Unauthorized
          headers:
            APIErrorMsg:
              description: Error message describing the error
              schema:
                type: string
                example: "Invalid token or token is not present"
            APIErrorCode:
              description: Error code indicating the type of error
              schema:
                type: string
                example: "UJ0001"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomErrorResponse"
              examples: 
                UJ0001:
                  value:
                    response:
                      errors:
                        - code: "UJ0001"
                          message: "Invalid token or token is not present"
        "415":
          description: Unsupported Media Type
          headers:
            APIErrorMsg:
              description: Error message describing the error
              schema:
                type: string
                example: "Unsupported Media Type"
            APIErrorCode:
              description: Error code indicating the type of error
              schema:
                type: string
                example: "4015"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomErrorResponse"
              examples: 
                E4015:
                  value:
                    response:
                      errors:
                        - code: "4015"
                          message: "Unsupported Media Type"
        "422":
          description: Unprocessable Entity
          headers:
            APIErrorMsg:
              description: Error message describing the error
              schema:
                type: string
                example: "Unprocessable Entity"
            APIErrorCode:
              description: Error code indicating the type of error
              schema:
                type: string
                example: "4022"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomErrorResponse"
              examples: 
                E4022:
                  value:
                    response:
                      errors:
                        - code: "4022"
                          message: "Unprocessable Entity"
        "500":
          description: Internal Server Error
          headers:
            APIErrorMsg:
              description: Error message describing the error
              schema:
                type: string
                example: "Internal Server Error"
            APIErrorCode:
              description: Error code indicating the type of error
              schema:
                type: string
                example: "5000"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomErrorResponse"
              examples: 
                E5000:
                  value:
                    response:
                      errors:
                        - code: "5000"
                          message: "Internal Server Error"
  /interactive/feedback/{sessionId}:
    post:
      tags:
        - Interactive Description
      summary: Allows the user to provide feedback on a specific question of the
        overall session.
      description: Allows the user to provide feedback on a specific question of the
        overall session.
      security:
        - OAuth2: [] 
      operationId: submit_feedback_interactive_feedback__sessionId__post
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
        - name: version
          in: path
          description: version
          required: true
          schema:
            type: string
            default: v1
            enum:
                - v1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Feedback"
      responses:
        "204":
          description: Successful Response
        "400":
          description: Bad Request
          headers:
            APIErrorMsg:
              description: Error message describing the error
              schema:
                type: string
                example: "Invalid input provided"
            APIErrorCode:
              description: Error code indicating the type of error
              schema:
                type: string
                example: "4000"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomErrorResponse"
              examples: 
                E4000:
                  value:
                    response:
                      errors:
                        - code: "4000"
                          message: "Invalid input provided"
                E7004:
                  value:
                    response:
                      errors:
                        - code: "7004"
                          message: "Session Expired or Does Not Exist"
                E7005:
                  value:
                    response:
                      errors:
                        - code: "7005"
                          message: "Unknown Question"
        "401":
          description: Unauthorized
          headers:
            APIErrorMsg:
              description: Error message describing the error
              schema:
                type: string
                example: "Invalid token or token is not present"
            APIErrorCode:
              description: Error code indicating the type of error
              schema:
                type: string
                example: "UJ0001"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomErrorResponse"
              examples: 
                UJ0001:
                  value:
                    response:
                      errors:
                        - code: "UJ0001"
                          message: "Invalid token or token is not present"
        "415":
          description: Unsupported Media Type
          headers:
            APIErrorMsg:
              description: Error message describing the error
              schema:
                type: string
                example: "Unsupported Media Type"
            APIErrorCode:
              description: Error code indicating the type of error
              schema:
                type: string
                example: "4015"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomErrorResponse"
              examples: 
                E4015:
                  value:
                    response:
                      errors:
                        - code: "4015"
                          message: "Unsupported Media Type"
        "422":
          description: Unprocessable Entity
          headers:
            APIErrorMsg:
              description: Error message describing the error
              schema:
                type: string
                example: "Unprocessable Entity"
            APIErrorCode:
              description: Error code indicating the type of error
              schema:
                type: string
                example: "4022"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomErrorResponse"
              examples: 
                E4022:
                  value:
                    response:
                      errors:
                        - code: "4022"
                          message: "Unprocessable Entity"
        "500":
          description: Internal Server Error
          headers:
            APIErrorMsg:
              description: Error message describing the error
              schema:
                type: string
                example: "Internal Server Error"
            APIErrorCode:
              description: Error code indicating the type of error
              schema:
                type: string
                example: "5000"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomErrorResponse"
              examples: 
                E5000:
                  value:
                    response:
                      errors:
                        - code: "5000"
                          message: "Internal Server Error"
components:
  schemas:
    Answer:
      type: object
      properties:
        id:
          type: string
          description: |- 
            The "id" field in the response structure represents the unique identifier of the question that was answered.
            This identifier helps track which specific question the user's response corresponds to, ensuring the accuracy and continuity of the interactive session. It is used to maintain the sequence of interactions and to provide context for subsequent questions and answers.
        selected:
          type: integer
          description: |-
            The "selected" field represents the index of the chosen option from the multiple-choice answers provided for a specific question. 
            This is a 0-based index, meaning the first option is represented by 0, the second by 1, and so on.
            This field ensures that the system accurately records the user's choice and continues the interactive session based on the selected answer.
      required:
        - id
        - selected
    Countries:
      type: string
      enum:
        - "US"
        - "CA"
        - "CN"
        - "UK"
        - "DE"
        - "HK"
        - "NL"
        - "IT"
        - "ES"
        - "FR"
        - "GB"
        - "IE"
    CustomErrorResponse:
      type: object
      properties:
        response:
          $ref: "#/components/schemas/ErrorObjList"
      required:
        - response
    ErrorObj:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message
    ErrorObjList:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: "#/components/schemas/ErrorObj"
      required:
        - errors
    Feedback:
      type: object
      properties:
        id:
          type: string
          description: The id field represents the unique identifier of the specific question for which the user is submitting feedback. This identifier ensures that the feedback is accurately associated with the correct question within the session.
        sentiment:
          type: boolean
          description: The "sentiment" field is a boolean that indicates the user's sentiment towards the specific question. A value of true represents a positive sentiment, while a value of false represents negative sentiment.
        feedback:
          type: string
          description: An optional field for user input to describe the reason for their
            sentiment.
      required:
        - id
        - sentiment
    History:
      type: object
      properties:
        id:
          type: string
          description: |- 
            The "id" field in the response structure represents the unique identifier of the question that was answered.
            This identifier helps track which specific question the user's response corresponds to, ensuring the accuracy and continuity of the interactive session. It is used to maintain the sequence of interactions and to provide context for subsequent questions and answers.
        selected:
          type: integer
          description: |-
            The "selected" field represents the index of the chosen option from the multiple-choice answers provided for a specific question. 
            This is a 0-based index, meaning the first option is represented by 0, the second by 1, and so on.
            This field ensures that the system accurately records the user's choice and continues the interactive session based on the selected answer.
        assumed:
          type: boolean
          description: Identifies whether the API selected an answer to the corresponding question without having to explicitly ask it to the user. The value true means that the answer was assumed by the API, while false means that the answer was selected by the user.
          example: true
      required:
        - id
        - selected
        - assumed
    InteractiveResponse:
      type: object
      properties:
        newProductDescription:
          type: string
          description: An enhanced description generated for the product after processing product details.
        actualHts:
          type: string
          description: The Harmonized Tariff Schedule (HTS) code representing the currently provided "newProductDescription"
          example: "010121"
        suggestedHts:
          type: string
          description: The API's prediction for what the final Harmonized Tariff Schedule (HTS) code might be based on the current point of the session.
          example: "01012100"
        confidence:
          type: number
          description: A value between 0.00 and 1.00 representing the APIs likeliness for a suggestedHts to be the final HTS code. A value of 1.00 can also be interpreted as 100% confidence.
          minimum: 0.0
          maximum: 1.0
        noMoreQuestions:
          type: boolean
          description: This field will be marked as true when the API doesn't have any more questions to ask the user. In this case, the questions list will be empty and the most complete "actualHts" is provided.
          default: false
        questions:
          type: array
          items:
            $ref: "#/components/schemas/Question"
        session:
          $ref: "#/components/schemas/Session"
      required:
        - newProductDescription
        - session
    IterateRequest:
      type: object
      properties:
        questions:
          type: array
          items:
            $ref: "#/components/schemas/Answer"
      required:
        - questions
    Languages:
      type: string
      description: The language code following the ISO 639-1 standard.
      enum:
        - "EN"
    QuestionType:
      type: string
      enum:
        - multiple_choice
    Question:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of a question.
        type:
          description: The formatting of the question and how it should be presented to the user.
          $ref: "#/components/schemas/QuestionType"
        question:
          type: string
          description: A question asked by the API to help clarify and improve product description.
          maxLength: 2048
          example: "What is the intended use of your water bottle?"
        options:
          type: array
          description: A list representing the most common possible answers to a question.
          items:
            type: string
          example: ["For decorative purposes", "For storing or drinking water"]
        other:
          type: array
          description: |- 
            An extended list of "options". When a large list of potential options are generated by the API, uncommon options will be categorized into the "other" field. 
            For all intensive purposes, selecting an option from the other list should be treated as an indexable list as a continuation of options. For example, if "options" is a list of 5 items, selecting the first value from "other" would be index 5.
          items:
            type: string
          example: ["PET", "PPT"]
        selected:
          type: integer
          description: |-
            The "selected" field represents the index of the chosen option from the multiple-choice answers provided for a specific question. 
            This is a 0-based index, meaning the first option is represented by 0, the second by 1, and so on.
            This field ensures that the system accurately records the user's choice and continues the interactive session based on the selected answer.
        assumed:
          type: boolean
          description: Identifies whether the API selected an answer to the corresponding question without having to explicitly ask it to the user.
          default: false
      required:
        - id
        - question
        - options
    Session:
      type: object
      description: An object representing the user's session, a series of questions and selected answers.
      properties:
        id:
          type: string
          description: A unique identifier for representing the session belonging a user.
        historyDesc:
          type: array
          items:
            $ref: "#/components/schemas/History"
      required:
        - id
    StartRequest:
      type: object
      properties:
        importCountryCode:
          type: string
          description: The two-letter ISO 3166-1 alpha-2 country code representing the import country.
          $ref: "#/components/schemas/Countries"
          example: "US"
        exportCountryCode:
          type: string
          description: The two-letter ISO 3166-1 alpha-2 country code representing the export country.
          example: "US"
        commodityValue:
          type: string
          description: The declared value of the commodity for customs and trade purposes.
          example: "100.00"
        commodityCurrencyCode:
          type: string
          description: The three-letter currency code representing the currency in which the commodity value is expressed, according to the ISO 4217 standard.
          example: "USD"
        commodityQuantity:
          type: string
          description: The quantity of the commodity.
          example: "100"
        commodityUnitOfMeasure:
          type: string
          description: The unit of measure used for the commodity quantity.
          example: "ml"
        commodityDescription:
          type: string
          description: A brief description of the commodity, detailing its type and key characteristics.
          example: "Water Bottles"
        commodityHtsCode:
          type: string
          description: The commodityHtsCode is an optional field that allows the user to submit their known HTS classification. This will be used as a starting point for the interactive description guidance process.
          example: "0101"
        commodityCountryOfOrigin:
          type: string
          description: The two-letter ISO 3166-1 alpha-2 country code representing the country of origin of the commodity.
          example: "US"
        shipperName:
          type: string
          description: The name of the company or individual responsible for shipping the commodity.
          example: "Hardwood Floors LLC"
        shipperAccountNumber:
          type: string
          description: The account number representing the company or individual responsible for shipping the commodity.
          example: "10003KER50"
        locale:
          type: string
          description: The language the user uses to submit their initial product description. If the actual language used differs from this field, the application will throw an error as a "7015".
          allOf:
            - $ref: "#/components/schemas/Languages"
          default: "EN"
      required:
        - importCountryCode
        - commodityDescription
  securitySchemes:
    OAuth2:
      type: oauth2
      description: |
        Find your Client ID and Secret on your app info page. 
          1. Select "Try It" 
          2. In the Security section enter your Client ID and Secret 
          3. Select "Request Token"
          4. Enter any additional information in the Body and Parameters sections
          5. Select "Send" to execute your API request"
      flows:
        clientCredentials:
          x-tokenEndpointAuthMethod: client_secret_basic
          tokenUrl: https://wwwcie.ups.com/security/v1/oauth/token
          scopes: {}