Skip to Content
API Reference

API Reference

Complete reference for the kollect API.

Table of Contents

  1. Form Submission API
  2. Management API
  3. Authentication
  4. Rate Limits
  5. Error Codes

Form Submission API

Submit Form Data

Submit data to a kollect form endpoint.

Endpoint:

POST https://kollect.app/f/{FORM_KEY}

Content Types:

  • application/x-www-form-urlencoded (standard HTML forms)
  • multipart/form-data (file uploads)
  • application/json (AJAX requests)

Basic Request

curl -X POST https://kollect.app/f/abc123xyz \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "email=user@example.com&message=Hello"

JSON Request

curl -X POST https://kollect.app/f/abc123xyz \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "message": "Hello"}'

Response

Success (200 OK):

{
  "success": true,
  "message": "Form submitted successfully"
}

Error (400 Bad Request):

{
  "error": "Form is disabled"
}

Error (403 Forbidden):

{
  "error": "Origin not whitelisted"
}

Special Form Fields

Certain field names have special behavior:

Field NamePurposeExample
_redirect_urlRedirect URL after submissionhttps://yoursite.com/thanks
_gotchaHoneypot field (default name)Leave empty (hidden field)

Note: The honeypot field name can be customized in form settings.

CORS Headers

All form endpoints include CORS headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Content-Type

This allows submissions from any domain by default. Use origin whitelisting to restrict access.

Management API

The Management API allows programmatic access to forms and submissions.

Base URL:

https://kollect.app/api

Authentication

All management API requests require authentication using a Bearer token.

curl -X GET https://kollect.app/api/forms \
  -H "Authorization: Bearer YOUR_API_KEY"

Get API Key: API keys are available in your account settings (coming soon).

Forms API

List All Forms

Get all forms for the authenticated user/organization.

Endpoint:

GET /api/forms

Response:

{
  "forms": [
    {
      "id": "abc123xyz",
      "name": "Contact Form",
      "enabled": true,
      "createdAt": "2025-01-15T10:30:00Z",
      "submissionCount": 42
    }
  ]
}

Create Form

Create a new form.

Endpoint:

POST /api/forms

Request Body:

{
  "name": "Contact Form",
  "redirectUrl": "https://example.com/thank-you",
  "honeypotField": "_gotcha",
  "originWhitelist": ["https://example.com"]
}

Response:

{
  "id": "abc123xyz",
  "name": "Contact Form",
  "endpoint": "https://kollect.app/f/abc123xyz",
  "createdAt": "2025-01-15T10:30:00Z"
}

Get Form Details

Get detailed information about a specific form.

Endpoint:

GET /api/forms/{FORM_ID}

Response:

{
  "id": "abc123xyz",
  "name": "Contact Form",
  "enabled": true,
  "settings": {
    "redirectUrl": "https://example.com/thank-you",
    "honeypotField": "_gotcha",
    "originWhitelist": ["https://example.com"]
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-16T14:20:00Z"
}

Update Form

Update form settings.

Endpoint:

PATCH /api/forms/{FORM_ID}

Request Body:

{
  "name": "Updated Contact Form",
  "enabled": true,
  "redirectUrl": "https://example.com/success"
}

Response:

{
  "id": "abc123xyz",
  "name": "Updated Contact Form",
  "enabled": true,
  "updatedAt": "2025-01-16T15:00:00Z"
}

Delete Form

Delete a form and all its submissions.

Endpoint:

DELETE /api/forms/{FORM_ID}

Response:

{
  "success": true,
  "message": "Form deleted successfully"
}

Note: This action is permanent and will delete all associated submissions.

Submissions API

List Submissions

Get submissions for a specific form.

Endpoint:

GET /api/forms/{FORM_ID}/submissions

Query Parameters:

ParameterTypeDescription
limitnumberNumber of submissions to return (default: 50, max: 100)
offsetnumberPagination offset (default: 0)
fromISO dateFilter submissions after this date
toISO dateFilter submissions before this date

Example:

curl -X GET "https://kollect.app/api/forms/abc123xyz/submissions?limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "submissions": [
    {
      "id": "sub_123",
      "formId": "abc123xyz",
      "data": {
        "email": "user@example.com",
        "message": "Hello"
      },
      "metadata": {
        "origin": "https://example.com",
        "userAgent": "Mozilla/5.0...",
        "ip": "192.168.1.1"
      },
      "createdAt": "2025-01-16T09:15:00Z"
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

Get Single Submission

Get details of a specific submission.

Endpoint:

GET /api/forms/{FORM_ID}/submissions/{SUBMISSION_ID}

Response:

{
  "id": "sub_123",
  "formId": "abc123xyz",
  "data": {
    "email": "user@example.com",
    "message": "Hello",
    "name": "John Doe"
  },
  "metadata": {
    "origin": "https://example.com",
    "userAgent": "Mozilla/5.0...",
    "ip": "192.168.1.1"
  },
  "createdAt": "2025-01-16T09:15:00Z"
}

Export Submissions

Export submissions in CSV or JSON format.

Endpoint:

GET /api/forms/{FORM_ID}/submissions/export

Query Parameters:

ParameterTypeDescription
formatstringExport format: csv or json (default: csv)
fromISO dateFilter submissions after this date
toISO dateFilter submissions before this date

Example:

curl -X GET "https://kollect.app/api/forms/abc123xyz/submissions/export?format=csv" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o submissions.csv

Authentication

API Keys

API keys provide programmatic access to the Management API.

Creating API Keys:

  1. Navigate to Account Settings
  2. Click “API Keys”
  3. Click “Generate New Key”
  4. Copy and securely store your key

Using API Keys:

curl -X GET https://kollect.app/api/forms \
  -H "Authorization: Bearer sk_live_abc123xyz..."

Security:

  • Never commit API keys to version control
  • Rotate keys regularly
  • Use different keys for different environments
  • Revoke compromised keys immediately

Session Authentication

Dashboard access uses Clerk session authentication. This is handled automatically by the UI.

Rate Limits

Rate limits protect the API from abuse.

Form Submissions

PlanLimit
Free100 submissions/month
Starter1,000 submissions/month
Professional10,000 submissions/month

API Requests

Endpoint TypeLimit
Form Submissions60 requests/minute per form
Management API100 requests/minute per API key

Rate Limit Headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1642348800

Rate Limit Exceeded (429):

{
  "error": "Rate limit exceeded",
  "retryAfter": 30
}

Error Codes

HTTP Status Codes

CodeMeaningDescription
200OKRequest successful
400Bad RequestInvalid request data
401UnauthorizedMissing or invalid authentication
403ForbiddenInsufficient permissions
404Not FoundResource not found
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer error

Error Response Format

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {
    "field": "Additional context"
  }
}

Common Error Codes

CodeDescription
FORM_DISABLEDForm is currently disabled
ORIGIN_NOT_WHITELISTEDRequest origin not allowed
HONEYPOT_TRIGGEREDSpam protection triggered
PLAN_LIMIT_REACHEDSubmission quota exceeded
INVALID_FORM_KEYForm key not found
VALIDATION_ERRORRequest validation failed

Webhooks

Send form submissions to external endpoints (coming soon).

Webhook Events

  • submission.created - New form submission
  • submission.spam - Spam submission detected

Webhook Payload

{
  "event": "submission.created",
  "formId": "abc123xyz",
  "formName": "Contact Form",
  "submission": {
    "id": "sub_123",
    "data": {
      "email": "user@example.com",
      "message": "Hello"
    },
    "createdAt": "2025-01-16T09:15:00Z"
  }
}

Webhook Signature

Webhooks include a signature header for verification:

X-Kollect-Signature: sha256=abc123...

SDK Libraries

Official SDK libraries (coming soon):

  • JavaScript/TypeScript
  • Python
  • Ruby
  • PHP

Support

Questions about the API?

Last updated on
Introduction to kollectExamples