formies/API_DOCUMENTATION.md

Formies API Documentation (v1)

This document provides instructions on how to use the Formies API to access your forms and submission data programmatically.

Authentication

All API requests must be authenticated using an API Key.

1. Generate an API Key: You can generate and manage your API keys from your user dashboard under the "API Keys" section.

2. Pass the API Key: The API key must be included in the Authorization header of your HTTP requests, using the Bearer scheme.

   Example:

   Authorization: Bearer YOUR_FULL_API_KEY_HERE
   

   Replace YOUR_FULL_API_KEY_HERE with the actual API key you generated (e.g., fsk_xxxxxxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy).

If authentication fails (e.g., missing key, invalid key, expired key), the API will respond with a 401 Unauthorized or 403 Forbidden status code and a JSON error message.

Endpoints

All API endpoints are prefixed with /api/v1.

1. List Your Forms

• Endpoint: GET /api/v1/forms
• Method: GET
• Authentication: Required (Bearer Token)
• Description: Retrieves a list of all forms owned by the authenticated user.
• Successful Response (200 OK):

  {
  	"success": true,
  	"forms": [
  		{
  			"uuid": "form-uuid-123",
  			"name": "My Contact Form",
  			"created_at": "2023-10-26T10:00:00.000Z",
  			"is_archived": false,
  			"submission_count": 150
  		}
  		// ... other forms
  	]
  }
  

• Error Responses:
  • 401 Unauthorized: Authentication failed.
  • 500 Internal Server Error: If there was an issue fetching the forms.

2. List Submissions for a Form

• Endpoint: GET /api/v1/forms/:formUuid/submissions
• Method: GET
• Authentication: Required (Bearer Token)
• Path Parameters:
  • formUuid (string, required): The UUID of the form for which to retrieve submissions.
• Query Parameters (for pagination):
  • page (integer, optional, default: 1): The page number of submissions to retrieve.
  • limit (integer, optional, default: 25): The number of submissions to retrieve per page.
• Description: Retrieves a paginated list of submissions for a specific form owned by the authenticated user.
• Successful Response (200 OK):

  {
  	"success": true,
  	"formName": "My Contact Form",
  	"formUuid": "form-uuid-123",
  	"pagination": {
  		"currentPage": 1,
  		"totalPages": 3,
  		"totalSubmissions": 65,
  		"limit": 25,
  		"perPage": 25,
  		"count": 25
  	},
  	"submissions": [
  		{
  			"id": 1,
  			"data": { "email": "test@example.com", "message": "Hello!" },
  			"ip_address": "123.123.123.123",
  			"submitted_at": "2023-10-27T14:30:00.000Z"
  		}
  		// ... other submissions for the current page
  	]
  }
  

• Error Responses:
  • 401 Unauthorized: Authentication failed.
  • 403 Forbidden: If the authenticated user does not own the specified form.
  • 404 Not Found: If the specified formUuid does not exist.
  • 500 Internal Server Error: If there was an issue fetching the submissions.

General Notes

• All API responses are in JSON format.
• Successful responses will generally include a success: true field.
• Error responses will include success: false and an error field (string or object) with details.