Papereg API Documentation

REST JSON API v1 — Token-based authentication

JRDL Docs Home

Authentication

All API requests require a Bearer token in the Authorization header.

Create API tokens in your Workspace Settings → API Tokens section. Each token is scoped to a single workspace. 

curl https://your-domain.com/api/v1/forms -H "Authorization: Bearer pprg_your_token_here"

Token Format

  • Tokens start with the pprg_ prefix
  • Shown only once at creation — store securely
  • Expiration options: 30 days, 90 days, 1 year, or unlimited
  • Revoke anytime from Workspace Settings

HTTP Status Codes

Code Meaning
200 Success
201 Created
204 No Content (successful delete)
401 Unauthorized — missing, invalid, or expired token
403 Forbidden — API access not available on current plan, or insufficient permission
404 Not Found
422 Validation Error

Forms

GET /api/v1/forms

List all forms in the workspace

Query parameters:

  • status — Filter by status: active, archived
  • search — Search forms by name
  • page — Page number (default: 1)
  • per_page — Items per page (default: 30, max: 100)
  • include_field_count=true — Include field count in response
  • include_submission_count=true — Include submission count
GET /api/v1/forms/:form_uid

Get a form with its fields

Returns form details with all associated fields.

POST /api/v1/forms

Create a new form

Request Body 
{"form": {"name": "Employee Onboarding", "description": "New hire checklist"}}

Optional fields: is_public, is_enabled, is_published

PUT /api/v1/forms/:form_uid

Update a form

Request Body 
{"form": {"name": "Updated Name", "status": "archived"}}
DELETE /api/v1/forms/:form_uid

Delete a form

Returns 204 No Content on success.

PDF Upload & Extract

POST /api/v1/forms/from-pdf

Upload a PDF and auto-create a form with AI-extracted fields

Send as multipart/form-data with the PDF as the file field. 

curl -X POST https://your-domain.com/api/v1/forms/from-pdf -H "Authorization: Bearer pprg_your_token" -F "file=@/path/to/form.pdf" -F "name=My Form Name"

Optional parameters: name (defaults to filename), description

Max file size: 50 MB. Only PDF files accepted.

Form Fields

GET /api/v1/forms/:form_uid/fields

List all fields for a form

POST /api/v1/forms/:form_uid/fields

Add a field to a form

Request Body 
{"field": {"name": "phone", "field_type": "tel", "label": "Phone Number", "required": false, "placeholder": "(555) 123-4567"}}
Input field types
text textarea email number tel url checkbox radio select multiselect date time datetime file signature
Display field types
title paragraph static_text instruction info_block divider row image external_link embed tab_group section
Layout parameters
  • row_group — Integer; fields sharing the same value appear side-by-side
  • col_span — Grid width: 3, 4, 6, 8, or 12 (default 12)
  • access_roles — Array of roles that can see the field: ["manager", "supervisor", "user"]
POST /api/v1/forms/:form_uid/fields/reorder

Reorder fields by updating positions

{"field_positions": {"123": 0, "456": 1, "789": 2}}
PUT /api/v1/forms/:form_uid/fields/:id

Update a field

DELETE /api/v1/forms/:form_uid/fields/:id

Delete a field

Submissions (Records)

GET /api/v1/forms/:form_uid/submissions

List submissions (paginated)

Query parameters:

  • page — Page number (default: 1)
  • per_page — Items per page (default: 30, max: 100)
  • status — Filter: draft, submitted, approved, rejected
  • search — Search by UID or field values
  • from_date — Filter from date (YYYY-MM-DD)
  • to_date — Filter to date (YYYY-MM-DD)
  • sort_field — Field ID to sort by
  • sort_direction — asc or desc (default: asc)
  • include_deleted — Include soft-deleted (true/false)
GET /api/v1/forms/:form_uid/submissions/:uid

Get a single submission with named field data

Response 
{"data": {"uid": "AZy_uzvLdM2...", "status": "submitted", "submitted_at": "2026-03-05T20:40:44", "field_data": {"full_name": "John Doe", "email": "john@example.com"}}}
POST /api/v1/forms/:form_uid/submissions

Create a submission with field data

Request Body 
{"submission": {"data": {"full_name": "Jane Smith", "email": "jane@example.com"}, "submit": true}}

Set "submit": true to immediately submit. Otherwise the submission is created as a draft. Field data keys must match field name values.

PUT /api/v1/forms/:form_uid/submissions/:uid

Update submission data

Request Body 
{"submission": {"data": {"full_name": "Jane Doe"}}}
POST /api/v1/forms/:form_uid/submissions/:uid/submit

Submit a draft submission

Changes status from draft to submitted.

POST /api/v1/forms/:form_uid/submissions/:uid/approve

Approve a submitted submission

Requires change_status permission.

POST /api/v1/forms/:form_uid/submissions/:uid/reject

Reject a submitted submission

Requires change_status permission.

POST /api/v1/forms/:form_uid/submissions/:uid/restore

Restore a soft-deleted submission

Requires delete_any_submission permission.

DELETE /api/v1/forms/:form_uid/submissions/:uid

Soft-delete a submission

Returns 204 No Content.

Submission Exports

Download all matching submissions as a file. Requires export_submissions permission. Supports the same search, status, sort_field, sort_direction, and include_deleted query params as the submissions list.

GET /api/v1/forms/:form_uid/export/csv

Download submissions as CSV

GET /api/v1/forms/:form_uid/export/excel

Download submissions as Excel (.xlsx)

GET /api/v1/forms/:form_uid/export/markdown

Download submissions as Markdown table

Linked Forms (Workflow)

Manage form chains so users are guided from one form to the next after submitting. Requires edit_forms permission for write operations.

GET /api/v1/forms/:form_uid/links

List linked forms in order

POST /api/v1/forms/:form_uid/links

Add a linked form

{"linked_form_uid": "abc123"}
DELETE /api/v1/forms/:form_uid/links/:link_id

Remove a linked form

PUT /api/v1/forms/:form_uid/links/reorder

Reorder linked forms

{"ordered_link_ids": [3, 1, 2]}

Event Actions (Automations)

Manage automated actions triggered by submission lifecycle events. Requires manage_event_actions permission.

GET /api/v1/forms/:form_uid/event-actions

List event actions for a form

GET /api/v1/forms/:form_uid/event-actions/:id

Get event action details

POST /api/v1/forms/:form_uid/event-actions

Create an event action

Valid events:

submission.created submission.submitted submission.approved submission.rejected submission.deleted submission.restored

Action types:

send_email webhook
PUT /api/v1/forms/:form_uid/event-actions/:id

Update an event action

DELETE /api/v1/forms/:form_uid/event-actions/:id

Delete an event action

POST /api/v1/forms/:form_uid/event-actions/:id/toggle

Enable or disable an event action

GET /api/v1/forms/:form_uid/event-actions/:id/logs

List execution logs for an action

Query param: limit (default: 20, max: 100)

Workspace

GET /api/v1/workspace

Get current workspace info (name, plan, member count)

GET /api/v1/workspace/members

List workspace members with roles

Requires manage_workspace permission.

Pages

Manage workspace pages. Read endpoints are available to all members. Write operations require manage_pages permission.

GET /api/v1/pages

List all pages

GET /api/v1/pages/:slug

Get page content

POST /api/v1/pages

Create a page

{"page": {"title": "Getting Started", "slug": "getting-started", "content": "# Markdown...", "is_published": true}}
PUT /api/v1/pages/:slug

Update a page

DELETE /api/v1/pages/:slug

Delete a page

Reports

Access preset analytics reports. Requires view_reports permission. Export endpoints require export_reports.

GET /api/v1/reports

List available reports for this workspace (based on preset detection)

GET /api/v1/reports/:report_slug

Get report data (summary + charts + rows)

Query params: start_date, end_date (YYYY-MM-DD), year

GET /api/v1/reports/:report_slug/export/pdf

Download report as PDF

GET /api/v1/reports/:report_slug/export/excel

Download report as Excel

Custom Reports

Create, manage, and execute user-defined reports pulling data from any form(s). Requires view_reports to view, create_custom_reports to create, and export_reports for exports. See the JRDL Documentation for the full JSON Report Definition Language schema reference.

GET /api/v1/custom-reports

List custom reports visible to the token's user (own drafts + all published)

GET /api/v1/custom-reports/:uid

Get report with executed results (summary cards, charts, tables)

Query params: start_date, end_date (YYYY-MM-DD)

POST /api/v1/custom-reports

Create a custom report

Request Body 
{"custom_report": {"name": "My KPI Report", "description": "...", "is_published": false, "config": {"layout": {"summary_cards": [], "charts": [], "tables": []}}, "sources": [{"alias": "intake", "form_id": 42, "field_mappings": {"patient_name": "full_name"}}]}}
PUT /api/v1/custom-reports/:uid

Update a custom report (creator or owner only)

Accepts same body as create. Pass sources to replace all sources atomically.

DELETE /api/v1/custom-reports/:uid

Soft-delete a custom report (creator or owner only)

Returns 204 No Content on success.

GET /api/v1/custom-reports/:uid/export

Export report as a portable JSON Report Definition Language (JRDL) file

Returns a downloadable .json file containing the full report definition including layout, sources, and field mappings. Can be imported into any workspace.

POST /api/v1/custom-reports/import

Import a report from a JRDL JSON definition

Send as multipart/form-data with the JSON as definition (file upload or raw JSON string). Pass allow_partial=true to import even when some source forms are missing.

Returns 422 with missing_forms array if sources can't be matched and allow_partial is not set.

GET /api/v1/custom-reports/:uid/export/pdf

Download custom report as PDF

Query params: start_date, end_date (YYYY-MM-DD)

GET /api/v1/custom-reports/:uid/export/excel

Download custom report as Excel (.xlsx)

Query params: start_date, end_date (YYYY-MM-DD)

Batch Upload

Upload multiple scanned documents (PDF, JPG, PNG) to auto-create submission records via AI extraction.

POST /api/v1/forms/:form_uid/batch-upload

Start a batch upload

Send as multipart/form-data with files[] fields (up to 50 files, max 20MB each). Optional: auto_submit=true to auto-submit extracted records.

GET /api/v1/forms/:form_uid/batch-uploads

List batch uploads for a form

GET /api/v1/forms/:form_uid/batch-uploads/:id

Get batch upload status and per-file results

Poll this endpoint to track progress. Item statuses: queued → extracting → created | failed.

Submission Extraction

Upload a filled document and use AI to extract field values into an existing submission.

POST /api/v1/forms/:form_uid/submissions/:uid/extract

Upload a filled document for AI extraction

Send as multipart/form-data with a file field. Accepted types: PDF, JPEG, PNG. Max size: 20MB. Extraction runs asynchronously — poll the status endpoint.

GET /api/v1/forms/:form_uid/submissions/:uid/extraction

Get extraction status and result

Statuses: uploaded → extracting → extracted | failed. The extraction_result field contains a map of field names to extracted values.

Apps & Connections

Read-only access to installed apps and form-to-app sync status. Requires configure_apps permission for app endpoints and manage_form_connections for connection endpoints.

GET /api/v1/apps

List installed apps in the workspace

GET /api/v1/apps/:slug

Get installed app details and config status

GET /api/v1/forms/:form_uid/connections

List form-to-app connections

GET /api/v1/forms/:form_uid/connections/:id/sync-logs

Get sync logs for a connection

Error Responses

All errors follow a consistent format:

{"errors": {"detail": "Not found"}}

Validation errors return field-specific messages:

{"errors": {"name": ["can't be blank"], "status": ["is invalid"]}}

Papereg API v1 — Back to Home