> ## 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

## Available endpoints

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

Base URL: `https://apx.paubox.com/forms`

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

## 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.

Both endpoints documented here are public. They're 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

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 |
| Form management (create, update, delete) | Paubox Forms API key        |

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

## Get started

1. Create a form in the Paubox Forms app.
2. Copy the form's UUID. This is the `form_id` you'll pass to both endpoints.
3. Use the endpoints below to render the form and accept submissions.

<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>
</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 Forms API endpoints require authentication?">
    Both 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.
  </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.
  </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.
  </Accordion>

  <Accordion title="What happens if I send an invalid form_id?">
    Both endpoints return a 404 Not Found response.
  </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 delete the form when you're done testing to keep submission counts clean.
  </Accordion>
</AccordionGroup>