REST API Reference

The GudForm API lets you manage forms, collections, and responses programmatically. All endpoints require authentication.

Authentication

Authenticate requests by including your API key in the Authorization header as a Bearer token. Generate keys from Dashboard → API Keys.

Header format

Authorization: Bearer ff_your_api_key_here

All API keys start with ff_. Keep your keys secure — they grant full access to your account’s forms and responses.

Free keys work on hosted Cloud with per-minute rate limits. Self-host is unlocked. See Rate Limits.

Forms

List Forms

Returns all forms owned by the authenticated user, ordered by last updated. Optionally filter by collection.

GET/api/v1/forms

Query Parameters

Parameter	Type	Required	Description
`collectionId`	string	No	Filter forms by collection ID

Response

200 OKJSON

{
  "forms": [
    {
      "id": "clx1234abcd",
      "title": "Customer Feedback",
      "description": "Collect feedback from customers",
      "slug": "customer-feedback",
      "status": "PUBLISHED",
      "collectionId": "col_abc123",
      "collection": {
        "id": "col_abc123",
        "name": "Surveys"
      },
      "themeColor": "#6366f1",
      "backgroundColor": "#ffffff",
      "themeMode": "LIGHT",
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": "2025-01-20T14:30:00.000Z",
      "publishedAt": "2025-01-16T09:00:00.000Z",
      "_count": {
        "responses": 142,
        "questions": 8
      }
    }
  ]
}

Create Form

Creates a new form in your account. If no collectionId is provided, the form is placed in your default collection.

POST/api/v1/forms

Request Body

Parameter	Type	Required	Description
`title`	string	No	Form title (defaults to "Untitled Form")
`description`	string	No	Form description
`collectionId`	string	No	Collection to place the form in (defaults to your default collection)
`questions`	array	No	Optional question list created in the same request

RequestJSON

{
  "title": "Event Registration",
  "description": "Register for our upcoming workshop",
  "collectionId": "col_abc123"
}

201 CreatedJSON

{
  "form": {
    "id": "clx5678efgh",
    "title": "Event Registration",
    "description": "Register for our upcoming workshop",
    "slug": "event-registration-abc123",
    "status": "DRAFT",
    "collectionId": "col_abc123",
    "createdAt": "2025-01-21T12:00:00.000Z"
  }
}

Get Form

Retrieve a single form with all questions.

GET/api/v1/forms/:formId

Path Parameters

Parameter	Type	Required	Description
`formId`	string	Yes	The form ID

200 OKJSON

{
  "form": {
    "id": "clx1234abcd",
    "title": "Customer Feedback",
    "status": "PUBLISHED",
    "collectionId": "col_abc123",
    "collection": {
      "id": "col_abc123",
      "name": "Surveys"
    },
    "paymentEnabled": true,
    "paymentAmount": 1000,
    "paymentCurrency": "usd",
    "paymentDescription": "Consultation fee",
    "questions": [
      {
        "id": "q_001",
        "order": 0,
        "type": "WELCOME_SCREEN",
        "title": "Welcome!",
        "description": "Thanks for taking our survey",
        "required": false,
        "properties": {}
      },
      {
        "id": "q_002",
        "order": 1,
        "type": "SHORT_TEXT",
        "title": "What is your name?",
        "description": null,
        "required": true,
        "properties": { "placeholder": "John Doe" }
      },
      {
        "id": "q_003",
        "order": 2,
        "type": "RATING",
        "title": "Rate your experience",
        "required": true,
        "properties": { "maxRating": 5 }
      }
    ],
    "_count": { "responses": 142 }
  }
}

Replace questions

Replace the live question list on a form. Omit id for new questions. Questions not included are deleted.

PUT/api/v1/forms/:formId/questions

RequestJSON

{
  "questions": [
    {
      "type": "SHORT_TEXT",
      "title": "What is your name?",
      "required": true
    },
    {
      "type": "EMAIL",
      "title": "Email",
      "required": true
    }
  ]
}

Update Form

Update form properties. Use collectionId to move a form between collections.

PATCH/api/v1/forms/:formId

Request Body

Parameter	Type	Required	Description
`title`	string	No	Form title
`description`	string	No	Form description
`status`	string	No	"DRAFT", "PUBLISHED", or "CLOSED"
`collectionId`	string	No	Move form to a different collection
`themeColor`	string	No	Hex color code (e.g. #6366f1)
`backgroundColor`	string	No	Hex background color
`showProgressBar`	boolean	No	Show progress indicator
`redirectUrl`	string	No	URL to redirect after submission
`notifyOnResponse`	boolean	No	Email notification on new response

Request — move form to a collectionJSON

{
  "collectionId": "col_def456"
}

Delete Form

Permanently deletes a form and all its questions and responses. This action cannot be undone.

DELETE/api/v1/forms/:formId

200 OKJSON

{ "deleted": true }

Responses

List Responses

Retrieve paginated responses for a form. Each response includes all answers with their associated question details.

GET/api/v1/forms/:formId/responses

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number (default: 1)
`limit`	integer	No	Results per page (default: 50, max: 100)

200 OKJSON

{
  "responses": [
    {
      "id": "resp_abc123",
      "formId": "clx1234abcd",
      "startedAt": "2025-01-20T14:30:00.000Z",
      "completedAt": "2025-01-20T14:32:15.000Z",
      "paymentStatus": "COMPLETED",
      "paymentAmount": 1000,
      "paymentCurrency": "usd",
      "answers": [
        {
          "id": "ans_001",
          "questionId": "q_002",
          "value": "Jane Smith",
          "question": {
            "id": "q_002",
            "title": "What is your name?",
            "type": "SHORT_TEXT"
          }
        },
        {
          "id": "ans_002",
          "questionId": "q_003",
          "value": "5",
          "question": {
            "id": "q_003",
            "title": "Rate your experience",
            "type": "RATING"
          }
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 142,
    "totalPages": 3
  }
}

Submit a response

Submit answers for a form you own. Each item is questionId plus value. Closed forms are rejected.

POST/api/v1/forms/:formId/responses

RequestJSON

{
  "answers": [
    { "questionId": "q_002", "value": "Jane Smith" },
    { "questionId": "q_003", "value": "5" }
  ]
}

Collections

Collections let you organize forms into groups. Every account has a default collection that cannot be renamed or deleted. Forms are always placed in a collection — new forms go to the default collection unless you specify otherwise.

List Collections

Returns all collections for the authenticated user, ordered by default collection first then alphabetically.

GET/api/v1/collections

200 OKJSON

{
  "collections": [
    {
      "id": "col_abc123",
      "name": "Default",
      "isDefault": true,
      "createdAt": "2025-01-10T08:00:00.000Z",
      "updatedAt": "2025-01-20T14:00:00.000Z",
      "_count": {
        "forms": 5,
        "teams": 0
      }
    },
    {
      "id": "col_def456",
      "name": "Surveys",
      "isDefault": false,
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": "2025-01-18T12:00:00.000Z",
      "_count": {
        "forms": 3,
        "teams": 2
      }
    }
  ]
}

Create Collection

Creates a new collection.

POST/api/v1/collections

Request Body

Parameter	Type	Required	Description
`name`	string	Yes	Collection name (1-50 characters)

RequestJSON

{
  "name": "Marketing Forms"
}

201 CreatedJSON

{
  "collection": {
    "id": "col_ghi789",
    "name": "Marketing Forms",
    "isDefault": false,
    "createdAt": "2025-01-21T12:00:00.000Z",
    "updatedAt": "2025-01-21T12:00:00.000Z"
  }
}

Get Collection

Retrieve a single collection with all its forms.

GET/api/v1/collections/:collectionId

Path Parameters

Parameter	Type	Required	Description
`collectionId`	string	Yes	The collection ID

200 OKJSON

{
  "collection": {
    "id": "col_def456",
    "name": "Surveys",
    "isDefault": false,
    "forms": [
      {
        "id": "clx1234abcd",
        "title": "Customer Feedback",
        "slug": "customer-feedback",
        "status": "PUBLISHED",
        "createdAt": "2025-01-15T10:00:00.000Z",
        "updatedAt": "2025-01-20T14:30:00.000Z",
        "_count": { "responses": 142, "questions": 8 }
      }
    ],
    "_count": { "forms": 1, "teams": 2 }
  }
}

Update Collection

Rename a collection. The default collection cannot be renamed.

PATCH/api/v1/collections/:collectionId

Request Body

Parameter	Type	Required	Description
`name`	string	Yes	New collection name (1-50 characters)

RequestJSON

{
  "name": "Customer Surveys"
}

Delete Collection

Deletes a collection. The default collection cannot be deleted. When a collection is deleted, all its forms are moved back to the default collection automatically.

DELETE/api/v1/collections/:collectionId

200 OKJSON

{ "deleted": true }

Question Types

Each question has a type field indicating the kind of input. The properties object varies by type.

Type	Description	Properties
`WELCOME_SCREEN`	Intro screen	`buttonText, align, titleSize, titleColor, titleBold, descriptionSize, descriptionColor, descriptionBold`
`SHORT_TEXT`	Single-line text	`placeholder, format (set to url for website fields)`
`LONG_TEXT`	Multi-line text	`placeholder`
`EMAIL`	Email address	`placeholder`
`NUMBER`	Numeric input	`placeholder, min, max`
`PHONE`	Phone number	`placeholder`
`DATE`	Date picker	—
`RATING`	Star rating	`maxRating`
`SCALE`	Numeric scale	`scaleMin, scaleMax, scaleMinLabel, scaleMaxLabel`
`YES_NO`	Boolean choice	—
`MULTIPLE_CHOICE`	Select from options	`choices, allowMultiple, minSelections, maxSelections`
`DROPDOWN`	Dropdown menu	`choices`
`FILE_UPLOAD`	File attachment	`maxFileSize`
`STATEMENT`	Read-only text	`buttonText, align, titleSize, titleColor, titleBold, descriptionSize, descriptionColor, descriptionBold`
`THANK_YOU_SCREEN`	Completion screen	`align, titleSize, titleColor, titleBold, descriptionSize, descriptionColor, descriptionBold`

Error Handling

The API uses standard HTTP status codes. Errors return a JSON object with an error field containing a human-readable message.

Status	Meaning	Example
400	Bad Request	Invalid parameters
401	Unauthorized	Missing or invalid API key
404	Not Found	Form or resource not found
429	Rate Limited	Too many requests
500	Server Error	Internal error

Error response formatJSON

{
  "error": "Form not found"
}

Rate Limits

API requests are rate-limited per API key:

Plan	API Access	Rate Limit	Burst
Free	Yes	30 requests/min	30 requests
Starter	Yes	60 requests/min	60 requests
Pro	Yes	100 requests/min	100 requests
Business	Yes	500 requests/min	500 requests
Self-host	Yes	1000 requests/min	1000 requests

When rate-limited, the API returns 429 Too Many Requests with a Retry-After header indicating seconds to wait.