Management API
Manage submissions programmatically per form: create, retrieve, list, update, and delete submissions using form-scoped API keys.
Introduction
DropForm provides a REST API to interact programmatically with your forms and submissions. The API supports standard HTTP methods and accepts JSON or multipart requests, including file uploads. It is perfect for server-side automation, integrations, or any workflow where you need direct access to your form data.
Authentication
All DropForm API endpoints require authentication using form-level API keys. Each form provides two types of keys:
- Master Key - full access for reading, creating, updating, and deleting submissions. Should only be used from trusted server-side environments.
- Read-Only Key - limited access to fetch form schemas and retrieve submissions. Cannot create, update, or delete data.
Include the API key in every request using the HTTP Authorization header.
Best Practices
- Keep keys secret: Never expose Master Keys in client-side code or public repositories.
- Rotate keys regularly: Replace and revoke old keys periodically to reduce security risks.
- Use Read-Only keys when possible: Limit exposure when only fetching data.
- Server-side enforcement: Use Master Keys for operations that modify data; keep Read-Only keys for data retrieval.
By following these practices, you ensure secure access to your forms and submissions while minimizing the risk of unauthorized access.
Create Submission
POST /api/v1/forms/{formId}/submissions
Create a new submission for a specific form. You can send data as JSON or multipart/form-data including file uploads.
Access: Master Key only
JSON Request
Multipart Request
Use multipart/form-data for file uploads. Include a data part with JSON-encoded form fields, and add file parts with the field names matching the form.
Example Response
Get Submission
GET /api/v1/forms/{formId}/submissions/{submissionId}
Retrieve a single submission by its ID. The response includes all submission metadata, form data, headers, and attached files.
Access: Read-Only Key or Master Key
Example Request
Example Response
The response includes the submission’s metadata and its field data:
List Submissions
GET /api/v1/forms/{formId}/submissions
Retrieve a paginated list of submissions for a specific form. You can filter by submissionStatus, isStarred, or search by keyword. Sorting and paging parameters are supported.
Access: Master Key or Read-Only Key
Request Parameters
- page (integer, default: 0) - page number (0-based)
- size (integer, default: 20) - number of submissions per page
- sortBy - field to sort by. Allowed values:
CREATED_DATE - sortDir - sort direction. Allowed values:
ASC,DESC - submissionStatus - filter by status. Allowed values:
READ,UNREAD,SPAM - isStarred (boolean) - filter by starred submissions
- keyword (string) - search in submission data
Example Request
Example Response
Update Submission
PATCH /api/v1/forms/{formId}/submissions/{submissionId}
Update a submission’s metadata, such as isStarred or submissionStatus.
Access: Master Key only
Example Request
Example Response
Delete Submission
DELETE /api/v1/forms/{formId}/submissions/{submissionId}
Delete a submission permanently. Once deleted, the submission cannot be recovered.
Access: Master Key only
Example Request
Status codes
200- OK201- Created (submission accepted)204- No Content (delete successful)400- Bad Request (validation error)401- Unauthorized (missing or invalid API key)403- Forbidden (key does not have required role)404- Not Found (form or submission not found)429- Too Many Requests (rate limit)500- Internal Server Error