API Documentation

Common API Patterns

APIResponse<T>

Standard response format for all API endpoints. We always return HTTP 200 for business logic responses, using error_code for business logic errors. HTTP error codes (4xx, 5xx) are only used for unexpected errors or server issues.

Property	Type	Description	Required	Default
`success`	`boolean`	Whether the operation was successful	Yes	-
`data`	`T \| null`	Response data of generic type T	No	-
`message`	`string`	Human-readable message for both success and error cases	No	-
`error_code`	`ErrorCode`	Business logic error code, only present for errors	No	-

ErrorCode

Enumeration of possible business logic error codes

Property	Type	Description	Required	Default
`SUCCESS`	`string`	Operation completed successfully	Yes	-
`NOT_FOUND`	`string`	Requested resource not found	Yes	-
`USER_NOT_FOUND`	`string`	User not found	Yes	-
`INVALID_INPUT`	`string`	Invalid input data	Yes	-
`AUTHENTICATION_FAILED`	`string`	Authentication failed	Yes	-
`UNAUTHORIZED_ACCESS`	`string`	User not authorized to access resource	Yes	-
`FORBIDDEN_ACTION`	`string`	Action not allowed	Yes	-
`VALIDATION_ERROR`	`string`	Input validation failed	Yes	-
`MISSING_REQUIRED_FIELDS`	`string`	Required fields are missing	Yes	-
`RESOURCE_NOT_FOUND`	`string`	Requested resource not found	Yes	-
`RESOURCE_ALREADY_EXISTS`	`string`	Resource already exists	Yes	-
`SUBSCRIPTION_EXPIRED`	`string`	User subscription has expired	Yes	-
`PAYMENT_FAILED`	`string`	Payment operation failed	Yes	-
`INTEGRATION_ERROR`	`string`	Error with external integration	Yes	-
`SERVICE_UNAVAILABLE`	`string`	Service is currently unavailable	Yes	-
`INTERNAL_SERVER_ERROR`	`string`	Internal server error occurred	Yes	-
`OPERATION_FAILED`	`string`	Operation failed to complete	Yes	-
`INVALID_FILE_TYPE`	`string`	File type not supported	Yes	-

Successful Response

{
    "success": true,
    "data": {
        "id": "01HQ2V...",
        "title": "Contact Form"
    },
    "message": "Form created successfully"
}

Error Response

{
    "success": false,
    "message": "Form not found",
    "error_code": "RESOURCE_NOT_FOUND"
}

Forms API

GET /forms

Get all forms for the current user

Parameters

Name	Type	Description	Required
exclude_archived_trashed_deleted	`boolean`	Filter out archived/trashed/deleted forms	Yes
favorites_first	`boolean`	Sort favorites first	Yes
limit	`number`	Limit number of results	No

Returns

Array of FormAsQueryResult

GET /forms/{form_id}

Get a specific form by ID

Parameters

Name	Type	Description	Required
form_id	`string`	Form ID	Yes

Returns

FormAsQueryResult

POST /forms

Create a new form

Parameters

Name	Type	Description	Required
form	`FormCreate`	Form creation data	Yes

Returns

FormAsQueryResult

PUT /forms/{form_id}

Update an existing form

Parameters

Name	Type	Description	Required
form_id	`string`	Form ID	Yes
form	`FormUpdate`	Form update data	Yes

Returns

FormAsQueryResult

DELETE /forms/{form_id}

Delete a form

Parameters

Name	Type	Description	Required
form_id	`string`	Form ID	Yes

Returns

APIResponse

POST /forms/{form_id}/submit

Submit form response

Parameters

Name	Type	Description	Required
form_id	`string`	Form ID	Yes
files	`List[UploadFile]`	Uploaded files	No
form_data	`string`	JSON encoded form data	Yes
browser_timezone	`string`	Browser timezone	No
browser_time	`string`	Browser time	No

Returns

APIResponse with submission data

GET /forms/{form_id}/responses

Get all responses for a form

Parameters

Name	Type	Description	Required
form_id	`string`	Form ID	Yes

Returns

Array of FormResponseModel

GET /forms/{form_id}/responses/{response_id}

Get a specific form response

Parameters

Name	Type	Description	Required
form_id	`string`	Form ID	Yes
response_id	`string`	Response ID	Yes

Returns

FormResponseModel

GET /forms/{form_id}/responses/{response_id}/files/{filename}

Get file data from a form response

Parameters

Name	Type	Description	Required
form_id	`string`	Form ID	Yes
response_id	`string`	Response ID	Yes
filename	`string`	Name of the file	Yes

Returns

Base64 encoded file data

GET /forms/{form_id}/responses/{response_id}/files-as-link/{filename}/{download_filename}

Get file as downloadable link or display in browser

Parameters

Name	Type	Description	Required
form_id	`string`	Form ID	Yes
response_id	`string`	Response ID	Yes
filename	`string`	Internal filename	Yes
download_filename	`string`	Filename for download	Yes
force_download	`boolean`	Force download instead of display	No

Returns

File stream response

GET /forms/{form_id}/export/csv

Export form responses as CSV

Parameters

Name	Type	Description	Required
form_id	`string`	Form ID	Yes

Returns

CSV file stream

GET /forms/{form_id}/export/xlsx

Export form responses as Excel file

Parameters

Name	Type	Description	Required
form_id	`string`	Form ID	Yes

Returns

XLSX file stream

GET /forms/{form_id}/responses/{response_id}/pdf

Generate PDF for a specific form response

Parameters

Name	Type	Description	Required
form_id	`string`	Form ID	Yes
response_id	`string`	Response ID	Yes

Returns

PDF file stream

Zapier Integration API

GET /generate_code

Generate OAuth code for Zapier integration

Parameters

Name	Type	Description	Required
client_id	`string`	OAuth client ID	Yes
user_id	`string`	User ID	Yes

Returns

APIResponse with OAuth code

POST /verify_code

Verify OAuth code and return access token

Parameters

Name	Type	Description	Required
code	`string`	OAuth code	Yes
client_id	`string`	OAuth client ID	Yes
client_secret	`string`	OAuth client secret	Yes
grant_type	`string`	OAuth grant type	Yes
redirect_uri	`string`	OAuth redirect URI	Yes
provider	`string`	OAuth provider	Yes

Returns

JSON response with access token and email

GET /test

Test Zapier OAuth authentication

Parameters

Name	Type	Description	Required
Authorization	`string`	Bearer token	Yes

Returns

Test success response

POST /webhook/subscription

Subscribe to form webhooks

Parameters

Name	Type	Description	Required
hookUrl	`string`	Webhook URL	Yes
form_id	`string`	Form ID	Yes

Returns

Webhook subscription details with ID

DELETE /webhook/subscription

Delete webhook subscription

Parameters

Name	Type	Description	Required
hookUrl	`string`	Webhook URL	Yes
form_id	`string`	Form ID (optional)	No

Returns

Success response

GET /webhook/subscription

Get example data for form webhooks

Parameters

Name	Type	Description	Required
form_id	`string`	Form ID	Yes

Returns

Array of example form submission data

GET /forms

Get all forms for the authenticated Zapier user

Parameters

Name	Type	Description	Required
Authorization	`string`	Bearer token	Yes

Returns

JSON response with array of form objects containing id and title

Workflow API

POST /workflows

Create a new workflow

Parameters

Name	Type	Description	Required
form_id	`string`	Form ID	Yes
connection_id	`string`	Connection ID	Yes
config	`dict`	Workflow configuration	No

Returns

APIResponse with workflow details

Data Models

FormElement

Represents a form element/field

Property	Type	Description	Required	Default
`id`	`string`	Unique identifier	Yes	-
`type`	`string`	Element type (text, email, number, phone, etc.)	Yes	-
`label`	`string`	Display label	No	-
`column_name`	`string`	Database column name	No	-
`value`	`any`	Element value	Yes	-
`required`	`boolean`	Whether field is required	Yes	false
`displayWidth`	`string`	Display width of element	Yes	100%
`hidden`	`boolean`	Whether element is hidden	Yes	false

Page

Represents a single page in a form

Property	Type	Description	Required	Default
`id`	`string`	Unique identifier (ULID)	Yes	-
`name`	`string`	Page name	Yes	-
`type`	`string`	Page type (cover, form, ending)	Yes	form
`elements`	`Array<FormElement>`	List of form elements	Yes	-
`settings`	`object`	Page-specific settings	Yes	-

FormAsQueryResult

Form data with additional query information

Property	Type	Description	Required	Default
`id`	`string`	Form ID	Yes	-
`title`	`string`	Form title	Yes	-
`user_id`	`string`	Owner's user ID	Yes	-
`folder_id`	`string`	Parent folder ID	No	-
`created_at`	`datetime`	Creation timestamp	Yes	-
`updated_at`	`datetime`	Last update timestamp	No	-
`deleted_at`	`datetime`	Deletion timestamp	No	-
`moved_at`	`datetime`	Last move timestamp	No	-
`pages`	`Array<Page>`	Form pages	Yes	-
`settings`	`FormSettings`	Form settings	Yes	-
`styles`	`FormStyles`	Form styles	Yes	-
`favorite`	`boolean`	Whether form is favorited	Yes	false
`published`	`boolean`	Whether form is published	Yes	false
`response_count`	`number`	Number of form responses	No	-
`form_connections`	`string`	Connected integrations	No	-

FormResponseModel

Form submission response data

Property	Type	Description	Required	Default
`id`	`string`	Response ID	Yes	-
`form_id`	`string`	Associated form ID	Yes	-
`response_data`	`Array<object>`	Form submission data	Yes	-
`submitted_at`	`string`	Submission timestamp	Yes	-

FormSettings

Functional settings for the form

Property	Type	Description	Required	Default
`submitButtonText`	`string`	Submit button text	Yes	Submit
`previousButtonText`	`string`	Previous button text	Yes	Previous
`nextButtonText`	`string`	Next button text	Yes	Next

FormStyles

Visual styles for the form

Property	Type	Description	Required	Default
`pageBackgroundColor`	`string`	Page background color	Yes	#ffffff
`formBackgroundColor`	`string`	Form background color	Yes	#FFFAF0
`defaultFontColor`	`string`	Default text color	Yes	#625b5b
`formMaxWidth`	`number`	Maximum form width in pixels	Yes	720