REST APIForms

Forms Endpoints

Submit form data and manage form configurations via the REST API.

POST/api/forms/:formId/submit

Submit Form

Submit data to a published form. This endpoint is public and does not require authentication for forms that allow public submissions.

Public Endpoint

Form submission is designed to work from client-side code without exposing your API key. The formId can be either the form ID or the form slug.

Request Body

Field	Type	Description
`[fieldId]`	any	Form field values keyed by field ID

Example Request

curlTerminal

curl -X POST https://api.metigan.com/api/forms/contact-form/submit \
  -H "Content-Type: application/json" \
  -d '{
    "field-email": "user@example.com",
    "field-name": "John Doe",
    "field-message": "Hello, I would like more information about your services.",
    "field-company": "Acme Inc"
  }'

Response

200 OKJSON

{
  "success": true,
  "message": "Thank you for your submission!",
  "submissionId": "sub_xyz789"
}

JavaScript Example (Client-side)

form-submit.jsJavaScript

// Client-side form submission (no API key needed)
const response = await fetch('https://api.metigan.com/api/forms/contact-form/submit', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    'field-email': formData.email,
    'field-name': formData.name,
    'field-message': formData.message
  })
});

const result = await response.json();

if (result.success) {
  alert(result.message);
}

GET/api/forms

List Forms

Retrieve all forms with pagination. Requires API key authentication.

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20)
`published`	boolean	Filter by published status

Example Request

curlTerminal

curl -X GET "https://api.metigan.com/api/forms?page=1&limit=20" \
  -H "x-api-key: your_api_key"

Response

200 OKJSON

{
  "success": true,
  "forms": [
    {
      "id": "frm_abc123",
      "title": "Contact Form",
      "description": "Get in touch with us",
      "slug": "contact-form",
      "published": true,
      "publishedUrl": "https://forms.metigan.com/f/contact-form",
      "analytics": {
        "views": 1234,
        "submissions": 89,
        "conversionRate": 7.2
      },
      "createdAt": "2024-01-19T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 5,
    "page": 1,
    "limit": 20,
    "pages": 1
  }
}

GET/api/forms/:id

Get Form

Retrieve a form's configuration including all fields and settings.

Example Request

curlTerminal

curl -X GET https://api.metigan.com/api/forms/frm_abc123 \
  -H "x-api-key: your_api_key"

Response

200 OKJSON

{
  "success": true,
  "data": {
    "id": "frm_abc123",
    "title": "Contact Form",
    "description": "Get in touch with us",
    "slug": "contact-form",
    "fields": [
      {
        "id": "field-email",
        "type": "email",
        "label": "Email Address",
        "placeholder": "you@example.com",
        "required": true
      },
      {
        "id": "field-name",
        "type": "text",
        "label": "Full Name",
        "placeholder": "John Doe",
        "required": true
      },
      {
        "id": "field-message",
        "type": "textarea",
        "label": "Message",
        "placeholder": "How can we help?",
        "required": true
      },
      {
        "id": "field-company",
        "type": "text",
        "label": "Company",
        "required": false
      }
    ],
    "settings": {
      "successMessage": "Thank you for your submission!",
      "notifyEmail": "team@yourcompany.com",
      "enableCaptcha": true,
      "storeResponses": true
    },
    "audienceId": "aud_abc123",
    "published": true,
    "createdAt": "2024-01-19T10:30:00Z"
  }
}

GET/api/forms/public/:slug

Get Public Form

Retrieve a published form by its slug for public rendering. No authentication required.

Example Request

curlTerminal

curl -X GET https://api.metigan.com/api/forms/public/contact-form

Response

200 OKJSON

{
  "success": true,
  "data": {
    "title": "Contact Form",
    "description": "Get in touch with us",
    "fields": [
      {
        "id": "field-email",
        "type": "email",
        "label": "Email Address",
        "placeholder": "you@example.com",
        "required": true
      },
      {
        "id": "field-name",
        "type": "text",
        "label": "Full Name",
        "required": true
      },
      {
        "id": "field-message",
        "type": "textarea",
        "label": "Message",
        "required": true
      }
    ],
    "appearance": {
      "backgroundColor": "#FFFFFF",
      "primaryColor": "#4F46E5",
      "fontFamily": "Inter"
    },
    "buttonCustomization": {
      "text": "Submit",
      "variant": "default"
    }
  }
}

GET/api/forms/:id/submissions

Get Form Submissions

Retrieve all submissions for a form with pagination.

Query Parameters

Parameter	Type	Description
`page`	number	Page number
`limit`	number	Items per page (max: 100)
`startDate`	string	Filter from date (ISO 8601)
`endDate`	string	Filter to date (ISO 8601)

Example Request

curlTerminal

curl -X GET "https://api.metigan.com/api/forms/frm_abc123/submissions?page=1&limit=50" \
  -H "x-api-key: your_api_key"

Response

200 OKJSON

{
  "success": true,
  "submissions": [
    {
      "id": "sub_xyz789",
      "data": {
        "field-email": "user@example.com",
        "field-name": "John Doe",
        "field-message": "Hello!"
      },
      "createdAt": "2024-01-19T14:30:00Z"
    }
  ],
  "pagination": {
    "total": 89,
    "page": 1,
    "limit": 50,
    "pages": 2
  }
}

Form Field Types

Available field types for form configuration:

Type	Description	Data Type
`text`	Single-line text input	string
`email`	Email address input	string
`number`	Numeric input	number
`textarea`	Multi-line text input	string
`select`	Dropdown selection	string
`checkbox`	Multiple choice checkboxes	string[]
`radio`	Single choice radio buttons	string
`date`	Date picker	string (ISO)
`phone`	Phone number input	string
`file`	File upload	object
`rating`	Star rating	number