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.

Text

Free-form text responses with character limits and validation

Editable Draft

Send a draft for the reviewer to revise before sending back

Single Select

Choose one option from a predefined list with labels

Multi Select

Choose multiple options with minimum/maximum selection limits

Rating

Numeric ratings with custom scales, steps, and labeled endpoints

Number

Numeric input with ranges, decimal places, and formatting

Text Response

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

Configuration

string

Placeholder text shown in the input field

integer

default:"0"

Minimum number of characters required

integer

required

Maximum number of characters allowed (1-5000)

boolean

default:"false"

Whether the response is required

Example Request

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
)

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

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:

{
  "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

string

required

The initial draft text that the reviewer will edit

string

Placeholder text shown in the editor

integer

default:"0"

Minimum characters required

integer

required

Maximum characters allowed (1-10000)

boolean

default:"false"

Whether a response is required

Example Request

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
)

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

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:

{
  "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

array

required

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

Show Simple Format

["Option 1", "Option 2", "Option 3"]

Automatically converted to rich SelectOption objects for mobile app compatibility.

Show Rich Format (SelectOption)

string

required

Internal value for the option (max 100 chars)

string

required

Display text for the option (max 200 chars)

boolean

default:"false"

Whether a selection is required

Example Request

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

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

{
  "response_data": "approve_with_warning"
}

Multi Select Response

Allow reviewers to choose multiple options from a predefined list.

Configuration

array

required

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

Show Simple Format

["Option 1", "Option 2", "Option 3"]

Automatically converted to rich SelectOption objects for mobile app compatibility.

Show Rich Format (SelectOption)

string

required

Internal value for the option (max 100 chars)

string

required

Display text for the option (max 200 chars)

integer

required

Maximum number of options that can be selected

integer

default:"1"

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

boolean

default:"false"

Whether at least one selection is required

Example Request

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

{
  "response_data": ["incorrect_address", "outdated_hours"]
}

Rating Response

Numeric rating scale with configurable range and step values.

Configuration

number

required

Maximum value of the rating scale

number

default:"1"

Minimum value of the rating scale (must be < scale_max)

number

default:"1"

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

boolean

default:"false"

Whether a rating is required

Example Request

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

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

{
  "response_data": 7.5
}

Number Response

Numeric input with validation and formatting options.

Configuration

number

required

Maximum allowed value

number

default:"1"

Minimum allowed value (must be < max_value)

integer

default:"2"

Number of decimal places allowed (0-10)

boolean

default:"false"

Whether negative numbers are allowed

boolean

default:"false"

Whether a value is required

Example Request

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

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

{
  "response_data": 299.99
}

Validation Rules

HITL.sh validates all responses against the configured rules:

Text Validation

Response must be a string
Length must be within min_length and max_length bounds
Required responses cannot be empty strings

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

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

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

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

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

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.

Single Select for Decisions

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

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.

Rating for Quality Assessment

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

Number for Quantitative Input

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

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

Keep Options Clear

Use descriptive labels and include helpful descriptions for select options. Consider adding colors for visual clarity.

Set Reasonable Limits

Configure appropriate min/max values, character limits, and selection bounds to prevent invalid or unusable responses.

Provide Good Defaults

Always specify meaningful default responses that represent the safest or most common expected outcome.

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:

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

Create Your First Request

Start using these response types in your requests

Mobile App Guide

See how reviewers interact with these response types

Webhooks

Set up webhooks to receive responses in real-time

Simple Integration

Learn how to integrate HITL.sh with practical examples

​Response Types

​Overview

Text

Editable Draft

Single Select

Multi Select

Rating

Number

​Text Response

​Configuration

​Example Request

​Response Format

​Editable Text Response

​Configuration

​Example Request

​Response Format

​Single Select Response

​Configuration

​Example Request

​Response Format

​Multi Select Response

​Configuration

​Example Request

​Response Format

​Rating Response

​Configuration

​Example Request

​Response Format

​Number Response

​Configuration

​Example Request

​Response Format

​Validation Rules

​Best Practices

​Choosing Response Types

​Configuration Tips

Keep Options Clear

Set Reasonable Limits

Provide Good Defaults

Consider Mobile UX

​Response Handling

​Next Steps

Create Your First Request

Mobile App Guide

Webhooks

Simple Integration

Response Types

Overview

Text Response

Configuration

Example Request

Response Format

Editable Text Response

Configuration

Example Request

Response Format

Single Select Response

Configuration

Example Request

Response Format

Multi Select Response

Configuration

Example Request

Response Format

Rating Response

Configuration

Example Request

Response Format

Number Response

Configuration

Example Request

Response Format

Validation Rules

Best Practices

Choosing Response Types

Configuration Tips

Response Handling

Next Steps