Simple Feedback API

Introduction

This project is designed to help you quickly add straightforward feedback forms to your MVPs and gather user input with minimal fuss. I hope it makes your development process smoother and saves you time.
Best, @gus

Why Simple Feedback API?

• No Third-Party Dependencies: Keep your data under your control
• MVP-Friendly: Perfect for testing ideas and gathering user feedback
• Developer-First: Simple REST API that integrates with any tech stack
• Lightweight: Minimal setup, maximum functionality

Quick Start

1. Generate an API key from your dashboard
2. Include the API key in your requests using the `X-API-Key` header
3. Make requests to our endpoints
4. Collect feedback and iterate on your ideas

Quick Guide

Creating a Form

1. Go to the Dashboard and select Forms.
2. Click Create Form.
3. Fill in the required fields:

• Title (at least 3 characters)
• Description (optional)
• URL Slug (auto-generated)

4. Add your desired form fields.
5. Note: Only forms with “Public” status can receive responses.

---

Where to Find Your API Key

To get your API key

1. Go to the API Keys section in the dashboard.
2. Click Create API Key to generate a new key, or view your existing keys.
3. When creating a new key, copy it immediately—it will only be shown once.
4. Use this API key for integrations or automating survey submissions.

---

Quick Tips

• ✅ Make forms public before expecting responses
• 📊 Check results dashboard regularly for new submissions
• 🔑 Keep API keys secure and rotate periodically

Getting Started

Prerequisites

• Active platform account
• API key from your dashboard
• Survey form with at least one question

Generate API Key

1. Login to dashboard → API Keys → Generate New API Key
2. Copy and store securely

⚠️ Keep your API key secure. Never expose in client-side code.

Submit Form Response

Request Structure

• form_id: Unique form identifier
• respondent: Submitter information (email, name, etc.)
• field_responses: Array of field answers

Example Request

curl -X POST "https://api.poketto.dev/api/v1/forms/submit/{{FORM_ID}}"
  -H "X-API-Key: {{API_KEY}}"
  -H "Content-Type: application/json"
  -d '{
    "respondent": {
      "email": "httptest1@poketto.dev",
      "name": "Test Doe",
      {other_optional_fields}
    },
    "field_responses": [
      {
        "field_id": "38261edc-8bff-4b7e-9f15-1ea11a839927",
        "value": 5
      },
      ...
    ]
  }'

Step 3: Handle the Response

The API will return a JSON response indicating success or failure:

{
  "success": true,
  "data": {
    "message": "Form response submitted successfully",
    "responseId": "bffa3a68-45ef-4536-add8-c6bf545789b5"
  },
  "timestamp": 1749080835
}

Optional Respondent Fields

"respondent": {
  "email": "httptest1@poketto.dev",
  "name": "Test Doe",
  "browser": "Chrome",
  "browser_version": "120.0.6099.109",
  "os": "macOS",
  "os_version": "14.2.1",
  "device_type": "Desktop",
  "device_model": "MacBook Pro",
  "screen_resolution": "1920x1080",
  "source": "google",
  "medium": "organic",
  "campaign": "holiday_2024",
  "utm_source": "google",
  "utm_medium": "cpc",
  "utm_campaign": "winter_sale",
  "utm_term": "best_products",
  "utm_content": "ad_variant_a",
  "referrer_url": "https://www.google.com/search?q=best+products",
  "country": "United States",
  "region": "California",
  "city": "San Francisco",
  "ip_address": "192.168.1.100",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
  "language": "en-US",
  "timezone": "America/New_York"
}

Viewing Survey Results

To view survey results

1. Open the Forms list in the dashboard.
2. Click on the title of the form you want to review.
3. The form details page will show all collected responses and summary statistics.
4. You can inspect individual responses and export results if needed.

Submit Form Response API

Submit a response to a specific form with optional respondent tracking data. This endpoint requires an API key and ensures the form belongs to the same organization as the API key.

---

Endpoint

POST https://api.poketto.dev/api/v1/forms/{formId}/submit-response

Authentication

• Header: X-API-Key (required)
• Alternative: Authorization: Bearer {API_KEY} (deprecated, use X-API-Key instead)

Request Body

Basic Example

{
  "respondent": {
    "email": "user@example.com",
    "name": "John Doe",
    "browser": "Chrome",
    "os": "Windows",
    "source": "website"
  },
  "field_responses": [
    {
      "field_id": "38261edc-8bff-4b7e-9f15-1ea11a839927",
      "value": "5"
    },
    {
      "field_id": "1138820b-716f-4705-b43e-7553f82187f6",
      "value": "The service was excellent!"
    }
  ]
}

Required Fields

• field_responses (array): Array of field responses
  • field_id (string): UUID of the form field
  • value (string, optional): Response value (max 4000 characters)

Optional Respondent Fields

Basic Information

• email (string): Valid email address
• name (string): Respondent name (max 255 characters)
• metadata (object): Custom metadata (max 64KB JSON)

Device & Browser Information

• browser (string): Browser name (max 50 characters)
• browser_version (string): Browser version (max 50 characters)
• os (string): Operating system (max 50 characters)
• os_version (string): OS version (max 50 characters)
• device_type (string): Device type (max 50 characters)
• device_model (string): Device model (max 100 characters)
• screen_resolution (string): Format "WIDTHxHEIGHT" (e.g., "1920x1080")
• user_agent (string): User agent string (max 500 characters)

Marketing & Analytics

• source (string): Traffic source (max 255 characters)
• medium (string): Traffic medium (max 255 characters)
• campaign (string): Campaign name (max 255 characters)
• utm_source (string): UTM source parameter (max 255 characters)
• utm_medium (string): UTM medium parameter (max 255 characters)
• utm_campaign (string): UTM campaign parameter (max 255 characters)
• utm_term (string): UTM term parameter (max 255 characters)
• utm_content (string): UTM content parameter (max 255 characters)
• referrer_url (string): Referrer URL (max 2048 characters)

Location & Locale

• country (string): Country name (max 100 characters)
• region (string): Region/state name (max 100 characters)
• city (string): City name (max 100 characters)
• ip_address (string): IPv4 or IPv6 address
• language (string): ISO 639-1 language code (e.g., "en", "es", "en-US")
• timezone (string): Timezone identifier (max 50 characters)

Response

Success Response (201 Created)

{
  "success": true,
  "data": {
    "message": "Form response submitted successfully",
    "responseId": "uuid-of-created-response"
  },
  "timestamp": 1234567890
}

Error Responses

400 Bad Request

{
  "success": false,
  "data": {
    "error": "Missing required fields"
  },
  "timestamp": 1234567890
}

401 Unauthorized

{
  "success": false,
  "data": {
    "error": "Missing API key. Please provide it in the X-API-Key header."
  },
  "timestamp": 1234567890
}

403 Forbidden

{
  "success": false,
  "data": {
    "error": "Unauthorized: API key cannot access this form"
  },
  "timestamp": 1234567890
}

405 Method Not Allowed

{
  "success": false,
  "data": {
    "error": "Method not allowed"
  },
  "timestamp": 1234567890
}

Validation Rules

• Email addresses must follow standard email format
• URLs must be valid HTTP/HTTPS URLs
• IP addresses support both IPv4 and IPv6 formats
• Screen resolution must be in "WIDTHxHEIGHT" format
• Language codes must follow ISO 639-1 standard
• All text fields are sanitized to remove potentially dangerous characters
• Field response values are limited to 4000 characters each
• Respondent metadata is limited to 64KB when serialized as JSON