Forms

Dynamic form builder with submission tracking, spam protection, and CSV export. Forms support 14+ field types, multi-page layouts, conditional logic, and custom validation.

Field types: text, email, tel, textarea, select, checkbox, radio, date, datetime, time, number, file, rating, hidden.

Spam protection: Honeypot fields and/or reCAPTCHA v3, configured per-site via Spam Settings.

12 endpoints

`GET /forms`

List forms

Returns all forms for your site with submission counts.

Parameters

Name	In	Type	Required	Description
`page`	query	number	No	Number
`limit`	query	number	No	Number <= 100
`status`	query	"draft" \| "active" \| "closed" \| "archived"	No	One of: draft, active, closed, archived
`search`	query	string	No	Full-text search query
`sortBy`	query	"created_at" \| "updated_at" \| "name"	No	One of: created_at, updated_at, name
`sortOrder`	query	"asc" \| "desc"	No	One of: asc, desc
`dateFrom`	query	string	No	Filter from date (ISO 8601)
`dateTo`	query	string	No	Filter until date (ISO 8601)
`slug`	query	string	No	URL-friendly identifier, unique per site and locale
`slugs`	query	string[]	No	Array of strings
`ids`	query	string[]	No	Array of strings
`excludeIds`	query	string[]	No	Array of strings
`groupByTranslation`	query	boolean	No	Boolean
`locale`	query	string	No	BCP 47 locale code (e.g. "en", "fr")
`translationGroupId`	query	string	No	Translation group UUID (links translations across locales)

Responses

Status	Description
`200`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions

Examples

Bash

curl https://api.lynkow.com/v1/forms \
  -H "Authorization: Bearer $API_TOKEN"

Response Example

JSON

{
  "data": [
    {
      "id": 1,
      "name": "Contact Form",
      "slug": "contact-form",
      "status": "active",
      "locale": "en",
      "submissionCount": 134,
      "createdAt": "2025-01-05T10:00:00.000Z",
      "updatedAt": "2025-03-20T08:15:00.000Z"
    },
    {
      "id": 2,
      "name": "Newsletter Signup",
      "slug": "newsletter-signup",
      "status": "active",
      "locale": "en",
      "submissionCount": 892,
      "createdAt": "2025-01-10T14:00:00.000Z",
      "updatedAt": "2025-04-01T09:30:00.000Z"
    }
  ],
  "meta": {
    "total": 4,
    "perPage": 15,
    "currentPage": 1,
    "lastPage": 1
  }
}

`POST /forms`

Create a form

Creates a new form with a schema defining its fields. The schema is a JSON array of field definitions with types, labels, validation rules, and conditional logic.

Request Body

Content-Type: application/json

Field	Type	Required	Description
`name`	string	Yes	Required. Display name. 1-255 characters
`slug`	string	Yes	Required. URL-friendly identifier, unique per site and locale. 1-255 characters
`description`	string	No	Description text. Max 1000 characters
`schema`	object	Yes	Required. Field schema definition
`settings`	object	No	Configuration settings
`notifications`	object	No	Notification preferences
`honeypotEnabled`	boolean	No	Boolean
`recaptchaEnabled`	boolean	No	Boolean
`recaptchaSiteKey`	string	No	Max 255 characters
`recaptchaSecretKey`	string	No	Max 255 characters
`status`	"draft" \| "active" \| "closed" \| "archived"	No	One of: draft, active, closed, archived
`locale`	string	No	BCP 47 locale code (e.g. "en", "fr")

Responses

Status	Description
`201`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions
`422`	Validation error

Notes: - Forms are created in draft status by default.
Set status to "active" to start accepting submissions immediately.

Examples

Bash

curl -X POST https://api.lynkow.com/v1/forms \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contact Form",
    "slug": "contact-form",
    "status": "active",
    "schema": [
      {"name": "name", "type": "text", "label": "Full Name", "required": true},
      {"name": "email", "type": "email", "label": "Email", "required": true},
      {"name": "message", "type": "textarea", "label": "Message", "required": true}
    ],
    "successMessage": "Thank you for reaching out!"
  }'

Response Example

JSON

{
  "data": {
    "id": 3,
    "name": "Contact Form",
    "slug": "contact-form",
    "status": "active",
    "locale": "en",
    "submissionCount": 0,
    "schema": [
      {
        "name": "name",
        "type": "text",
        "label": "Full Name",
        "required": true
      },
      {
        "name": "email",
        "type": "email",
        "label": "Email",
        "required": true
      },
      {
        "name": "message",
        "type": "textarea",
        "label": "Message",
        "required": true
      }
    ],
    "successMessage": "Thank you for reaching out!",
    "redirectUrl": null,
    "createdAt": "2025-04-06T11:00:00.000Z",
    "updatedAt": "2025-04-06T11:00:00.000Z"
  }
}

`GET /forms/:id`

Get a form

Returns a form with its complete field schema and settings.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier

Responses

Status	Description
`200`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions
`404`	Not found

Examples

Bash

curl https://api.lynkow.com/v1/forms/1 \
  -H "Authorization: Bearer $API_TOKEN"

Response Example

JSON

{
  "data": {
    "id": 1,
    "name": "Contact Form",
    "slug": "contact-form",
    "status": "active",
    "locale": "en",
    "submissionCount": 134,
    "schema": [
      {
        "name": "name",
        "type": "text",
        "label": "Full Name",
        "required": true,
        "placeholder": "Your name"
      },
      {
        "name": "email",
        "type": "email",
        "label": "Email Address",
        "required": true,
        "placeholder": "[email protected]"
      },
      {
        "name": "message",
        "type": "textarea",
        "label": "Message",
        "required": true,
        "placeholder": "How can we help?"
      },
      {
        "name": "rating",
        "type": "rating",
        "label": "How would you rate us?",
        "required": false
      }
    ],
    "successMessage": "Thank you for your message!",
    "redirectUrl": null,
    "createdAt": "2025-01-05T10:00:00.000Z",
    "updatedAt": "2025-03-20T08:15:00.000Z"
  }
}

`PUT /forms/:id`

Update a form

Updates a form's schema, settings, or status. Existing submissions are preserved even if the schema changes.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier

Request Body

Content-Type: application/json

Field	Type	Required	Description
`name`	string	No	Display name. 1-255 characters
`slug`	string	No	URL-friendly identifier, unique per site and locale. 1-255 characters
`description`	string	No	Description text. Max 1000 characters
`schema`	object	No	Field schema definition
`settings`	object	No	Configuration settings
`notifications`	object	No	Notification preferences
`honeypotEnabled`	boolean	No	Boolean
`recaptchaEnabled`	boolean	No	Boolean
`recaptchaSiteKey`	string	No	Max 255 characters
`recaptchaSecretKey`	string	No	Max 255 characters
`status`	"draft" \| "active" \| "closed" \| "archived"	No	One of: draft, active, closed, archived

Responses

Status	Description
`200`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions
`404`	Not found
`422`	Validation error

Examples

Bash

curl -X PUT https://api.lynkow.com/v1/forms/1 \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contact Form v2",
    "status": "active",
    "successMessage": "We will get back to you within 24h."
  }'

Response Example

JSON

{
  "data": {
    "id": 1,
    "name": "Contact Form v2",
    "slug": "contact-form",
    "status": "active",
    "locale": "en",
    "submissionCount": 134,
    "schema": [
      {
        "name": "name",
        "type": "text",
        "label": "Full Name",
        "required": true
      },
      {
        "name": "email",
        "type": "email",
        "label": "Email",
        "required": true
      },
      {
        "name": "message",
        "type": "textarea",
        "label": "Message",
        "required": true
      }
    ],
    "successMessage": "We will get back to you within 24h.",
    "redirectUrl": null,
    "createdAt": "2025-01-05T10:00:00.000Z",
    "updatedAt": "2025-04-06T12:00:00.000Z"
  }
}

`DELETE /forms/:id`

Delete a form

Permanently deletes a form and ALL its submissions.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier

Responses

Status	Description
`200`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions
`404`	Not found

Examples

Bash

curl -X DELETE https://api.lynkow.com/v1/forms/1 \
  -H "Authorization: Bearer $API_TOKEN"

Response Example

JSON

{
  "message": "Form deleted"
}

`GET /forms/:id/submissions`

List form submissions

Returns paginated submissions for a form. Supports filtering by status (unread, read, archived, spam) and date range.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier
`page`	query	number	No	Number
`limit`	query	number	No	Number <= 100
`status`	query	"new" \| "read" \| "spam" \| "archived"	No	One of: new, read, spam, archived
`search`	query	string	No	Full-text search query
`sortBy`	query	"created_at" \| "updated_at" \| "status"	No	One of: created_at, updated_at, status
`sortOrder`	query	"asc" \| "desc"	No	One of: asc, desc
`dateFrom`	query	string	No	Filter from date (ISO 8601)
`dateTo`	query	string	No	Filter until date (ISO 8601)
`ids`	query	string[]	No	Array of strings
`excludeIds`	query	string[]	No	Array of strings

Responses

Status	Description
`200`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions
`404`	Not found

Examples

Bash

curl "https://api.lynkow.com/v1/forms/1/submissions?status=unread&page=1" \
  -H "Authorization: Bearer $API_TOKEN"

Response Example

JSON

{
  "data": [
    {
      "id": 501,
      "formId": 1,
      "status": "unread",
      "data": {
        "name": "Sophie Bernard",
        "email": "[email protected]",
        "message": "I would like to know more about your enterprise plan."
      },
      "ipAddress": "203.0.113.42",
      "userAgent": "Mozilla/5.0",
      "createdAt": "2025-04-05T16:30:00.000Z"
    },
    {
      "id": 500,
      "formId": 1,
      "status": "read",
      "data": {
        "name": "Marc Leroy",
        "email": "[email protected]",
        "message": "Can I schedule a demo?"
      },
      "ipAddress": "198.51.100.17",
      "userAgent": "Mozilla/5.0",
      "createdAt": "2025-04-04T10:15:00.000Z"
    }
  ],
  "meta": {
    "total": 134,
    "perPage": 15,
    "currentPage": 1,
    "lastPage": 9
  }
}

`GET /forms/:id/submissions/export`

Export submissions as CSV

Downloads all submissions for a form as a CSV file. Columns match the form's field schema.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier

Responses

Status	Description
`200`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions
`404`	Not found

Examples

Bash

curl "https://api.lynkow.com/v1/forms/1/submissions/export" \
  -H "Authorization: Bearer $API_TOKEN" \
  -o submissions.csv

Response Example

JSON

"Returns a CSV file (Content-Type: text/csv). Example output:\nid,name,email,message,status,created_at\n501,\"Sophie Bernard\",\"[email protected]\",\"I would like to know more...\",\"unread\",\"2025-04-05 16:30:00\"\n"

`GET /forms/:id/submissions/:submissionId`

Get a submission

Returns a single form submission with all field values.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier
`submissionId`	path	string	Yes	Form submission ID

Responses

Status	Description
`200`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions
`404`	Not found

Examples

Bash

curl https://api.lynkow.com/v1/forms/1/submissions/501 \
  -H "Authorization: Bearer $API_TOKEN"

Response Example

JSON

{
  "data": {
    "id": 501,
    "formId": 1,
    "status": "unread",
    "data": {
      "name": "Sophie Bernard",
      "email": "[email protected]",
      "message": "I would like to know more about your enterprise plan."
    },
    "ipAddress": "203.0.113.42",
    "userAgent": "Mozilla/5.0",
    "createdAt": "2025-04-05T16:30:00.000Z"
  }
}

`DELETE /forms/:id/submissions/:submissionId`

Delete a submission

Permanently deletes a single form submission.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier
`submissionId`	path	string	Yes	Form submission ID

Responses

Status	Description
`200`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions
`404`	Not found

Examples

Bash

curl -X DELETE https://api.lynkow.com/v1/forms/1/submissions/501 \
  -H "Authorization: Bearer $API_TOKEN"

Response Example

JSON

{
  "message": "Submission deleted"
}

`PUT /forms/:id/submissions/:submissionId/status`

Update submission status

Changes a submission's status. Valid values: read, archived, spam. Use this to manage your submission inbox.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier
`submissionId`	path	string	Yes	Form submission ID

Request Body

Content-Type: application/json

Field	Type	Required	Description
`status`	"new" \| "read" \| "spam" \| "archived"	Yes	Required. One of: new, read, spam, archived

Responses

Status	Description
`200`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions
`404`	Not found
`422`	Validation error

Examples

Bash

curl -X PUT https://api.lynkow.com/v1/forms/1/submissions/501/status \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "read"}'

Response Example

JSON

{
  "data": {
    "id": 501,
    "formId": 1,
    "status": "read",
    "data": {
      "name": "Sophie Bernard",
      "email": "[email protected]",
      "message": "I would like to know more about your enterprise plan."
    },
    "createdAt": "2025-04-05T16:30:00.000Z",
    "updatedAt": "2025-04-06T12:00:00.000Z"
  }
}

`GET /forms/:id/translations`

Get form translation status

Returns the translation status for this form across all enabled locales.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier

Responses

Status	Description
`200`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions
`404`	Not found

Examples

Bash

curl https://api.lynkow.com/v1/forms/1/translations \
  -H "Authorization: Bearer $API_TOKEN"

Response Example

JSON

{
  "data": {
    "en": {
      "status": "complete"
    },
    "fr": {
      "status": "missing"
    },
    "es": {
      "status": "partial"
    }
  }
}

`POST /forms/:id/copy-to-locale`

Copy form to another locale

Creates a translated copy of this form in the target locale. Field labels, placeholders, and option labels are copied — translate them in the copy.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier

Request Body

Content-Type: application/json

Field	Type	Required	Description
`targetLocale`	string	Yes	Required

Responses

Status	Description
`200`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions
`404`	Not found
`422`	Validation error

Examples

Bash

curl -X POST https://api.lynkow.com/v1/forms/1/copy-to-locale \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"locale": "fr"}'

Response Example

JSON

{
  "data": {
    "id": 10,
    "name": "Contact Form",
    "slug": "contact-form",
    "status": "draft",
    "locale": "fr",
    "submissionCount": 0,
    "schema": [
      {
        "name": "name",
        "type": "text",
        "label": "Full Name",
        "required": true
      },
      {
        "name": "email",
        "type": "email",
        "label": "Email",
        "required": true
      },
      {
        "name": "message",
        "type": "textarea",
        "label": "Message",
        "required": true
      }
    ],
    "createdAt": "2025-04-06T15:00:00.000Z",
    "updatedAt": "2025-04-06T15:00:00.000Z"
  }
}

GET /forms

Parameters

Responses

Examples

Response Example

POST /forms

Request Body

Responses

Examples

Response Example

GET /forms/:id

Parameters

Responses

Examples

Response Example

PUT /forms/:id

Parameters

Request Body

Responses

Examples

Response Example

DELETE /forms/:id

Parameters

Responses

Examples

Response Example

GET /forms/:id/submissions

Parameters

Responses

Examples

Response Example

GET /forms/:id/submissions/export

Parameters

Responses

Examples

Response Example

GET /forms/:id/submissions/:submissionId

Parameters

Responses

Examples

Response Example

DELETE /forms/:id/submissions/:submissionId

Parameters

Responses

Examples

Response Example

PUT /forms/:id/submissions/:submissionId/status

Parameters

Request Body

Responses

Examples

Response Example

GET /forms/:id/translations

Parameters

Responses

Examples

Response Example

POST /forms/:id/copy-to-locale

Parameters

Request Body

Responses

Examples

Response Example

For LLMs

`GET /forms`

`POST /forms`

`GET /forms/:id`

`PUT /forms/:id`

`DELETE /forms/:id`

`GET /forms/:id/submissions`

`GET /forms/:id/submissions/export`

`GET /forms/:id/submissions/:submissionId`

`DELETE /forms/:id/submissions/:submissionId`

`PUT /forms/:id/submissions/:submissionId/status`

`GET /forms/:id/translations`

`POST /forms/:id/copy-to-locale`