> ## 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 six 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.

> [card] Text
>
> Free-form text responses with character limits and validation

> [card] Editable Draft
>
> Send a draft for the reviewer to revise before sending back

> [card] Single Select
>
> Choose one option from a predefined list with labels

> [card] Multi Select
>
> Choose multiple options with minimum/maximum selection limits

> [card] Rating
>
> Numeric ratings with custom scales, steps, and labeled endpoints

> [card] Number
>
> Numeric input with ranges, decimal places, and formatting

## Text Response

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

### Configuration

**placeholder** `string`

Placeholder text shown in the input field

**min\_length** `integer` (default: 0)

Minimum number of characters required

**max\_length** `integer` *required*

Maximum number of characters allowed (1-5000)

**required** `boolean` (default: false)

Whether the response is required

### Example Request

```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"
  }'
```

### 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."
}
```

## Editable Text Response

Send a draft message for the reviewer to edit and revise before sending back. Perfect for AI-generated notifications, emails, or messages that need human polish.

### Configuration

**draft\_text** `string` *required*

The initial draft text that the reviewer will edit

**placeholder** `string`

Placeholder text shown in the editor

**min\_length** `integer` (default: 0)

Minimum characters required

**max\_length** `integer` *required*

Maximum characters allowed (1-10000)

**required** `boolean` (default: false)

Whether a response is required

### Example Request

```python Python theme={null}
import requests

request_data = {
    "processing_type": "time-sensitive",
    "type": "markdown",
    "priority": "medium",
    "request_text": "Please review and edit this AI-generated client notification before it is sent.",
    "response_type": "editable_text",
    "response_config": {
        "draft_text": "Dear Client,\n\nYour project milestone has been completed ahead of schedule. Our team will reach out shortly to discuss next steps.\n\nBest regards,\nThe Team",
        "placeholder": "Edit the message above...",
        "min_length": 20,
        "max_length": 2000,
        "required": True
    },
    "default_response": "Notification not reviewed 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 and edit this AI-generated client notification before it is sent.",
    response_type: "editable_text",
    response_config: {
        draft_text: "Dear Client,\n\nYour project milestone has been completed ahead of schedule. Our team will reach out shortly to discuss next steps.\n\nBest regards,\nThe Team",
        placeholder: "Edit the message above...",
        min_length: 20,
        max_length: 2000,
        required: true
    },
    default_response: "Notification not reviewed 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 and edit this AI-generated client notification before it is sent.",
    "response_type": "editable_text",
    "response_config": {
        "draft_text": "Dear Client,\n\nYour project milestone has been completed ahead of schedule. Our team will reach out shortly to discuss next steps.\n\nBest regards,\nThe Team",
        "placeholder": "Edit the message above...",
        "min_length": 20,
        "max_length": 2000,
        "required": true
    },
    "default_response": "Notification not reviewed within timeout period",
    "timeout_seconds": 3600,
    "platform": "api"
  }'
```

### Response Format

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

```json theme={null}
{
  "response_data": {
    "revised_text": "Dear Client,\n\nGreat news — your project milestone has been completed two days ahead of schedule! We will be in touch by end of day to walk you through the next phase.\n\nWarm regards,\nThe Team",
    "was_edited": true
  }
}
```

## Single Select Response

Allow reviewers to choose one option from a predefined list.

### Configuration

**options** `array` *required*

Array of options (1-20 options max). Can be simple strings or SelectOption objects.

**Simple Format**

```json theme={null}
["Option 1", "Option 2", "Option 3"]
```

Automatically converted to rich SelectOption objects for mobile app compatibility.

**Rich Format (SelectOption)**

**value** `string` *required*

Internal value for the option (max 100 chars)

**label** `string` *required*

Display text for the option (max 200 chars)

**required** `boolean` (default: false)

Whether a selection is required

### Example Request

```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"
};
```

### Response Format

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

## Multi Select Response

Allow reviewers to choose multiple options from a predefined list.

### Configuration

**options** `array` *required*

Array of options (1-20 options max). Can be simple strings or SelectOption objects.

**Simple Format**

```json theme={null}
["Option 1", "Option 2", "Option 3"]
```

Automatically converted to rich SelectOption objects for mobile app compatibility.

**Rich Format (SelectOption)**

**value** `string` *required*

Internal value for the option (max 100 chars)

**label** `string` *required*

Display text for the option (max 200 chars)

**max\_selections** `integer` *required*

Maximum number of options that can be selected

**min\_selections** `integer` (default: 1)

Minimum number of options that must be selected (auto-added when max\_selections is provided)

**required** `boolean` (default: false)

Whether at least one selection is required

### Example Request

```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"
}
```

### Response Format

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

## Rating Response

Numeric rating scale with configurable range and step values.

### Configuration

**scale\_max** `number` *required*

Maximum value of the rating scale

**scale\_min** `number` (default: 1)

Minimum value of the rating scale (must be \< scale\_max)

**scale\_step** `number` (default: 1)

Step increment for the rating scale (e.g., 0.5 for half-star ratings, 1 for full-star ratings)

**required** `boolean` (default: false)

Whether a rating is required

### Example Request

```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"
};
```

### Response Format

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

## Number Response

Numeric input with validation and formatting options.

### Configuration

**max\_value** `number` *required*

Maximum allowed value

**min\_value** `number` (default: 1)

Minimum allowed value (must be \< max\_value)

**decimal\_places** `integer` (default: 2)

Number of decimal places allowed (0-10)

**allow\_negative** `boolean` (default: false)

Whether negative numbers are allowed

**required** `boolean` (default: false)

Whether a value is required

### Example Request

```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"
};
```

### Response Format

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

## Validation Rules

HITL.sh validates all responses against the configured rules:

> [accordion] Text Validation
>
> * Response must be a string
> * Length must be within min\_length and max\_length bounds
> * Required responses cannot be empty strings

> [accordion] 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] 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] 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] 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] Editable Text Validation
>
> * Response must be an object containing `revised_text` (string) and `was_edited` (boolean)
> * `revised_text` length must be within min\_length and max\_length bounds
> * Required responses cannot have an empty `revised_text`
> * `max_length` must be between 1 and 10000

## Best Practices

### Choosing Response Types

**1. 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.

**2. Single Select for Decisions**

Use single select for clear decisions with mutually exclusive options. Perfect for approval workflows, categorization, and status assignments.

**3. 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.

**4. Rating for Quality Assessment**

Use ratings for quantitative assessments where you need to measure quality, satisfaction, confidence levels, or performance on a scale.

**5. Number for Quantitative Input**

Use number responses for pricing, quantities, measurements, or any numeric data that needs validation and formatting.

**6. Editable Text for Human Polish**

Use editable text when you have AI-generated drafts — emails, notifications, or messages — that need a human to refine the tone, accuracy, or wording before delivery.

### Configuration Tips

> [card] Keep Options Clear
>
> Use descriptive labels and include helpful descriptions for select options. Consider adding colors for visual clarity.

> [card] Set Reasonable Limits
>
> Configure appropriate min/max values, character limits, and selection bounds to prevent invalid or unusable responses.

> [card] Provide Good Defaults
>
> Always specify meaningful default responses that represent the safest or most common expected outcome.

> [card] Consider Mobile UX
>
> Remember that reviewers will interact with these response types on mobile devices. Keep options concise and touch-friendly.

### 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)

    elif response_type == "editable_text":
        revised_text = response_data["revised_text"]
        was_edited = response_data["was_edited"]
        send_client_notification(revised_text)
        if was_edited:
            log_human_revision(request_id, revised_text)
```

## Next Steps

> [card] [Create Your First Request](https://docs.hitl.sh/api-reference/requests/create-request.md)
>
> Start using these response types in your requests

> [card] [Mobile App Guide](https://docs.hitl.sh/mobile/responding.md)
>
> See how reviewers interact with these response types

> [card] [Webhooks](https://docs.hitl.sh/api-reference/webhooks.md)
>
> Set up webhooks to receive responses in real-time

> [card] [Simple Integration](https://docs.hitl.sh/guides/simple-integration.md)
>
> Learn how to integrate HITL.sh with practical examples


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.