PutForm
Profile

Developer resources

API Documentation

Everything you need to integrate PutForm into your own apps — create forms, collect responses, and manage submissions with a simple REST API.

iOverview

The PutForm API lets you manage forms programmatically. All endpoints use JSON over HTTP, require an API key, and return structured responses that are easy to consume from any language.

Base URL
https://api.putform.online

Quick links

POST
Create Form
Create a new form with questions.
GET
List Forms
Fetch all forms for the current user.
PUT
Update Form
Edit form details and questions.
SCHEMA
Data Models
Form & question field reference.
PATCH
Publish Form
Make a form live for respondents.
POST
Submit Response
Answer a published form.
ERRORS
Error Codes
401, 403, 404, 400 responses.

🔐Authentication

Every Forms API request must include your API key in the X-API-KEY request header. The public Submit Response endpoint is the exception and does not require a key.

Header

Include your API key as a header on every request:

X-API-KEY: gf_live_xxxxxxxxxxxxxxxxx
Keep your API key secret. Do not expose it in frontend JavaScript or commit it to Git. Generate and manage your keys from your Profile page. 
X-API-KEY: gf_live_xxxxxxxxxxxxxxxxx

📦Data Models

The main response model returned by every Forms API endpoint. Each field's Java type is shown alongside the field name.

FormResponse Root object 

{
  "id": "UUID",
  "ownerId": "Long",
  "title": "String",
  "description": "String",
  "status": "FormStatus (ENUM)",
  "plan": "FormPlan (ENUM)",
  "responseLimit": "Long",
  "fillingAmount": "BigDecimal",
  "totalCollectionAmount": "BigDecimal",
  "questions": [
    {
      "id": "UUID",
      "formId": "UUID",
      "question": "String",
      "type": "QuestionType (ENUM)",
      "required": "Boolean",
      "questionOrder": "Integer",
      "configuration": {}
    }
  ],
  "expiresAt": "ISO-8601 LocalDateTime",
  "createdAt": "ISO-8601 LocalDateTime",
  "updatedAt": "ISO-8601 LocalDateTime"
}

Form fields

Field Type Description
id UUID Unique identifier for the form. Used in all URL paths and query parameters.
ownerId Long ID of the user who owns the form.
title String Form title. Required. Maximum 200 characters.
description String Optional form description. Maximum 1000 characters.
status FormStatus Current lifecycle state.
DRAFT PUBLISHED CLOSED ARCHIVED
plan FormPlan Pricing plan for the form.
FREE BASIC PREMIUM
responseLimit Long Maximum number of responses accepted. null means unlimited.
fillingAmount BigDecimal Amount charged per response. 0.00 for free forms.
totalCollectionAmount BigDecimal Running total of all paid responses. Computed by the backend.
questions Question[] Array of question objects. See Question fields below.
expiresAt LocalDateTime ISO-8601 timestamp when the form stops accepting responses. null for no expiry.
createdAt LocalDateTime ISO-8601 timestamp when the form was created.
updatedAt LocalDateTime ISO-8601 timestamp of the last modification.

Question Nested object

Field Type Description
id UUID Unique identifier for the question.
formId UUID ID of the parent form this question belongs to.
question String Question text shown to respondents. Required. Maximum 500 characters.
type QuestionType Input type of the question.
SHORT_TEXT LONG_TEXT NUMBER EMAIL DATE SINGLE_CHOICE MULTIPLE_CHOICE DROPDOWN CHECKBOX FILE_UPLOAD RATING
required Boolean true if respondents must answer this question to submit.
questionOrder Integer Display position of the question, starting from 1.
configuration Map<String,Object> Type-specific settings. For choice-based questions this contains an options array, e.g. { "options": ["Yes", "No"] }. Empty object for free-text questions.
Note: All timestamps are serialized as ISO-8601 strings (e.g. 2026-12-31T23:59:59) in the server's local timezone. All IDs are UUIDs in canonical xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx format.

01Create Form

Creates a new form owned by the API key owner.

POST /api/v1/forms
Full URL
https://api.putform.online/api/v1/forms
Headers
Content-Type: application/json X-API-KEY: gf_live_xxxxxxxxx
Request body 
{
  "title": "Customer Feedback Form",
  "description": "Collect feedback from customers",
  "plan": "FREE",
  "responseLimit": 100,
  "fillingAmount": 0.00,
  "expiresAt": "2026-12-31T23:59:59",
  "questionRequestSet": [
    {
      "question": "How was our service?",
      "type": "SHORT_TEXT",
      "required": true,
      "questionOrder": 1,
      "configuration": {}
    }
  ]
}
✓ Success 201 Created 
{
  "id": "{formId}",
  "ownerId": 1,
  "title": "Customer Feedback Form",
  "description": "Collect feedback from customers",
  "status": "DRAFT",
  "plan": "FREE",
  "responseLimit": 100,
  "fillingAmount": 0.00,
  "totalCollectionAmount": 0.00,
  "questions": [],
  "expiresAt": "2026-12-31T23:59:59",
  "createdAt": "2026-09-13T23:00:00",
  "updatedAt": "2026-09-13T23:00:00"
}

02Get My Forms

Returns all forms associated with the API key owner.

GET /api/v1/forms/all
Full URL
https://api.putform.online/api/v1/forms/all
Headers
X-API-KEY: gf_live_xxxxxxxxx
✓ Success 200 OK 
[
  {
    "id": "{formId}",
    "ownerId": 1,
    "title": "Customer Feedback Form",
    "description": "Collect feedback from customers",
    "status": "DRAFT",
    "plan": "FREE",
    "responseLimit": 100,
    "fillingAmount": 0.00,
    "totalCollectionAmount": 0.00,
    "questions": [],
    "expiresAt": "2026-12-31T23:59:59",
    "createdAt": "2026-09-13T23:00:00",
    "updatedAt": "2026-09-13T23:00:00"
  }
]

03Get Form

Returns a specific form by its ID.

GET /api/v1/forms?formId={formId}
Full URL
https://api.putform.online/api/v1/forms?formId={formId}
Query parameters
Param Type Description
formId UUID Required. Unique identifier of the form to fetch.
Headers
X-API-KEY: gf_live_xxxxxxxxx
✓ Success 200 OK

Returns the full form object.

04Update Form

Updates an existing form. You can modify the form's details and its full question list in one request.

PUT /api/v1/forms?formId={formId}
Full URL
https://api.putform.online/api/v1/forms?formId={formId}
Query parameters
Param Type Description
formId UUID Required. Unique identifier of the form to update.
Headers
Content-Type: application/json X-API-KEY: gf_live_xxxxxxxxx
Request body 
{
  "title": "Updated Customer Feedback",
  "description": "Updated description",
  "plan": "FREE",
  "responseLimit": 200,
  "fillingAmount": 5.00,
  "expiresAt": "2026-12-31T23:59:59",
  "questionRequestList": [
    {
      "id": "{questionId}",
      "question": "How was our service?",
      "type": "SHORT_TEXT",
      "required": true,
      "questionOrder": 1,
      "configuration": {}
    }
  ]
}
✓ Success 200 OK

Returns the updated form object.

05Publish Form

Publishes a form so respondents can start submitting responses.

PATCH /api/v1/forms/publish?formId={formId}
Full URL
https://api.putform.online/api/v1/forms/publish?formId={formId}
Query parameters
Param Type Description
formId UUID Required. Unique identifier of the form to publish.
Headers
X-API-KEY: gf_live_xxxxxxxxx
✓ Success 200 OK 
{
  "id": "{formId}",
  "title": "Customer Feedback Form",
  "status": "PUBLISHED"
}

06Close Form

Closes a form. Respondents can no longer submit responses.

PATCH /api/v1/forms/close?formId={formId}
Full URL
https://api.putform.online/api/v1/forms/close?formId={formId}
Query parameters
Param Type Description
formId UUID Required. Unique identifier of the form to close.
Headers
X-API-KEY: gf_live_xxxxxxxxx
✓ Success 200 OK

Returns the updated FormResponse.

07Archive Form

Archives a form. Archived forms can no longer be edited or accept responses.

PATCH /api/v1/forms/archive?formId={formId}
Full URL
https://api.putform.online/api/v1/forms/archive?formId={formId}
Query parameters
Param Type Description
formId UUID Required. Unique identifier of the form to archive.
Headers
X-API-KEY: gf_live_xxxxxxxxx
✓ Success 200 OK

Returns the updated FormResponse.

08Delete Form

Permanently deletes a form and all of its responses.

DELETE /api/v1/forms?formId={formId}
Full URL
https://api.putform.online/api/v1/forms?formId={formId}
Query parameters
Param Type Description
formId UUID Required. Unique identifier of the form to delete.
Headers
X-API-KEY: gf_live_xxxxxxxxx
✓ Success 204 No Content

No response body is returned.

09Submit Response

Submits a respondent's answer to a published form. This is the only public endpoint in the API — it does not require an API key, since it is called from the form's public URL by respondents.

POST /api/v1/forms/submit?formId={formId}
Full URL
https://api.putform.online/api/v1/forms/submit?formId={formId}
Query parameters
Param Type Description
formId UUID Required. ID of the form the response belongs to.
Headers
Content-Type: application/json
Request body 
{
  "respondentEmail": "jane@example.com",
  "answers": {
    "{questionId}": "Great service!",
    "{questionId2}": ["Yes", "Fast delivery"]
  }
}
Request fields
Field Type Description
respondentEmail String Optional. Must be a valid email address — the server validates this with @Email and returns 400 Bad Request if the format is wrong.
answers Map<String,Object> Required. Keys are question UUIDs; values depend on the question's type: a plain string for text/number/date/email, an array of strings for choice questions (MULTIPLE_CHOICE, CHECKBOX), a number for RATING, and a URL or file reference for FILE_UPLOAD.
✓ Success 201 Created 
{
  "id": "{responseId}",
  "formId": "{formId}",
  "respondentEmail": "jane@example.com",
  "answers": {
    "{questionId}": "Great service!",
    "{questionId2}": ["Yes", "Fast delivery"]
  },
  "submittedAt": "2026-09-13T23:12:00"
}
Invalid Email 400 Bad Request 
{
  "status": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "errors": {
    "respondentEmail": "Invalid email address"
  }
}
Note: This endpoint is public by design and does not send X-API-KEY. The server rejects submissions to forms that are not in PUBLISHED status, that have expired, or that have reached their responseLimit — each returns a 4xx error.

⚠Error Responses

The API returns standard HTTP status codes along with a JSON error body.

Missing API Key 401 Unauthorized 
{
  "status": 401,
  "error": "Unauthorized",
  "message": "API key is required"
}
Invalid API Key 401 Unauthorized 
{
  "status": 401,
  "error": "Unauthorized",
  "message": "Invalid API key"
}
Expired/Revoked API Key 401 Unauthorized 
{
  "status": 401,
  "error": "Unauthorized",
  "message": "API key is expired or revoked"
}
Access Denied 403 Forbidden 
{
  "status": 403,
  "error": "Forbidden",
  "message": "You do not have permission to access this resource"
}
Form Not Found 404 Not Found 
{
  "status": 404,
  "error": "Not Found",
  "message": "Form not found"
}
Validation Error 400 Bad Request 
{
  "status": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "errors": {
    "title": "Title is required"
  }
}
✓ Copied