> ## 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.
# Create a form with the Forms API
> Creates a new form. Returns the UUID of the created form.
## OpenAPI
````yaml openapi-forms POST /api/forms
openapi: 3.0.0
info:
title: Paubox Forms API
description: >
The Paubox Forms API has two kinds of endpoints. Public, respondent-facing
endpoints (retrieving a form definition for rendering and submitting a form
response) require no authentication. Authenticated management endpoints
(creating, listing, updating, copying, archiving forms, and reading or
exporting submissions) require a Paubox API key with the "forms" scope, sent
as `Authorization: Bearer YOUR_API_KEY`. API keys are generated in the
Paubox dashboard.
version: 1.0.0
servers:
- url: https://api.paubox.com/v1/forms
description: Paubox Forms API
security: []
tags:
- name: Forms
description: Retrieve form definitions and accept submissions
- name: Form management
description: Create, list, update, copy, and archive forms (requires API key)
- name: Submissions
description: List and export form submissions (requires API key)
paths:
/api/forms:
post:
tags:
- Form management
summary: Create a form
description: |
Creates a new form. Returns the UUID of the created form.
operationId: createForm
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateFormRequest'
examples:
basic:
summary: Minimal form
value:
title: Patient Intake Form
form_json:
body:
- type: TextInput
id: pi-01
properties:
field_name: first_name
text: First name
required: true
input_mask: Any
- type: Button
id: pi-02
properties:
margin: 4px
full_width: true
customer_id: 123
version: 1
full:
summary: Marketing form with notifications
value:
title: Newsletter Signup
description: Sign up for our monthly newsletter.
form_json:
body:
- type: TextInput
id: nl-01
properties:
field_name: email
text: Email
required: true
input_mask: Email
- type: Button
id: nl-02
properties:
margin: 4px
form_html:
form_css: 'form { font-family: sans-serif; }'
customer_id: 123
version: 1
recipient: marketing@example.com
subscription_list_id: b3f9c2d1-4a5e-4f6b-8c7d-9e0f1a2b3c4d
type: marketing_form
active: true
responses:
'200':
description: Form created
content:
application/json:
schema:
type: object
properties:
id:
type: string
format: uuid
description: UUID of the new form
examples:
example:
summary: Example response
value:
id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
'401':
description: Missing or invalid API key, or the key lacks the "forms" scope
'403':
description: The API key does not have access to the requested customer
'422':
description: >
`form_json` is not a schema the form renderer can draw. The message
names the offending component's index and type, for example:
"form_json.body[1].type `DatePicker` is not a component the form
renderer knows". A missing `body` array reports "form_json must have
a `body` array of components".
content:
application/json:
schema:
$ref: '#/components/schemas/FormJsonValidationError'
examples:
fields_shape:
summary: Legacy `fields` payload
value:
message: >-
form_json must have a `body` array of components; a form
without one renders as an empty page
security:
- bearerAuth: []
components:
schemas:
CreateFormRequest:
type: object
required:
- title
- form_json
- customer_id
- version
properties:
title:
type: string
description: Title of the form
form_json:
type: object
description: >
The form's schema. Must be an object containing a `body` array of
components; the renderer reads `body` and ignores every other
top-level key. A payload shaped any other way — notably a `fields`
array — is rejected with 422. Empty `body` is allowed: a draft
legitimately has no components yet.
properties:
body:
type: array
description: >
Ordered list of components. Each entry is an object with a
string `type` drawn from the list below, an `id`, and an
optional `properties` object.
items:
type: object
required:
- type
properties:
type:
type: string
description: >
Component type. Case-sensitive — note `Radiobutton` has a
lowercase `b`, unlike the others.
enum:
- Text
- Divider
- TextInput
- TextArea
- Dropdown
- Checkboxes
- Radiobutton
- FileUpload
- Signature
- Button
- Conditional
- Logo
id:
type: string
description: Identifier for the component, unique within the form.
properties:
type: object
description: >
Per-component settings such as `field_name`, `text`,
`required` and `input_mask`. Not validated on write.
required:
- body
customer_id:
type: integer
description: Your Paubox customer ID
version:
type: integer
description: Form schema version
description:
type: string
form_html:
type: string
form_css:
type: string
recipient:
type: string
description: |
Comma-separated email addresses notified on each submission.
signable:
type: boolean
default: false
description: Whether the form collects a signature
signature_confirmation_label:
type: string
subscription_list_id:
type: string
description: >
ID of the connected Marketing contact list. For marketing forms, new
subscribers are added to this list.
type:
type: string
description: Form type, for example `marketing_form`
active:
type: boolean
default: false
submission_count:
type: integer
default: 0
FormJsonValidationError:
type: object
description: >
Returned with 422 when `form_json` is not a schema the form renderer can
draw. Introduced in pb_rforms v1.11.0; before that release these
payloads were accepted and the resulting form rendered as an empty page.
properties:
message:
type: string
description: >
Human-readable reason, naming the offending component's index and
type where applicable.
example:
message: >-
form_json.body[1].type `DatePicker` is not a component the form
renderer knows; expected one of: Text, Divider, TextInput, TextArea,
Dropdown, Checkboxes, Radiobutton, FileUpload, Signature, Button,
Conditional, Logo
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >
Paubox API key sent as `Authorization: Bearer YOUR_API_KEY`. API keys
are created in the Paubox dashboard and must have the "forms" scope; a
key without the forms scope receives 401 Unauthorized. A valid key used
against a resource that belongs to a different customer receives 403
Forbidden.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.