> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paubox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Paubox Forms API

> Build, host, and process HIPAA compliant forms directly inside your application.

The Paubox Forms API lets you build, host, and process HIPAA compliant forms (patient intake, consent, surveys, waivers) directly inside your application. Submissions are stored on Paubox's HITRUST certified infrastructure and visible in your Paubox Forms account.

The Forms API is part of Paubox Forms, Paubox's HIPAA compliant intake form product.

## What you can build with it

Healthcare teams use the Paubox Forms API to:

* Embed patient intake forms inside a portal or app and process responses without storing PHI on their own systems
* Collect signed consent forms tied to appointments, onboarding, or treatment plans
* Securely collect patient data with HIPAA compliant forms
* Create, update, copy, and archive forms programmatically instead of clicking through the Paubox Forms app
* Pull submissions into their own systems, or export them as CSV or PDF for records and reporting

## Available endpoints

Base URL: `https://api.paubox.com/v1/forms`

### Public endpoints

These endpoints are called by respondents loading and submitting forms from end user devices, so they require no API key.

| Method | Endpoint | Purpose | API key |
| - | - | - | - |
| `GET` | `/public/form_data/{form_id}` | Retrieve a form's full definition (HTML, JSON schema, CSS) for rendering to a respondent | No |
| `POST` | `/api/forms/{form_id}/submissions` | Submit a form response, including text fields and file attachments | No |

See the reference: [Get form metadata](/forms/get-form) and [Submit a form response](/forms/submit-form).

### Management endpoints

These endpoints require an API key with the `forms` scope, sent as `Authorization: Bearer YOUR_API_KEY`. See [Authentication](/forms/authentication).

| Method | Endpoint | Purpose | API key |
| - | - | - | - |
| `GET` | `/api/forms` | List your forms, with filtering, search, sorting, and pagination | Yes |
| `POST` | `/api/forms` | Create a form | Yes |
| `GET` | `/api/forms/{form_id}` | Get a form's full definition, including inactive and archived forms | Yes |
| `PUT` | `/api/forms/{form_id}` | Update a form (partial update; omitted fields are unchanged) | Yes |
| `POST` | `/api/forms/copy` | Copy an existing form under a new title | Yes |
| `POST` | `/api/forms/{form_id}/archive` | Archive a form (also deactivates it) | Yes |
| `POST` | `/api/forms/{form_id}/unarchive` | Unarchive a form (does not re-activate it) | Yes |
| `GET` | `/api/forms/stats` | Get form statistics for a customer: active form count and submission counts | Yes |
| `GET` | `/api/forms/{form_id}/submissions` | List submissions for a form, with sorting and pagination | Yes |
| `GET` | `/api/forms/{form_id}/submissions/submission-csv` | Export all submissions of a form as CSV | Yes |
| `GET` | `/api/forms/{form_id}/submissions/submission-csv/{submission_id}` | Export a single submission as CSV | Yes |
| `GET` | `/api/forms/{form_id}/submissions/{submission_id}/submission-pdf` | Export a single submission as PDF | Yes |

See the reference: [List forms](/forms/list-forms), [Create a form](/forms/create-form), [Get a form](/forms/get-form-details), [Update a form](/forms/update-form), [Copy a form](/forms/copy-form), [Archive a form](/forms/archive-form), [Unarchive a form](/forms/unarchive-form), [Get form statistics](/forms/form-stats), [List form submissions](/forms/list-submissions), [Export submissions as CSV](/forms/export-submissions-csv), [Export a submission as CSV](/forms/export-submission-csv), and [Export a submission as PDF](/forms/export-submission-pdf).

## How it handles HIPAA and security

The Paubox Forms API runs on the same HIPAA compliant infrastructure as the rest of the Paubox platform. Form definitions and submissions are stored in Paubox's secure environment. Paubox signs a business associate agreement (BAA) with every customer.

The two public endpoints are called by respondents loading and submitting forms from end user devices, where authentication wouldn't be feasible. The form's UUID acts as access control:

* Form IDs are UUIDs, which makes them difficult to enumerate
* Submissions are capped at 250 MB total, including form fields and any file attachments

All management endpoints require an API key with the `forms` scope, and a key can only access forms belonging to its own customer account.

Paubox Forms is included with paid Paubox accounts, including Paubox Email Suite.

## Authentication

| Endpoint | Authentication |
| - | - |
| `GET /public/form_data/{form_id}` | Public, no API key required |
| `POST /api/forms/{form_id}/submissions` | Public, no API key required |
| All management endpoints | `Authorization: Bearer YOUR_API_KEY` with the `forms` scope |

The two public endpoints are intentionally unauthenticated. Respondents fill out forms from end user devices, so authentication happens at the form definition layer rather than the request layer.

Management endpoints (listing, creating, updating, copying, archiving forms, and reading or exporting submissions) require a scoped API key generated in the Paubox dashboard. The key must carry the `forms` scope; a key without it receives a `401 Unauthorized` response, and a valid key requesting another customer's resources receives `403 Forbidden`. See [Authentication](/forms/authentication) for details.

## Get started

1. Create a form in the Paubox Forms app, or generate an API key with the `forms` scope and create one with `POST /api/forms`.
2. Copy the form's UUID. This is the `form_id` you'll pass to the endpoints.
3. Use the public endpoints to render the form and accept submissions, and the management endpoints to read and export what comes in.

<CardGroup cols={2}>
  <Card title="Get form metadata" icon="file-lines" href="/forms/get-form">
    Retrieve the form's HTML, JSON schema, and CSS for rendering to a respondent.
  </Card>

  <Card title="Submit a form response" icon="paper-plane" href="/forms/submit-form">
    Post field values and file attachments to the submissions endpoint.
  </Card>

  <Card title="Authentication" icon="key" href="/forms/authentication">
    Generate a scoped API key and authenticate to the management endpoints.
  </Card>

  <Card title="List form submissions" icon="inbox" href="/forms/list-submissions">
    Retrieve submissions programmatically, or export them as CSV or PDF.
  </Card>
</CardGroup>

## FAQs

<AccordionGroup>
  <Accordion title="Is the Paubox Forms API HIPAA compliant?">
    Yes. Form definitions and submissions are stored on Paubox's HITRUST certified, HIPAA compliant infrastructure. All data is encrypted in transit and at rest, and Paubox signs a business associate agreement (BAA) with every customer.
  </Accordion>

  <Accordion title="Why don't the public Forms API endpoints require authentication?">
    The two public endpoints are called by respondents loading and submitting forms from end user devices, where authentication wouldn't be feasible. The form's UUID acts as access control: each form has a unique UUID generated by Paubox when you create the form. All management endpoints require an API key with the `forms` scope.
  </Accordion>

  <Accordion title="Can the Paubox Forms API collect signatures?">
    Yes. Forms can be marked as signable. The `signable` and `signature_confirmation_label` fields on the form metadata indicate signature behavior, and a signature confirmation is recorded with the submission. PDF exports of submissions include the signature image.
  </Accordion>

  <Accordion title="Can I include file attachments in a form submission?">
    Yes. The `attachments` array on `POST /api/forms/{form_id}/submissions` accepts file objects with a `name` and base64 encoded `content`. The maximum total submission size is 250 MB.
  </Accordion>

  <Accordion title="Where do form submissions go?">
    Submissions are stored in your Paubox Forms account and visible in the app. You can configure email notifications to designated recipients on each submission, retrieve submissions with `GET /api/forms/{form_id}/submissions`, or export them as CSV or PDF.
  </Accordion>

  <Accordion title="What happens if I send an invalid form_id?">
    It depends on the endpoint. The public form fetch (`GET /public/form_data/{form_id}`), update, copy, list submissions, and both CSV export endpoints return `404 Not Found`. The management `GET /api/forms/{form_id}`, the public submission endpoint, and the PDF export currently return `500` for an unknown form ID. The archive and unarchive endpoints do not verify that the form exists and return a `200` success response either way.
  </Accordion>

  <Accordion title="What format do form fields take?">
    The `form_data` object on a submission accepts key-value pairs where keys match the field names defined in the form's schema. Retrieve the schema by calling `GET /public/form_data/{form_id}` and reading the `form_json` field.
  </Accordion>

  <Accordion title="Is there a sandbox for testing the Forms API?">
    Test against any form in your Paubox Forms account. Deactivate or archive the form when you're done testing to keep submission counts clean.
  </Accordion>
</AccordionGroup>

## Community & support

<CardGroup cols={2}>
  <Card title="Q&A" icon="comments" href="https://github.com/Paubox/community/discussions/categories/paubox-forms">
    Ask usage questions in the Paubox Community.
  </Card>

  <Card title="Ideas" icon="lightbulb" href="https://github.com/Paubox/community/discussions/categories/ideas">
    Propose features and improvements.
  </Card>
</CardGroup>

<Warning>
  Never post PHI, recipient addresses, or message content in public threads. Account, billing, or anything sensitive goes to [support@paubox.com](mailto:support@paubox.com).
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.