> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitl.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Response Types

> Complete guide to all response types supported by HITL.sh - from simple text to complex ratings and multi-select options

# Response Types

HITL.sh supports five different response types that allow reviewers to provide structured feedback. Each response type has its own configuration options and validation rules, giving you flexibility to design the perfect review experience for your use case.

## Overview

When creating a request, you specify the `response_type` and `response_config` to define how reviewers will respond. The response type determines the UI reviewers see in the mobile app and how their responses are structured and validated.

<CardGroup cols={3}>
  <Card title="Text" icon="message">
    Free-form text responses with character limits and validation
  </Card>

  <Card title="Single Select" icon="circle-dot">
    Choose one option from a predefined list with labels
  </Card>

  <Card title="Multi Select" icon="check-square">
    Choose multiple options with minimum/maximum selection limits
  </Card>

  <Card title="Rating" icon="star">
    Numeric ratings with custom scales, steps, and labeled endpoints
  </Card>

  <Card title="Number" icon="hashtag">
    Numeric input with ranges, decimal places, and formatting
  </Card>
</CardGroup>

## Text Response

Free-form text input allowing reviewers to provide detailed written feedback.

### Configuration

<ParamField body="placeholder" type="string" optional>
  Placeholder text shown in the input field
</ParamField>

<ParamField body="min_length" type="integer" optional default="0">
  Minimum number of characters required
</ParamField>

<ParamField body="max_length" type="integer" required>
  Maximum number of characters allowed (1-5000)
</ParamField>

<ParamField body="required" type="boolean" optional default="false">
  Whether the response is required
</ParamField>

### Example Request

<CodeGroup>
  ```python Python theme={null}
  import requests

  request_data = {
      "processing_type": "time-sensitive",
      "type": "markdown", 
      "priority": "medium",
      "request_text": "Please review this article and provide detailed feedback on accuracy and tone.",
      "response_type": "text",
      "response_config": {
          "placeholder": "Provide your detailed feedback here...",
          "min_length": 50,
          "max_length": 1000,
          "required": True
      },
      "default_response": "No feedback provided within timeout period",
      "timeout_seconds": 3600,
      "platform": "api"
  }

  response = requests.post(
      f"https://api.hitl.sh/v1/api/loops/{loop_id}/requests",
      headers={"Authorization": f"Bearer {api_key}"},
      json=request_data
  )
  ```

  ```javascript Node.js theme={null}
  const requestData = {
      processing_type: "time-sensitive",
      type: "markdown",
      priority: "medium", 
      request_text: "Please review this article and provide detailed feedback on accuracy and tone.",
      response_type: "text",
      response_config: {
          placeholder: "Provide your detailed feedback here...",
          min_length: 50,
          max_length: 1000,
          required: true
      },
      default_response: "No feedback provided within timeout period",
      timeout_seconds: 3600,
      platform: "api"
  };

  const response = await axios.post(
      `https://api.hitl.sh/v1/api/loops/${loopId}/requests`,
      requestData,
      { headers: { Authorization: `Bearer ${apiKey}` }}
  );
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.hitl.sh/v1/api/loops/{loop_id}/requests \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "processing_type": "time-sensitive",
      "type": "markdown",
      "priority": "medium",
      "request_text": "Please review this article and provide detailed feedback on accuracy and tone.",
      "response_type": "text", 
      "response_config": {
          "placeholder": "Provide your detailed feedback here...",
          "min_length": 50,
          "max_length": 1000,
          "required": true
      },
      "default_response": "No feedback provided within timeout period",
      "timeout_seconds": 3600,
      "platform": "api"
    }'
  ```
</CodeGroup>

### Response Format

When a reviewer submits a text response, you'll receive:

```json theme={null}
{
  "response_data": "This article is well-written and factually accurate. The tone is professional and engaging. I recommend approval with minor grammar corrections on paragraph 3."
}
```

## Single Select Response

Allow reviewers to choose one option from a predefined list.

### Configuration

<ParamField body="options" type="array" required>
  Array of options (1-20 options max). Can be simple strings or SelectOption objects.

  <Expandable title="Simple Format">
    ```json theme={null}
    ["Option 1", "Option 2", "Option 3"]
    ```

    Automatically converted to rich SelectOption objects for mobile app compatibility.
  </Expandable>

  <Expandable title="Rich Format (SelectOption)">
    <ParamField body="value" type="string" required>
      Internal value for the option (max 100 chars)
    </ParamField>

    <ParamField body="label" type="string" required>
      Display text for the option (max 200 chars)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="required" type="boolean" optional default="false">
  Whether a selection is required
</ParamField>

### Example Request

<CodeGroup>
  ```python Python theme={null}
  request_data = {
      "processing_type": "time-sensitive",
      "type": "markdown",
      "priority": "high",
      "request_text": "Please review this user comment for community guideline compliance:",
      "response_type": "single_select",
      "response_config": {
          "options": [
              "Approve",
              "Approve with Warning",
              "Reject",
              "Escalate"
          ]
      },
      "default_response": "reject",
      "timeout_seconds": 1800,
      "platform": "api"
  }
  ```

  ```javascript Node.js theme={null}
  const requestData = {
      processing_type: "time-sensitive",
      type: "markdown", 
      priority: "high",
      request_text: "Please review this user comment for community guideline compliance:",
      response_type: "single_select",
      response_config: {
          options: [
              "Approve",
              "Approve with Warning",
              "Reject",
              "Escalate"
          ]
      },
      default_response: "reject",
      timeout_seconds: 1800,
      platform: "api"
  };
  ```
</CodeGroup>

### Response Format

```json theme={null}
{
  "response_data": "approve_with_warning"
}
```

## Multi Select Response

Allow reviewers to choose multiple options from a predefined list.

### Configuration

<ParamField body="options" type="array" required>
  Array of options (1-20 options max). Can be simple strings or SelectOption objects.

  <Expandable title="Simple Format">
    ```json theme={null}
    ["Option 1", "Option 2", "Option 3"]
    ```

    Automatically converted to rich SelectOption objects for mobile app compatibility.
  </Expandable>

  <Expandable title="Rich Format (SelectOption)">
    <ParamField body="value" type="string" required>
      Internal value for the option (max 100 chars)
    </ParamField>

    <ParamField body="label" type="string" required>
      Display text for the option (max 200 chars)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="max_selections" type="integer" required>
  Maximum number of options that can be selected
</ParamField>

<ParamField body="min_selections" type="integer" optional default="1">
  Minimum number of options that must be selected (auto-added when max\_selections is provided)
</ParamField>

<ParamField body="required" type="boolean" optional default="false">
  Whether at least one selection is required
</ParamField>

### Example Request

<CodeGroup>
  ```python Python theme={null}
  request_data = {
      "processing_type": "time-sensitive",
      "type": "markdown",
      "priority": "medium",
      "request_text": "What issues do you see in this business listing? Select all that apply:",
      "response_type": "multi_select",
      "response_config": {
          "options": [
              "Incorrect Address",
              "Wrong Phone Number",
              "Outdated Hours",
              "Poor Quality Photos",
              "Duplicate Listing",
              "No Issues Found"
          ],
          "max_selections": 5
      },
      "default_response": [],
      "timeout_seconds": 2400,
      "platform": "api"
  }
  ```
</CodeGroup>

### Response Format

```json theme={null}
{
  "response_data": ["incorrect_address", "outdated_hours"]
}
```

## Rating Response

Numeric rating scale with configurable range and step values.

### Configuration

<ParamField body="scale_max" type="number" required>
  Maximum value of the rating scale
</ParamField>

<ParamField body="scale_min" type="number" optional default="1">
  Minimum value of the rating scale (must be \< scale\_max)
</ParamField>

<ParamField body="scale_step" type="number" optional default="1">
  Step increment for the rating scale (e.g., 0.5 for half-star ratings, 1 for full-star ratings)
</ParamField>

<ParamField body="required" type="boolean" optional default="false">
  Whether a rating is required
</ParamField>

### Example Request

<CodeGroup>
  ```python Python theme={null}
  request_data = {
      "processing_type": "time-sensitive",
      "type": "markdown",
      "priority": "medium", 
      "request_text": "Please rate the quality of this AI-generated content on a scale of 1-10:",
      "response_type": "rating",
      "response_config": {
          "scale_min": 1,
          "scale_max": 10,
          "scale_step": 0.5,
          "required": true
      },
      "default_response": 5,
      "timeout_seconds": 1800,
      "platform": "api"
  }
  ```

  ```javascript Node.js theme={null}
  const requestData = {
      processing_type: "time-sensitive",
      type: "markdown",
      priority: "medium",
      request_text: "Please rate the quality of this AI-generated content on a scale of 1-10:",
      response_type: "rating",
      response_config: {
          scale_min: 1,
          scale_max: 10, 
          scale_step: 0.5,
          required: true
      },
      default_response: 5,
      timeout_seconds: 1800,
      platform: "api"
  };
  ```
</CodeGroup>

### Response Format

```json theme={null}
{
  "response_data": 7.5
}
```

## Number Response

Numeric input with validation and formatting options.

### Configuration

<ParamField body="max_value" type="number" required>
  Maximum allowed value
</ParamField>

<ParamField body="min_value" type="number" optional default="1">
  Minimum allowed value (must be \< max\_value)
</ParamField>

<ParamField body="decimal_places" type="integer" optional default="2">
  Number of decimal places allowed (0-10)
</ParamField>

<ParamField body="allow_negative" type="boolean" optional default="false">
  Whether negative numbers are allowed
</ParamField>

<ParamField body="required" type="boolean" optional default="false">
  Whether a value is required
</ParamField>

### Example Request

<CodeGroup>
  ```python Python theme={null}
  request_data = {
      "processing_type": "time-sensitive", 
      "type": "markdown",
      "priority": "medium",
      "request_text": "What's a fair market price for this product based on your expertise?",
      "response_type": "number",
      "response_config": {
          "max_value": 10000,
          # min_value defaults to 1
          # decimal_places defaults to 2  
          # allow_negative defaults to false
          # required defaults to false
      },
      "default_response": 50,
      "timeout_seconds": 2400,
      "platform": "api"
  }
  ```

  ```javascript Node.js theme={null}
  const requestData = {
      processing_type: "time-sensitive",
      type: "markdown", 
      priority: "medium",
      request_text: "What's a fair market price for this product based on your expertise?",
      response_type: "number",
      response_config: {
          max_value: 10000,
          // min_value defaults to 1
          // decimal_places defaults to 2  
          // allow_negative defaults to false
          // required defaults to false
      },
      default_response: 50,
      timeout_seconds: 2400,
      platform: "api"
  };
  ```
</CodeGroup>

### Response Format

```json theme={null}
{
  "response_data": 299.99
}
```

## Validation Rules

HITL.sh validates all responses against the configured rules:

<AccordionGroup>
  <Accordion title="Text Validation">
    * Response must be a string
    * Length must be within min\_length and max\_length bounds
    * Required responses cannot be empty strings
  </Accordion>

  <Accordion title="Single Select Validation">
    * Response must be a valid option value from the options array
    * Required responses must include a selection
    * Only one option can be selected
  </Accordion>

  <Accordion title="Multi Select Validation">
    * All selected values must be valid options from the options array
    * Number of selections must be within min\_selections and max\_selections bounds
    * No duplicate selections allowed
  </Accordion>

  <Accordion title="Rating Validation">
    * Response must be a number within scale\_min and scale\_max bounds
    * Value must align with scale\_step increments (e.g., only .0 and .5 for step=0.5)
    * Required ratings cannot be null
  </Accordion>

  <Accordion title="Number Validation">
    * Response must be a number within min\_value and max\_value bounds
    * Decimal places must not exceed configured decimal\_places
    * Negative numbers only allowed if allow\_negative is true
  </Accordion>
</AccordionGroup>

## Best Practices

### Choosing Response Types

<Steps>
  <Step title="Text for Complex Feedback">
    Use text responses when you need detailed explanations, qualitative feedback, or open-ended input that can't be captured in predefined options.
  </Step>

  <Step title="Single Select for Decisions">
    Use single select for clear decisions with mutually exclusive options. Perfect for approval workflows, categorization, and status assignments.
  </Step>

  <Step title="Multi Select for Categorization">
    Use multi select when multiple aspects need to be evaluated simultaneously, such as content issues, feature requests, or compliance checklist items.
  </Step>

  <Step title="Rating for Quality Assessment">
    Use ratings for quantitative assessments where you need to measure quality, satisfaction, confidence levels, or performance on a scale.
  </Step>

  <Step title="Number for Quantitative Input">
    Use number responses for pricing, quantities, measurements, or any numeric data that needs validation and formatting.
  </Step>
</Steps>

### Configuration Tips

<CardGroup cols={2}>
  <Card title="Keep Options Clear" icon="eye">
    Use descriptive labels and include helpful descriptions for select options. Consider adding colors for visual clarity.
  </Card>

  <Card title="Set Reasonable Limits" icon="shield-check">
    Configure appropriate min/max values, character limits, and selection bounds to prevent invalid or unusable responses.
  </Card>

  <Card title="Provide Good Defaults" icon="settings">
    Always specify meaningful default responses that represent the safest or most common expected outcome.
  </Card>

  <Card title="Consider Mobile UX" icon="mobile">
    Remember that reviewers will interact with these response types on mobile devices. Keep options concise and touch-friendly.
  </Card>
</CardGroup>

### Response Handling

When processing responses in your application:

```python theme={null}
def handle_response(request_id, response_data, response_type):
    """Handle different response types appropriately"""
    
    if response_type == "text":
        text = response_data
        # Process free-form text feedback
        analyze_sentiment(text)
        extract_keywords(text)
        
    elif response_type == "single_select":
        selected = response_data
        if selected == "approve":
            approve_content()
        elif selected == "reject":
            reject_content()
        elif selected == "escalate":
            escalate_to_senior_reviewer()

    elif response_type == "multi_select":
        issues = response_data
        for issue in issues:
            handle_identified_issue(issue)

    elif response_type == "rating":
        score = response_data
        if score >= 8:
            mark_as_high_quality()
        elif score <= 3:
            flag_for_improvement()

    elif response_type == "number":
        value = response_data
        update_pricing_model(request_id, value)
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Your First Request" icon="rocket" href="/api-reference/requests/create-request">
    Start using these response types in your requests
  </Card>

  <Card title="Mobile App Guide" icon="mobile" href="/mobile/responding">
    See how reviewers interact with these response types
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks">
    Set up webhooks to receive responses in real-time
  </Card>

  <Card title="Simple Integration" icon="puzzle" href="/guides/simple-integration">
    Learn how to integrate HITL.sh with practical examples
  </Card>
</CardGroup>