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

# Node.js SDK forms client

> Retrieve Paubox Form schemas and submit form responses using the Node.js SDK.

`getForm` and `submitForm` do not require API credentials. The form management methods require an API key with the `forms` scope (see [Manage forms](#manage-forms)). Forms are identified by a UUID that you obtain from the Paubox dashboard.

## Create the service

```javascript theme={null}
const pbMail       = require('paubox-node');
const formsService = pbMail.formService();
```

## Get a form

Retrieve a form's metadata, field schema, and rendered HTML/CSS:

```javascript theme={null}
const form = await formsService.getForm('your-form-uuid');

console.log('Title:', form.title);
console.log('HTML:',  form.form_html);
```

Key fields in the response:

| Field | Description |
| - | - |
| `title` | Display name of the form |
| `form_json` | Parsed field schema |
| `form_html` | Rendered HTML for embedding |
| `form_css` | Associated stylesheet |
| `active` | Whether the form is accepting submissions |
| `submission_count` | Number of submissions received |

The Promise rejects with a 404 error if the form UUID is invalid.

## Submit a form

```javascript theme={null}
await formsService.submitForm('your-form-uuid', {
  first_name: 'Jane',
  last_name:  'Smith',
  email:      'jane@example.com'
});
// Resolves to null on success (HTTP 201)
```

### Submitting with file attachments

The maximum total request size is 250 MB.

```javascript theme={null}
const fs = require('fs');

const attachments = [
  {
    name:    'consent.pdf',
    content: fs.readFileSync('consent.pdf').toString('base64')
  }
];

await formsService.submitForm(
  'your-form-uuid',
  { first_name: 'Jane' },
  attachments
);
```

Each attachment is an object with two fields:

| Field | Description |
| - | - |
| `name` | File name including extension |
| `content` | Base64-encoded file content |

## Manage forms

These methods need a `forms`-scoped API key, sent as `Authorization: Bearer YOUR_API_KEY`. Create the service with `pbMail.formService({ apiKey: 'YOUR_API_KEY' })`, or set `FORMS_API_KEY` in the environment. Without a key they throw an error.

| Method | Description |
| - | - |
| `listForms(params)` | List forms; `params.customer_id` is required |
| `createForm(formAttributes)` | Create a form |
| `getFormById(formId)` | Get any of your forms, including archived and inactive ones |
| `updateForm(formId, updates)` | Update a form |
| `archiveForm(formId)` / `unarchiveForm(formId)` | Archive or restore a form |
| `copyForm(formId, title)` | Copy a form under a new title |
| `getFormStats(customerId)` | Form and submission counts; `customerId` is optional |
| `listSubmissions(formId, params)` | List a form's submissions |
| `exportSubmissionsCsv(formId, submissionId)` | Export all submissions, or one when `submissionId` is set, as CSV |
| `exportSubmissionPdf(formId, submissionId)` | Export one submission as PDF |

```javascript theme={null}
const formsAdmin = pbMail.formService({ apiKey: 'YOUR_API_KEY' });

const list = await formsAdmin.listForms({ customer_id: 12345, active: true, items: 25 });
list.results.forEach(f => console.log(`${f.id}: ${f.title}`));
```

## Error handling

```javascript theme={null}
try {
  const form = await formsService.getForm('your-form-uuid');
  await formsService.submitForm('your-form-uuid', formData);
} catch (err) {
  console.error('Forms error:', err.message);
}
```

The Promise rejects on HTTP 400 (bad request) and 404 (form not found).


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