From 5e25e5d92855caf845070351b6f9bc4191177570 Mon Sep 17 00:00:00 2001 From: Nathan Broadbent Date: Sun, 10 Aug 2025 22:03:03 +1200 Subject: [PATCH 01/18] added pdf generation guide --- api-guide/generate-pdfs.mdx | 225 ++++++++++++++++++++++++++++++++++++ 1 file changed, 225 insertions(+) create mode 100644 api-guide/generate-pdfs.mdx diff --git a/api-guide/generate-pdfs.mdx b/api-guide/generate-pdfs.mdx new file mode 100644 index 0000000..355c204 --- /dev/null +++ b/api-guide/generate-pdfs.mdx @@ -0,0 +1,225 @@ +--- +title: Generate PDFs +description: Generate PDFs from templates using the DocSpring API +sidebar: + order: 3 +--- + +import { Tabs, TabItem, Aside, LinkCard } from '@astrojs/starlight/components' + +The DocSpring API generates PDFs by filling templates with your data. Templates can be either: + +- **PDF templates** - Upload a PDF and add fillable fields in our visual editor +- **HTML/CSS templates** - Write HTML and CSS for complete control over layout + +When you create a template, you define fields with names and types (text, number, date, signature, etc.). +These fields determine the structure of the data you send to generate PDFs. +The API validates your data against the template's field schema and fills the template to create your PDF. + +### API Endpoint + +``` +POST /api/v1/templates/{template_id}/submissions +``` + +### Key Parameters + +- `data` - Field data matching your template schema +- `test` - Generate a free watermarked test PDF (`true`) or live PDF (`false`) +- `metadata` - Additional data like user IDs, included in webhook requests +- `version` - Template version to use (`draft`, `latest`, or specific version like `1.2.3`) +- `wait` - Wait for PDF processing to complete (`true`) or return immediately (`false`). Default: `true` +- `editable` - Generate an editable PDF with fillable form fields (`true`) or static PDF (`false`). Uses template default if not specified +- `expires_in` - Number of seconds before the submission expires after processing +- `data_requests` - Request additional information or signatures from recipients +- `field_overrides` - Override field settings like `required` for specific fields + +
+ + +## Batch PDF Generation + +Generate up to 50 PDFs in a single request, each potentially using different templates and data. + +### API Endpoint + +``` +POST /api/v1/submissions/batches +``` + +### Example Request + +```json +{ + "submissions": [ + { + "template_id": "tpl_abc123", + "data": { "name": "John Smith" }, + "test": true + }, + { + "template_id": "tpl_xyz789", + "data": { "name": "Jane Doe" }, + "test": false + } + ] +} +``` + + + +## Synchronous vs Asynchronous Processing + +### Synchronous (Default) + +By default, the API waits for the PDF to be generated before returning: + +```javascript +// Wait for PDF generation (default behavior) +const response = await client.generatePdf(templateId, { + data: { name: "John Smith" } +}) +console.log(response.submission.download_url) // PDF is ready +``` + +### Asynchronous + +Set `wait=false` to return immediately and process in the background: + +```javascript +// Return immediately with pending submission +const response = await client.generatePdf(templateId, { + data: { name: "John Smith" }, + wait: false +}) + +// Poll for completion every few seconds +const submission = await client.getSubmission(response.submission.id) +``` + + + +## Customization Options + +### PDF Title and Filename + +You can customize both the PDF title (shown in PDF reader applications) and the filename in the download URL via metadata: + +```json +{ + "data": { "name": "John Smith" }, + "metadata": { + "pdf_title": "Employment Contract - John Smith", + "pdf_filename": "contract_2024_01_15" + } +} +``` + +- `pdf_title` - Sets the title shown in PDF reader applications (defaults to template name) +- `pdf_filename` - Sets the filename in the download URL (DocSpring adds `.pdf` automatically) + - Default URL: `/submissions/.pdf` + - Custom URL: `/submissions//contract_2024_01_15.pdf` + - Max 128 characters, allowed: `0-9 A-Z a-z - _ .` (other characters replaced with `_`) + +### Field Overrides + +Override template field settings per submission: + +```json +{ + "data": { "name": "John Smith" }, + "field_overrides": { + "signature": { + "required": false + } + } +} +``` + +### Handling Truncated Text + +If text doesn't fit in a field and the field's "Overflow" option is set to "Truncate", DocSpring stores the truncated text in the submission response: + +```json +{ + "submission": { + "truncated_text": { + "title": ["text that could not fit in the field"] + } + } +} +``` + +This is useful for forms with addendum pages - you can check `truncated_text` and generate additional pages when needed. + +### Special Newline Characters + +If your integration can't send literal newline characters (`\n`), use `%%LF%%` as a replacement: + +```json +{ + "address": "123 Main Street%%LF%%Suite 100%%LF%%New York, NY 10001" +} +``` + +This renders in the PDF as: +``` +123 Main Street +Suite 100 +New York, NY 10001 +``` + +## Data Requests + +Request additional information or electronic signatures from users before generating the PDF: + +```json +{ + "data": { "name": "John Smith" }, + "data_requests": [ + { + "name": "John Smith", + "email": "john@example.com", + "fields": ["signature", "date"] + } + ] +} +``` + + + +## Related Resources + + + + + + From 16f9fc80eda5fe42bed4745340307a8b3387f48c Mon Sep 17 00:00:00 2001 From: Nathan Broadbent Date: Sun, 10 Aug 2025 22:31:20 +1200 Subject: [PATCH 02/18] added api-guide/combine-pdfs.mdx --- api-guide/combine-pdfs.mdx | 153 +++++++++++++++++++++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 api-guide/combine-pdfs.mdx diff --git a/api-guide/combine-pdfs.mdx b/api-guide/combine-pdfs.mdx new file mode 100644 index 0000000..0f4cb4b --- /dev/null +++ b/api-guide/combine-pdfs.mdx @@ -0,0 +1,153 @@ +--- +title: Combine PDFs +description: Merge multiple PDFs into a single document with DocSpring +sidebar: + order: 4 +--- + +import { LinkCard } from '@astrojs/starlight/components' + +Combine multiple PDFs from different sources into a single merged document. + +## Endpoint + +``` +POST /api/v1/combined_submissions +``` + +## Source Types + +You can combine PDFs from various sources: + +### Submissions +Generated PDFs from template submissions: +```json +{ "type": "submission", "id": "sub_1234567890abcdef01" } +``` + +### Combined Submissions +Previously combined PDFs: +```json +{ "type": "combined_submission", "id": "com_1234567890abcdef01" } +``` + +### Templates +Original template PDFs (unfilled): +```json +{ "type": "template", "id": "tpl_1234567890abcdef01" } +{ "type": "template", "id": "tpl_1234567890abcdef01", "template_version": "1.2.3" } +``` + +### Custom Files +Uploaded PDF files: +```json +{ "type": "custom_file", "id": "cfi_1234567890abcdef01" } +``` + +### URLs +PDFs from external URLs: +```json +{ "type": "url", "url": "https://example.com/document.pdf" } +``` + +## Example Request + +```json +{ + "source_pdfs": [ + { "type": "submission", "id": "sub_1234567890abcdef01" }, + { "type": "template", "id": "tpl_1234567890abcdef01" }, + { "type": "url", "url": "https://example.com/terms.pdf" } + ], + "metadata": { + "document_type": "complete_package", + "pdf_filename": "complete_contract_package" + } +} +``` + +## Key Features + +### Template Versions +For template sources, specify versions: +- `"template_version": "draft"` - Use draft version +- `"template_version": "latest"` - Use latest published version (default) +- `"template_version": "1.2.3"` - Use specific version + +### Custom Filename +Set a custom PDF filename via metadata: +```json +{ + "metadata": { + "pdf_filename": "merged_documents_2024" + } +} +``` + +The download URL becomes: +`/combined_submissions/{id}/merged_documents_2024.pdf` + +**Filename rules:** +- Max 128 characters +- Allowed: `0-9 A-Z a-z - _ .` +- Other characters replaced with `_` + +### Free to Use +Combining PDFs is free, but source submission PDFs count toward your monthly usage. + +## Use Cases + +### Multi-Page Forms +Combine multiple template submissions for complex forms: +```json +{ + "source_pdfs": [ + { "type": "submission", "id": "sub_application_form" }, + { "type": "submission", "id": "sub_supporting_docs" }, + { "type": "template", "id": "tpl_terms_and_conditions" } + ] +} +``` + +### Document Packages +Create complete document packages with cover pages, forms, and attachments: +```json +{ + "source_pdfs": [ + { "type": "template", "id": "tpl_cover_page" }, + { "type": "submission", "id": "sub_main_form" }, + { "type": "url", "url": "https://company.com/legal/terms.pdf" } + ] +} +``` + +### Addendum Pages +Handle form fields with truncated text by generating additional pages: +```json +{ + "source_pdfs": [ + { "type": "submission", "id": "sub_main_form" }, + { "type": "submission", "id": "sub_addendum_page" } + ] +} +``` + + + +## Related Resources + + + + \ No newline at end of file From f78cfaf86d315f9487c0175f1b298d4fd709ef4d Mon Sep 17 00:00:00 2001 From: Nathan Broadbent Date: Mon, 11 Aug 2025 02:06:30 +1200 Subject: [PATCH 03/18] update auth and comparison pages --- api-guide/authentication.mdx | 70 +++++-------------------------- forms/compare-docspring-forms.mdx | 52 +++++++++-------------- 2 files changed, 31 insertions(+), 91 deletions(-) diff --git a/api-guide/authentication.mdx b/api-guide/authentication.mdx index 5e65f95..1634dff 100644 --- a/api-guide/authentication.mdx +++ b/api-guide/authentication.mdx @@ -9,18 +9,6 @@ import { Tabs, TabItem, Code, LinkCard } from '@astrojs/starlight/components' import fs from 'fs' import path from 'path' -export const authenticationExamples = { - javascript: await getCodeSample('javascript', 'test_authentication', 'js'), - typescript: await getCodeSample('typescript', 'test_authentication', 'ts'), - ruby: await getCodeSample('ruby', 'test_authentication', 'rb'), - python: await getCodeSample('python', 'test_authentication', 'py'), - php: await getCodeSample('php', 'test_authentication', 'php'), - java: await getCodeSample('java', 'test_authentication', 'java'), - csharp: await getCodeSample('csharp', 'test_authentication', 'cs'), - go: await getCodeSample('go', 'test_authentication', 'go'), - elixir: await getCodeSample('elixir', 'test_authentication', 'exs'), -} - export async function getCodeSample(language, filename, extension) { const filePath = path.join( process.cwd(), @@ -44,12 +32,12 @@ DocSpring uses API tokens for authentication. You can authenticate using HTTP ba Use your API token ID as the username, and the API token secret as the password. -## Environment Variables +### Environment Variables All DocSpring API clients support authentication via environment variables. Set the following environment variables, and the client will automatically use them: @@ -76,7 +64,7 @@ const client = new DocSpring.Client(); // Automatically uses process.env client = docspring.Client() # Automatically uses os.environ ``` -## HTTP Basic Authentication +### HTTP Basic Authentication "HTTP basic authentation" means that you need to send an `Authorization` header with the value `Basic` followed by `token_id:token_secret` in Base64 encoding. @@ -98,49 +86,13 @@ curl -H "Authorization: Basic QVBJX1RPS0VOX0lEOkFQSV9UT0tFTl9TRUNSRVQ=" \ https://sync.api.docspring.com/api/v1/authentication ``` -## Test Authentication - -Our API includes an `/authentication` endpoint that you can use to make sure your API tokens are valid. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +--- - - - +### Next Steps - - - - + diff --git a/forms/compare-docspring-forms.mdx b/forms/compare-docspring-forms.mdx index 7c8bc2b..216861c 100644 --- a/forms/compare-docspring-forms.mdx +++ b/forms/compare-docspring-forms.mdx @@ -7,25 +7,32 @@ sidebar: import { LinkCard, Aside, Code, Icon } from '@astrojs/starlight/components' -DocSpring supports three different kinds of forms that can be used to fill out and generate PDFs. +DocSpring supports three different kinds of forms that can be used to collect data and generate PDFs. -- [Web Forms](/docs/forms/web-forms/) - - Ideal for turning complex PDFs into a simple web-based form with inputs and checkboxes. -- [Visual Forms](/docs/forms/visual-forms/) - - Show a visual representation of the PDF to users and allow them to fill out the fields. Similar to filling out a PDF form in Acrobat or Preview on macOS. -- [Data Requests](/docs/forms/data-requests/) - - Generate legally binding electronic signatures with UETA/ESIGN compliance. Renders a visual form inside a secure iframe and adds compliance features and audit trails. + - + -### Key Differences + + + +### Comparison | Feature | Web Forms | Visual Forms | Data Requests | | ---------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- | -| Available on DocSpring.com | | | | +| Available on [DocSpring.com](https://docspring.com) | | | | | Embed on your own website | | | | | Field validation | | | | | Mobile support | | | | @@ -36,22 +43,3 @@ DocSpring supports three different kinds of forms that can be used to fill out a | User authentication tracking | | | | | Legally binding e-signatures | | | | -## Next Steps - - - - - - From 7178ca80a900eca9c9c7b14ef55142e2d9818011 Mon Sep 17 00:00:00 2001 From: Nathan Broadbent Date: Wed, 17 Sep 2025 13:17:01 +1200 Subject: [PATCH 04/18] fixed api-guide/install-api-client.mdx after refactor --- api-guide/install-api-client.mdx | 48 ++++++++++++++++++++------------ 1 file changed, 30 insertions(+), 18 deletions(-) diff --git a/api-guide/install-api-client.mdx b/api-guide/install-api-client.mdx index b5f71dc..62656ef 100644 --- a/api-guide/install-api-client.mdx +++ b/api-guide/install-api-client.mdx @@ -6,54 +6,66 @@ sidebar: --- import { Tabs, TabItem, LinkCard } from '@astrojs/starlight/components' -import JavaScriptInstallation from '@components/sdk-installation/javascript.astro' -import TypeScriptInstallation from '@components/sdk-installation/typescript.astro' -import RubyInstallation from '@components/sdk-installation/ruby.astro' -import PythonInstallation from '@components/sdk-installation/python.astro' -import PHPInstallation from '@components/sdk-installation/php.astro' -import JavaInstallation from '@components/sdk-installation/java.astro' -import CSharpInstallation from '@components/sdk-installation/csharp.astro' -import GoInstallation from '@components/sdk-installation/go.astro' -import ElixirInstallation from '@components/sdk-installation/elixir.astro' +import JavaScriptMarkdown from '../../sdk-installation/javascript.md' +import TypeScriptMarkdown from '../../sdk-installation/typescript.md' +import RubyMarkdown from '../../sdk-installation/ruby.md' +import PythonMarkdown from '../../sdk-installation/python.md' +import PHPMarkdown from '../../sdk-installation/php.md' +import JavaMarkdown from '../../sdk-installation/java.md' +import CSharpMarkdown from '../../sdk-installation/csharp.md' +import GoMarkdown from '../../sdk-installation/go.md' +import ElixirMarkdown from '../../sdk-installation/elixir.md' +import SdkInstallationCardGrid from '@components/SdkInstallationCardGrid.astro' +import { Package } from 'lucide-astro' import './install-api-client.css' +import { sdkLinkCardConfigs } from '@utils/sdkInstallations' Choose your preferred programming language to get started with the DocSpring API. - + + - + + - + + - + + - + + - + + - + + - + + - + + From 60daf06ce9efbc07ad4f7c28c02bff04dc1ede6e Mon Sep 17 00:00:00 2001 From: Nathan Broadbent Date: Wed, 17 Sep 2025 17:18:13 +1200 Subject: [PATCH 05/18] reorganized docs --- api-guide/autogenerated-api-clients.mdx | 2 +- api-guide/combine-pdfs.mdx | 6 +- api-guide/generate-pdfs.mdx | 225 ------------------ .../generate-pdfs/batch-generate-pdfs.mdx | 111 +++++++++ .../customize-pdf-title-and-filename.mdx | 0 .../generate-pdfs/generate-pdfs-via-api.mdx | 105 ++++++++ .../handle-truncated-text.mdx} | 2 +- .../special-newline-characters.mdx | 0 api-guide/openapi-schema.mdx | 6 - 9 files changed, 221 insertions(+), 236 deletions(-) delete mode 100644 api-guide/generate-pdfs.mdx create mode 100644 api-guide/generate-pdfs/batch-generate-pdfs.mdx rename api-guide/{ => generate-pdfs}/customize-pdf-title-and-filename.mdx (100%) create mode 100644 api-guide/generate-pdfs/generate-pdfs-via-api.mdx rename api-guide/{truncated-text.mdx => generate-pdfs/handle-truncated-text.mdx} (97%) rename api-guide/{ => generate-pdfs}/special-newline-characters.mdx (100%) diff --git a/api-guide/autogenerated-api-clients.mdx b/api-guide/autogenerated-api-clients.mdx index f67d498..783a175 100644 --- a/api-guide/autogenerated-api-clients.mdx +++ b/api-guide/autogenerated-api-clients.mdx @@ -45,7 +45,7 @@ OpenAPI Generator supports the following languages: @@ -142,7 +142,7 @@ Handle form fields with truncated text by generating additional pages: @@ -150,4 +150,4 @@ Handle form fields with truncated text by generating additional pages: title="Custom Files" href="/docs/api/#tag/custom-files" description="Upload and manage custom PDF files for combining" -/> \ No newline at end of file +/> diff --git a/api-guide/generate-pdfs.mdx b/api-guide/generate-pdfs.mdx deleted file mode 100644 index 355c204..0000000 --- a/api-guide/generate-pdfs.mdx +++ /dev/null @@ -1,225 +0,0 @@ ---- -title: Generate PDFs -description: Generate PDFs from templates using the DocSpring API -sidebar: - order: 3 ---- - -import { Tabs, TabItem, Aside, LinkCard } from '@astrojs/starlight/components' - -The DocSpring API generates PDFs by filling templates with your data. Templates can be either: - -- **PDF templates** - Upload a PDF and add fillable fields in our visual editor -- **HTML/CSS templates** - Write HTML and CSS for complete control over layout - -When you create a template, you define fields with names and types (text, number, date, signature, etc.). -These fields determine the structure of the data you send to generate PDFs. -The API validates your data against the template's field schema and fills the template to create your PDF. - -### API Endpoint - -``` -POST /api/v1/templates/{template_id}/submissions -``` - -### Key Parameters - -- `data` - Field data matching your template schema -- `test` - Generate a free watermarked test PDF (`true`) or live PDF (`false`) -- `metadata` - Additional data like user IDs, included in webhook requests -- `version` - Template version to use (`draft`, `latest`, or specific version like `1.2.3`) -- `wait` - Wait for PDF processing to complete (`true`) or return immediately (`false`). Default: `true` -- `editable` - Generate an editable PDF with fillable form fields (`true`) or static PDF (`false`). Uses template default if not specified -- `expires_in` - Number of seconds before the submission expires after processing -- `data_requests` - Request additional information or signatures from recipients -- `field_overrides` - Override field settings like `required` for specific fields - -
- - -## Batch PDF Generation - -Generate up to 50 PDFs in a single request, each potentially using different templates and data. - -### API Endpoint - -``` -POST /api/v1/submissions/batches -``` - -### Example Request - -```json -{ - "submissions": [ - { - "template_id": "tpl_abc123", - "data": { "name": "John Smith" }, - "test": true - }, - { - "template_id": "tpl_xyz789", - "data": { "name": "Jane Doe" }, - "test": false - } - ] -} -``` - - - -## Synchronous vs Asynchronous Processing - -### Synchronous (Default) - -By default, the API waits for the PDF to be generated before returning: - -```javascript -// Wait for PDF generation (default behavior) -const response = await client.generatePdf(templateId, { - data: { name: "John Smith" } -}) -console.log(response.submission.download_url) // PDF is ready -``` - -### Asynchronous - -Set `wait=false` to return immediately and process in the background: - -```javascript -// Return immediately with pending submission -const response = await client.generatePdf(templateId, { - data: { name: "John Smith" }, - wait: false -}) - -// Poll for completion every few seconds -const submission = await client.getSubmission(response.submission.id) -``` - - - -## Customization Options - -### PDF Title and Filename - -You can customize both the PDF title (shown in PDF reader applications) and the filename in the download URL via metadata: - -```json -{ - "data": { "name": "John Smith" }, - "metadata": { - "pdf_title": "Employment Contract - John Smith", - "pdf_filename": "contract_2024_01_15" - } -} -``` - -- `pdf_title` - Sets the title shown in PDF reader applications (defaults to template name) -- `pdf_filename` - Sets the filename in the download URL (DocSpring adds `.pdf` automatically) - - Default URL: `/submissions/.pdf` - - Custom URL: `/submissions//contract_2024_01_15.pdf` - - Max 128 characters, allowed: `0-9 A-Z a-z - _ .` (other characters replaced with `_`) - -### Field Overrides - -Override template field settings per submission: - -```json -{ - "data": { "name": "John Smith" }, - "field_overrides": { - "signature": { - "required": false - } - } -} -``` - -### Handling Truncated Text - -If text doesn't fit in a field and the field's "Overflow" option is set to "Truncate", DocSpring stores the truncated text in the submission response: - -```json -{ - "submission": { - "truncated_text": { - "title": ["text that could not fit in the field"] - } - } -} -``` - -This is useful for forms with addendum pages - you can check `truncated_text` and generate additional pages when needed. - -### Special Newline Characters - -If your integration can't send literal newline characters (`\n`), use `%%LF%%` as a replacement: - -```json -{ - "address": "123 Main Street%%LF%%Suite 100%%LF%%New York, NY 10001" -} -``` - -This renders in the PDF as: -``` -123 Main Street -Suite 100 -New York, NY 10001 -``` - -## Data Requests - -Request additional information or electronic signatures from users before generating the PDF: - -```json -{ - "data": { "name": "John Smith" }, - "data_requests": [ - { - "name": "John Smith", - "email": "john@example.com", - "fields": ["signature", "date"] - } - ] -} -``` - - - -## Related Resources - - - - - - diff --git a/api-guide/generate-pdfs/batch-generate-pdfs.mdx b/api-guide/generate-pdfs/batch-generate-pdfs.mdx new file mode 100644 index 0000000..cb3809b --- /dev/null +++ b/api-guide/generate-pdfs/batch-generate-pdfs.mdx @@ -0,0 +1,111 @@ +--- +title: Batch Generate PDFs +description: Create up to 50 submissions in a single API call +sidebar: + order: 4 +--- + +import { Aside, LinkCard } from '@astrojs/starlight/components' + +Batch submission requests let you create multiple PDFs in parallel with a single call to the DocSpring API. Each item in the batch can point to a different template, supply different data, and choose between test or live mode. + +## Endpoint + +``` +POST /api/v1/submissions/batches +``` + + + +## Request Structure + +Provide an array of submissions. Every entry accepts the same payload as a standard submission request: + +```json +{ + "submissions": [ + { + "template_id": "tpl_contract", + "data": { "name": "John Smith" }, + "test": true, + "metadata": { "pdf_filename": "contract_draft_john_smith" } + }, + { + "template_id": "tpl_invoice", + "data": { "name": "Acme Corp" }, + "test": false, + "wait": false + } + ] +} +``` + + + +## Response Format + +Batch responses include a `batch` object and an array of child `submissions`: + +```json +{ + "batch": { + "id": "bat_123", + "status": "processed", + "created_at": "2024-02-01T12:00:00Z" + }, + "submissions": [ + { + "id": "sub_first", + "status": "processed", + "download_url": "https://.../sub_first.pdf" + }, + { + "id": "sub_second", + "status": "pending" + } + ] +} +``` + +When you set `wait=false` on any submission, the batch response may return before the PDF is ready. Poll each submission with `GET /api/v1/submissions/{id}` or listen for the `submission.completed` webhook. + +## Limits & Best Practices + +- **Up to 50 submissions** per batch request. +- **Mix templates freely** – each item can target a different template. +- **Test vs. live mode** – set `test` per submission. +- **Back pressure** – prefer batch requests when generating many documents to avoid hitting rate limits with individual calls. +- **Webhooks** – enable webhooks if you need to know when asynchronous submissions finish processing. + +## Related Topics + + + + + + + + diff --git a/api-guide/customize-pdf-title-and-filename.mdx b/api-guide/generate-pdfs/customize-pdf-title-and-filename.mdx similarity index 100% rename from api-guide/customize-pdf-title-and-filename.mdx rename to api-guide/generate-pdfs/customize-pdf-title-and-filename.mdx diff --git a/api-guide/generate-pdfs/generate-pdfs-via-api.mdx b/api-guide/generate-pdfs/generate-pdfs-via-api.mdx new file mode 100644 index 0000000..0cc7766 --- /dev/null +++ b/api-guide/generate-pdfs/generate-pdfs-via-api.mdx @@ -0,0 +1,105 @@ +--- +title: Generate PDFs via API +description: Generate PDFs from templates using the DocSpring API +sidebar: + order: 3 +--- + +import { LinkCard } from '@astrojs/starlight/components' + +DocSpring generates PDFs by filling your templates with submission data. Templates can either be uploads that you annotate in the Template Editor or fully custom HTML/CSS layouts that you host in DocSpring. + +## Endpoint + +``` +POST /api/v1/templates/{template_id}/submissions +``` + + + +## Request Payload Basics + +Every submission must include: + +- `data` — Field values that match your template schema. +- `test` — Use `true` for free, watermarked PDFs while building your integration. +- `metadata` — Optional map for values you want echoed back in webhooks. +- `version` — Choose `draft`, `latest`, or a specific version such as `1.2.3`. + +Optional parameters: + +- `wait` — Decide between synchronous and asynchronous processing. +- `editable` — Keep the resulting PDF fillable or flatten the form fields. +- `expires_in` — Set a TTL for the generated PDF download link. +- `field_overrides` — Temporarily adjust field requirements or defaults. +- `data_requests` — Kick off a data collection or signature workflow before finalizing the PDF. + +## Processing Modes + +Submissions sent to `sync.api.docspring.com` wait for processing and return the `download_url` in the response. Switching `wait=false` or using the asynchronous domain returns immediately with a pending submission. See [Sync vs. Async Processing](/docs/api-guide/synchronous-requests/) for flow diagrams, polling tips, and webhook guidance. + +## Batch Generation + +Need to create many PDFs at once? Use the batch endpoint to submit up to 50 requests together. Each entry can target a different template, switch between test/live, and specify its own metadata. + + + +## Helpful Extras + + + + + + + + + +## Related Workflows + + + + + + + + diff --git a/api-guide/truncated-text.mdx b/api-guide/generate-pdfs/handle-truncated-text.mdx similarity index 97% rename from api-guide/truncated-text.mdx rename to api-guide/generate-pdfs/handle-truncated-text.mdx index 54350cb..973160c 100644 --- a/api-guide/truncated-text.mdx +++ b/api-guide/generate-pdfs/handle-truncated-text.mdx @@ -1,5 +1,5 @@ --- -title: When Text Doesn't Fit in a Field +title: Handle Truncated Text description: Handle text that doesn't fit in a PDF field sidebar: order: 5 diff --git a/api-guide/special-newline-characters.mdx b/api-guide/generate-pdfs/special-newline-characters.mdx similarity index 100% rename from api-guide/special-newline-characters.mdx rename to api-guide/generate-pdfs/special-newline-characters.mdx diff --git a/api-guide/openapi-schema.mdx b/api-guide/openapi-schema.mdx index ca12854..7676217 100644 --- a/api-guide/openapi-schema.mdx +++ b/api-guide/openapi-schema.mdx @@ -21,12 +21,6 @@ and [Postman collection](/docs/api-guide/postman/). ## Resources - - Date: Thu, 18 Sep 2025 15:47:34 +1200 Subject: [PATCH 06/18] fix linting issues --- api-guide/authentication.mdx | 6 +-- api-guide/autogenerated-api-clients.mdx | 2 +- api-guide/combine-pdfs.mdx | 24 ++++++++- api-guide/create-data-requests.mdx | 2 +- .../generate-pdfs/batch-generate-pdfs.mdx | 6 +-- .../customize-pdf-title-and-filename.mdx | 2 +- .../generate-pdfs/generate-pdfs-via-api.mdx | 2 +- .../generate-pdfs/handle-truncated-text.mdx | 2 +- .../special-newline-characters.mdx | 2 +- api-guide/install-api-client.mdx | 28 +++++------ api-guide/openapi-schema.mdx | 2 +- api-guide/postman.mdx | 2 +- api-guide/synchronous-requests.mdx | 2 +- changelogs/data-requests-js.mdx | 2 +- changelogs/simple-forms-js.mdx | 2 +- changelogs/visual-forms-js.mdx | 2 +- forms/compare-docspring-forms.mdx | 28 +++++------ forms/data-requests.mdx | 2 +- forms/js-libraries/data-requests-js.mdx | 8 +-- forms/js-libraries/visual-forms-js.mdx | 6 +-- forms/js-libraries/web-forms-js.mdx | 48 +++++++++--------- forms/visual-forms.mdx | 2 +- forms/web-forms.mdx | 10 ++-- .../embedded-forms/embedded-data-requests.mdx | 4 +- .../embedded-forms/embedded-visual-forms.mdx | 6 +-- guides/embedded-forms/embedded-web-forms.mdx | 4 +- .../web-forms-with-data-requests.mdx | 2 +- guides/index.mdx | 2 +- guides/integrations/aws-s3-integration.mdx | 12 ++--- html-templates/liquid-filters.mdx | 2 +- html-templates/overview.mdx | 2 +- index.mdx | 2 +- integrations/aws-s3.mdx | 14 +++--- integrations/overview.mdx | 2 +- introduction.mdx | 2 +- reference/field-data-types.mdx | 50 +++++++++---------- reference/field-defaults.mdx | 4 +- reference/field-display-types.mdx | 2 +- reference/field-schema.mdx | 8 +-- template-editor/field-names.mdx | 6 +-- template-editor/formulas.mdx | 2 +- template-editor/introduction.mdx | 8 +-- template-editor/keyboard-shortcuts.mdx | 2 +- template-editor/locked-templates.mdx | 8 +-- template-editor/radio-buttons.mdx | 2 +- template-editor/settings.mdx | 2 +- template-editor/versions.mdx | 2 +- 47 files changed, 181 insertions(+), 161 deletions(-) diff --git a/api-guide/authentication.mdx b/api-guide/authentication.mdx index 1634dff..dc4ca8d 100644 --- a/api-guide/authentication.mdx +++ b/api-guide/authentication.mdx @@ -5,9 +5,9 @@ sidebar: order: 2 --- -import { Tabs, TabItem, Code, LinkCard } from '@astrojs/starlight/components' -import fs from 'fs' -import path from 'path' +import { Tabs, TabItem, Code, LinkCard } from "@astrojs/starlight/components"; +import fs from "fs"; +import path from "path"; export async function getCodeSample(language, filename, extension) { const filePath = path.join( diff --git a/api-guide/autogenerated-api-clients.mdx b/api-guide/autogenerated-api-clients.mdx index 783a175..be06d61 100644 --- a/api-guide/autogenerated-api-clients.mdx +++ b/api-guide/autogenerated-api-clients.mdx @@ -5,7 +5,7 @@ sidebar: order: 7 --- -import { LinkCard, Code, Aside } from '@astrojs/starlight/components' +import { LinkCard, Code, Aside } from "@astrojs/starlight/components"; We use [openapi-generator](https://github.com/OpenAPITools/openapi-generator) to automatically generate API clients from our OpenAPI schema. diff --git a/api-guide/combine-pdfs.mdx b/api-guide/combine-pdfs.mdx index ad5e2f4..88a7196 100644 --- a/api-guide/combine-pdfs.mdx +++ b/api-guide/combine-pdfs.mdx @@ -5,7 +5,7 @@ sidebar: order: 4 --- -import { LinkCard } from '@astrojs/starlight/components' +import { LinkCard } from "@astrojs/starlight/components"; Combine multiple PDFs from different sources into a single merged document. @@ -20,32 +20,42 @@ POST /api/v1/combined_submissions You can combine PDFs from various sources: ### Submissions + Generated PDFs from template submissions: + ```json { "type": "submission", "id": "sub_1234567890abcdef01" } ``` ### Combined Submissions + Previously combined PDFs: + ```json { "type": "combined_submission", "id": "com_1234567890abcdef01" } ``` ### Templates + Original template PDFs (unfilled): + ```json { "type": "template", "id": "tpl_1234567890abcdef01" } { "type": "template", "id": "tpl_1234567890abcdef01", "template_version": "1.2.3" } ``` ### Custom Files + Uploaded PDF files: + ```json { "type": "custom_file", "id": "cfi_1234567890abcdef01" } ``` ### URLs + PDFs from external URLs: + ```json { "type": "url", "url": "https://example.com/document.pdf" } ``` @@ -69,13 +79,17 @@ PDFs from external URLs: ## Key Features ### Template Versions + For template sources, specify versions: + - `"template_version": "draft"` - Use draft version - `"template_version": "latest"` - Use latest published version (default) - `"template_version": "1.2.3"` - Use specific version ### Custom Filename + Set a custom PDF filename via metadata: + ```json { "metadata": { @@ -88,17 +102,21 @@ The download URL becomes: `/combined_submissions/{id}/merged_documents_2024.pdf` **Filename rules:** + - Max 128 characters - Allowed: `0-9 A-Z a-z - _ .` - Other characters replaced with `_` ### Free to Use + Combining PDFs is free, but source submission PDFs count toward your monthly usage. ## Use Cases ### Multi-Page Forms + Combine multiple template submissions for complex forms: + ```json { "source_pdfs": [ @@ -110,7 +128,9 @@ Combine multiple template submissions for complex forms: ``` ### Document Packages + Create complete document packages with cover pages, forms, and attachments: + ```json { "source_pdfs": [ @@ -122,7 +142,9 @@ Create complete document packages with cover pages, forms, and attachments: ``` ### Addendum Pages + Handle form fields with truncated text by generating additional pages: + ```json { "source_pdfs": [ diff --git a/api-guide/create-data-requests.mdx b/api-guide/create-data-requests.mdx index 305a4eb..616848c 100644 --- a/api-guide/create-data-requests.mdx +++ b/api-guide/create-data-requests.mdx @@ -3,7 +3,7 @@ title: Create Data Requests description: Learn how to create PDF submissions with pending data requests --- -import { LinkCard } from '@astrojs/starlight/components' +import { LinkCard } from "@astrojs/starlight/components"; ### Create a new PDF job submission with pending data requests diff --git a/api-guide/generate-pdfs/batch-generate-pdfs.mdx b/api-guide/generate-pdfs/batch-generate-pdfs.mdx index cb3809b..857a3ba 100644 --- a/api-guide/generate-pdfs/batch-generate-pdfs.mdx +++ b/api-guide/generate-pdfs/batch-generate-pdfs.mdx @@ -5,7 +5,7 @@ sidebar: order: 4 --- -import { Aside, LinkCard } from '@astrojs/starlight/components' +import { Aside, LinkCard } from "@astrojs/starlight/components"; Batch submission requests let you create multiple PDFs in parallel with a single call to the DocSpring API. Each item in the batch can point to a different template, supply different data, and choose between test or live mode. @@ -45,8 +45,8 @@ Provide an array of submissions. Every entry accepts the same payload as a stand ``` ## Response Format diff --git a/api-guide/generate-pdfs/customize-pdf-title-and-filename.mdx b/api-guide/generate-pdfs/customize-pdf-title-and-filename.mdx index 5779c6b..daa1970 100644 --- a/api-guide/generate-pdfs/customize-pdf-title-and-filename.mdx +++ b/api-guide/generate-pdfs/customize-pdf-title-and-filename.mdx @@ -5,7 +5,7 @@ sidebar: order: 3 --- -import { Aside } from '@astrojs/starlight/components' +import { Aside } from "@astrojs/starlight/components"; When generating PDFs through the DocSpring API, you can customize both the PDF title (shown in PDF reader applications) and the filename in the download URL. diff --git a/api-guide/generate-pdfs/generate-pdfs-via-api.mdx b/api-guide/generate-pdfs/generate-pdfs-via-api.mdx index 0cc7766..119f6ba 100644 --- a/api-guide/generate-pdfs/generate-pdfs-via-api.mdx +++ b/api-guide/generate-pdfs/generate-pdfs-via-api.mdx @@ -5,7 +5,7 @@ sidebar: order: 3 --- -import { LinkCard } from '@astrojs/starlight/components' +import { LinkCard } from "@astrojs/starlight/components"; DocSpring generates PDFs by filling your templates with submission data. Templates can either be uploads that you annotate in the Template Editor or fully custom HTML/CSS layouts that you host in DocSpring. diff --git a/api-guide/generate-pdfs/handle-truncated-text.mdx b/api-guide/generate-pdfs/handle-truncated-text.mdx index 973160c..3751b56 100644 --- a/api-guide/generate-pdfs/handle-truncated-text.mdx +++ b/api-guide/generate-pdfs/handle-truncated-text.mdx @@ -5,7 +5,7 @@ sidebar: order: 5 --- -import { Aside, Code } from '@astrojs/starlight/components' +import { Aside, Code } from "@astrojs/starlight/components"; If the full text can't fit in a field and the field's "Overflow" option is set to "Truncate", DocSpring will store any truncated text in the submission. diff --git a/api-guide/generate-pdfs/special-newline-characters.mdx b/api-guide/generate-pdfs/special-newline-characters.mdx index 94245b2..5a4f398 100644 --- a/api-guide/generate-pdfs/special-newline-characters.mdx +++ b/api-guide/generate-pdfs/special-newline-characters.mdx @@ -5,7 +5,7 @@ sidebar: order: 4 --- -import { Aside } from '@astrojs/starlight/components' +import { Aside } from "@astrojs/starlight/components"; ## The `%%LF%%` Sequence diff --git a/api-guide/install-api-client.mdx b/api-guide/install-api-client.mdx index 62656ef..cffca5d 100644 --- a/api-guide/install-api-client.mdx +++ b/api-guide/install-api-client.mdx @@ -5,20 +5,20 @@ sidebar: order: 1 --- -import { Tabs, TabItem, LinkCard } from '@astrojs/starlight/components' -import JavaScriptMarkdown from '../../sdk-installation/javascript.md' -import TypeScriptMarkdown from '../../sdk-installation/typescript.md' -import RubyMarkdown from '../../sdk-installation/ruby.md' -import PythonMarkdown from '../../sdk-installation/python.md' -import PHPMarkdown from '../../sdk-installation/php.md' -import JavaMarkdown from '../../sdk-installation/java.md' -import CSharpMarkdown from '../../sdk-installation/csharp.md' -import GoMarkdown from '../../sdk-installation/go.md' -import ElixirMarkdown from '../../sdk-installation/elixir.md' -import SdkInstallationCardGrid from '@components/SdkInstallationCardGrid.astro' -import { Package } from 'lucide-astro' -import './install-api-client.css' -import { sdkLinkCardConfigs } from '@utils/sdkInstallations' +import { Tabs, TabItem, LinkCard } from "@astrojs/starlight/components"; +import JavaScriptMarkdown from "../../sdk-installation/javascript.md"; +import TypeScriptMarkdown from "../../sdk-installation/typescript.md"; +import RubyMarkdown from "../../sdk-installation/ruby.md"; +import PythonMarkdown from "../../sdk-installation/python.md"; +import PHPMarkdown from "../../sdk-installation/php.md"; +import JavaMarkdown from "../../sdk-installation/java.md"; +import CSharpMarkdown from "../../sdk-installation/csharp.md"; +import GoMarkdown from "../../sdk-installation/go.md"; +import ElixirMarkdown from "../../sdk-installation/elixir.md"; +import SdkInstallationCardGrid from "@components/SdkInstallationCardGrid.astro"; +import { Package } from "lucide-astro"; +import "./install-api-client.css"; +import { sdkLinkCardConfigs } from "@utils/sdkInstallations"; Choose your preferred programming language to get started with the DocSpring API. diff --git a/api-guide/openapi-schema.mdx b/api-guide/openapi-schema.mdx index 7676217..fca9abb 100644 --- a/api-guide/openapi-schema.mdx +++ b/api-guide/openapi-schema.mdx @@ -5,7 +5,7 @@ sidebar: order: 6 --- -import { LinkCard, Aside } from '@astrojs/starlight/components' +import { LinkCard, Aside } from "@astrojs/starlight/components"; We define our API endpoints and request/response schemas using the [OpenAPI specification](https://swagger.io/docs/specification/about/) (formerly known as [Swagger](https://swagger.io/)). diff --git a/api-guide/postman.mdx b/api-guide/postman.mdx index e374d93..e6f0597 100644 --- a/api-guide/postman.mdx +++ b/api-guide/postman.mdx @@ -5,7 +5,7 @@ sidebar: order: 8 --- -import { LinkCard, Aside } from '@astrojs/starlight/components' +import { LinkCard, Aside } from "@astrojs/starlight/components"; Our API specification is published as a [Postman](https://www.postman.com) collection. diff --git a/api-guide/synchronous-requests.mdx b/api-guide/synchronous-requests.mdx index d724fa1..bd1cfb5 100644 --- a/api-guide/synchronous-requests.mdx +++ b/api-guide/synchronous-requests.mdx @@ -5,7 +5,7 @@ sidebar: order: 2 --- -import { Aside } from '@astrojs/starlight/components' +import { Aside } from "@astrojs/starlight/components"; The DocSpring API supports both synchronous and asynchronous API requests. diff --git a/changelogs/data-requests-js.mdx b/changelogs/data-requests-js.mdx index f6ebaf2..9d8186c 100644 --- a/changelogs/data-requests-js.mdx +++ b/changelogs/data-requests-js.mdx @@ -5,7 +5,7 @@ sidebar: order: 1 --- -import { Aside, Badge, LinkCard } from '@astrojs/starlight/components' +import { Aside, Badge, LinkCard } from "@astrojs/starlight/components"; This client-side JavaScript library allows you to embed a signing form on your own website to collect legally binding electronic signatures and generate signed PDFs. diff --git a/changelogs/simple-forms-js.mdx b/changelogs/simple-forms-js.mdx index adb7c63..ac4ca3c 100644 --- a/changelogs/simple-forms-js.mdx +++ b/changelogs/simple-forms-js.mdx @@ -5,7 +5,7 @@ sidebar: order: 2 --- -import { Aside, Badge, LinkCard } from '@astrojs/starlight/components' +import { Aside, Badge, LinkCard } from "@astrojs/starlight/components"; This client-side JavaScript library allows you to embed a simple web form on your own website. Share this page with your users and they can fill out the form to generate a PDF. diff --git a/changelogs/visual-forms-js.mdx b/changelogs/visual-forms-js.mdx index ba08f18..8c49365 100644 --- a/changelogs/visual-forms-js.mdx +++ b/changelogs/visual-forms-js.mdx @@ -5,7 +5,7 @@ sidebar: order: 3 --- -import { Aside, Badge, LinkCard } from '@astrojs/starlight/components' +import { Aside, Badge, LinkCard } from "@astrojs/starlight/components"; This client-side JavaScript library allows you to embed a visual form on your own website to fill out PDF templates and generate PDFs. diff --git a/forms/compare-docspring-forms.mdx b/forms/compare-docspring-forms.mdx index 216861c..0239a1f 100644 --- a/forms/compare-docspring-forms.mdx +++ b/forms/compare-docspring-forms.mdx @@ -5,7 +5,7 @@ sidebar: order: 0 --- -import { LinkCard, Aside, Code, Icon } from '@astrojs/starlight/components' +import { LinkCard, Aside, Code, Icon } from "@astrojs/starlight/components"; DocSpring supports three different kinds of forms that can be used to collect data and generate PDFs. @@ -27,19 +27,17 @@ DocSpring supports three different kinds of forms that can be used to collect da description="Generate legally binding electronic signatures with UETA/ESIGN compliance. Renders a visual form inside a secure iframe and adds compliance features and audit trails." /> - ### Comparison -| Feature | Web Forms | Visual Forms | Data Requests | -| ---------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- | -| Available on [DocSpring.com](https://docspring.com) | | | | -| Embed on your own website | | | | -| Field validation | | | | -| Mobile support | | | | -| Works with PDF templates | | | | -| Works with HTML templates | | | | -| Visual PDF preview | | | | -| Audit trail tracking | | | | -| User authentication tracking | | | | -| Legally binding e-signatures | | | | - +| Feature | Web Forms | Visual Forms | Data Requests | +| --------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- | +| Available on [DocSpring.com](https://docspring.com) | | | | +| Embed on your own website | | | | +| Field validation | | | | +| Mobile support | | | | +| Works with PDF templates | | | | +| Works with HTML templates | | | | +| Visual PDF preview | | | | +| Audit trail tracking | | | | +| User authentication tracking | | | | +| Legally binding e-signatures | | | | diff --git a/forms/data-requests.mdx b/forms/data-requests.mdx index 8f2a362..2c19dc6 100644 --- a/forms/data-requests.mdx +++ b/forms/data-requests.mdx @@ -3,7 +3,7 @@ title: Data Requests description: Core documentation for collecting UETA and ESIGN compliant electronic signatures --- -import { LinkCard, Aside } from '@astrojs/starlight/components' +import { LinkCard, Aside } from "@astrojs/starlight/components"; ### Collect legally binding electronic signatures diff --git a/forms/js-libraries/data-requests-js.mdx b/forms/js-libraries/data-requests-js.mdx index 611442f..93bde00 100644 --- a/forms/js-libraries/data-requests-js.mdx +++ b/forms/js-libraries/data-requests-js.mdx @@ -3,7 +3,7 @@ title: Data Requests JavaScript API description: JavaScript API reference for DocSpring.createDataRequest() --- -import { Code, Aside, LinkCard } from '@astrojs/starlight/components' +import { Code, Aside, LinkCard } from "@astrojs/starlight/components"; The Data Requests JavaScript library allows you to embed signing forms on your website for collecting electronic signatures. @@ -26,9 +26,9 @@ Creates an embedded signing form for collecting electronic signatures. ### Syntax ```javascript -DocSpring.createVisualForm(cssSelector, optionsAndCallbacks) +DocSpring.createVisualForm(cssSelector, optionsAndCallbacks); // or -DocSpring.createVisualForm(optionsAndCallbacks) +DocSpring.createVisualForm(optionsAndCallbacks); ``` ### Parameters @@ -204,7 +204,7 @@ These global functions allow you to interact with the form. Note that only one D Enable debug logging to troubleshoot issues: ```javascript -DocSpring.DEBUG = true +DocSpring.DEBUG = true; ``` This will show extra debugging log messages in the developer console. If you are experiencing any problems with your integration, please enable logging and include the console logs in your support request. diff --git a/forms/js-libraries/visual-forms-js.mdx b/forms/js-libraries/visual-forms-js.mdx index e5f9a11..f234a23 100644 --- a/forms/js-libraries/visual-forms-js.mdx +++ b/forms/js-libraries/visual-forms-js.mdx @@ -3,7 +3,7 @@ title: Visual Forms JavaScript API description: JavaScript API reference for DocSpring.createVisualForm() --- -import { Code, Aside, LinkCard } from '@astrojs/starlight/components' +import { Code, Aside, LinkCard } from "@astrojs/starlight/components"; The Visual Forms JavaScript library allows you to embed a visual PDF form directly on your website so that your users can fill it out and generate a PDF. @@ -29,9 +29,9 @@ Creates an embedded visual form for filling out PDF templates. ### Syntax ```javascript -DocSpring.createVisualForm(cssSelector, optionsAndCallbacks) +DocSpring.createVisualForm(cssSelector, optionsAndCallbacks); // or -DocSpring.createVisualForm(optionsAndCallbacks) +DocSpring.createVisualForm(optionsAndCallbacks); ``` ### Parameters diff --git a/forms/js-libraries/web-forms-js.mdx b/forms/js-libraries/web-forms-js.mdx index 0636201..49068ff 100644 --- a/forms/js-libraries/web-forms-js.mdx +++ b/forms/js-libraries/web-forms-js.mdx @@ -3,7 +3,7 @@ title: Web Forms JavaScript API description: JavaScript API reference for DocSpring.createSimpleForm() --- -import { Aside, LinkCard } from '@astrojs/starlight/components' +import { Aside, LinkCard } from "@astrojs/starlight/components"; The Web Forms JavaScript library allows you to embed web forms on your website for collecting data from your users and filling out PDF templates. @@ -26,7 +26,7 @@ Creates an embedded web form (or "simple form") for a DocSpring template. ### Syntax ```javascript -DocSpring.createSimpleForm(css_selector, template_id, options_and_callbacks) +DocSpring.createSimpleForm(css_selector, template_id, options_and_callbacks); ``` ### Parameters @@ -77,62 +77,62 @@ Returns a form instance object with methods for programmatic control (currently ### Basic Usage ```javascript -DocSpring.createSimpleForm('.dsp-form', 'tpl_123456') +DocSpring.createSimpleForm(".dsp-form", "tpl_123456"); ``` ### With Default Data ```javascript -DocSpring.createSimpleForm('.dsp-form', 'tpl_123456', { +DocSpring.createSimpleForm(".dsp-form", "tpl_123456", { defaultData: { - name: 'John Smith', - email: 'john@example.com', - date: '2024-01-15', + name: "John Smith", + email: "john@example.com", + date: "2024-01-15", }, -}) +}); ``` ### With All Options ```javascript -DocSpring.createSimpleForm('.dsp-form', 'tpl_123456', { +DocSpring.createSimpleForm(".dsp-form", "tpl_123456", { // Options defaultData: { - name: 'John Smith', + name: "John Smith", }, metadata: { - userId: '12345', - source: 'website', + userId: "12345", + source: "website", }, showClearButton: true, - clearButtonLabel: 'Reset', - submitButtonLabel: 'Generate My PDF', - submitButtonSavingLabel: 'Please wait...', - submitButtonProcessingLabel: 'Creating your PDF...', - redirectURL: 'https://example.com/success', + clearButtonLabel: "Reset", + submitButtonLabel: "Generate My PDF", + submitButtonSavingLabel: "Please wait...", + submitButtonProcessingLabel: "Creating your PDF...", + redirectURL: "https://example.com/success", waitForPDF: false, // Callbacks processTemplateSchema: function (jsonSchema) { // Hide the email field - delete jsonSchema.properties.email + delete jsonSchema.properties.email; }, onClearForm: function () { - console.log('Form cleared') + console.log("Form cleared"); }, onSubmit: function (formData) { - console.log('Form submitted:', formData) + console.log("Form submitted:", formData); }, onSave: function (submission) { - console.log('Submission saved:', submission.id) + console.log("Submission saved:", submission.id); }, onProcessed: function (submission) { - console.log('PDF ready:', submission.download_url) + console.log("PDF ready:", submission.download_url); }, onError: function (response) { - console.error('Error:', response) + console.error("Error:", response); }, -}) +}); ``` ## Submission Object diff --git a/forms/visual-forms.mdx b/forms/visual-forms.mdx index da96d1b..7d502c8 100644 --- a/forms/visual-forms.mdx +++ b/forms/visual-forms.mdx @@ -3,7 +3,7 @@ title: Visual Forms description: Core documentation for visual PDF forms - both hosted and embedded --- -import { LinkCard, Aside, Code, Icon } from '@astrojs/starlight/components' +import { LinkCard, Aside, Code, Icon } from "@astrojs/starlight/components"; Visual Forms allow you to embed a PDF form filling interface directly on your website. Unlike [Data Requests](/docs/forms/data-requests/), visual forms do not include compliance features like audit trails or authentication tracking - they're simply a visual component for filling out PDF templates. diff --git a/forms/web-forms.mdx b/forms/web-forms.mdx index c5d2f5b..5dbc9b7 100644 --- a/forms/web-forms.mdx +++ b/forms/web-forms.mdx @@ -3,11 +3,11 @@ title: Web Forms description: Generate PDFs through web-based forms and configure form settings --- -import { Image } from 'astro:assets' -import { Aside, Code } from '@astrojs/starlight/components' -import privacySettings from '@images/template_editor/privacy-settings.png' -import exampleLogo from '@images/web_forms/example-logo.png' -import formWithCustomLogo from '@images/web_forms/form-with-custom-logo.png' +import { Image } from "astro:assets"; +import { Aside, Code } from "@astrojs/starlight/components"; +import privacySettings from "@images/template_editor/privacy-settings.png"; +import exampleLogo from "@images/web_forms/example-logo.png"; +import formWithCustomLogo from "@images/web_forms/form-with-custom-logo.png"; DocSpring can automatically generate web-based forms based on the fields you've set up in your template. If you send your users a link to this form, they can fill out the form to generate a PDF. You can then redirect users to a different page after they have filled out the form. diff --git a/guides/embedded-forms/embedded-data-requests.mdx b/guides/embedded-forms/embedded-data-requests.mdx index e5e87ae..e2a1eeb 100644 --- a/guides/embedded-forms/embedded-data-requests.mdx +++ b/guides/embedded-forms/embedded-data-requests.mdx @@ -3,8 +3,8 @@ title: Embedded Data Requests description: Step-by-step guide to implement UETA and ESIGN compliant electronic signatures --- -import { LinkCard, Aside, Code, Icon } from '@astrojs/starlight/components' -import getEmbedVersion from '@utils/embed-versions' +import { LinkCard, Aside, Code, Icon } from "@astrojs/starlight/components"; +import getEmbedVersion from "@utils/embed-versions"; This guide walks through implementing data requests for collecting legally binding electronic signatures. For conceptual documentation about how data requests work, see the [Data Requests documentation](/docs/forms/data-requests/). diff --git a/guides/embedded-forms/embedded-visual-forms.mdx b/guides/embedded-forms/embedded-visual-forms.mdx index 07515fc..429dae5 100644 --- a/guides/embedded-forms/embedded-visual-forms.mdx +++ b/guides/embedded-forms/embedded-visual-forms.mdx @@ -3,8 +3,8 @@ title: Embedded Visual Forms description: Step-by-step guide to embed visual PDF forms on your website --- -import { LinkCard, Aside, Code } from '@astrojs/starlight/components' -import getEmbedVersion from '@utils/embed-versions' +import { LinkCard, Aside, Code } from "@astrojs/starlight/components"; +import getEmbedVersion from "@utils/embed-versions"; This guide walks through implementing visual forms for PDF generation without the compliance features of data requests. For conceptual documentation about visual forms, see the [Visual Forms documentation](/docs/forms/visual-forms/). @@ -34,7 +34,7 @@ Add the visual forms library to your webpage: `} lang="html" title="Include visual forms library" diff --git a/guides/embedded-forms/embedded-web-forms.mdx b/guides/embedded-forms/embedded-web-forms.mdx index 88cf158..515c95e 100644 --- a/guides/embedded-forms/embedded-web-forms.mdx +++ b/guides/embedded-forms/embedded-web-forms.mdx @@ -3,8 +3,8 @@ title: Embedded Web Forms description: Step-by-step guide to embed DocSpring web forms on your website --- -import { Code, Aside, LinkCard } from '@astrojs/starlight/components' -import getEmbedVersion from '@utils/embed-versions' +import { Code, Aside, LinkCard } from "@astrojs/starlight/components"; +import getEmbedVersion from "@utils/embed-versions"; You can embed DocSpring web forms on your own website, allowing users to fill out forms and generate PDFs without leaving your site. Users can be redirected to a different page after submitting the form, or you can run custom code in JavaScript callbacks. diff --git a/guides/embedded-forms/web-forms-with-data-requests.mdx b/guides/embedded-forms/web-forms-with-data-requests.mdx index 1b4d735..b4c21e9 100644 --- a/guides/embedded-forms/web-forms-with-data-requests.mdx +++ b/guides/embedded-forms/web-forms-with-data-requests.mdx @@ -3,7 +3,7 @@ title: Web Forms + Data Requests description: Using web forms to collect data, then creating a data request to sign the PDF --- -import { LinkCard, Aside, Code, Icon } from '@astrojs/starlight/components' +import { LinkCard, Aside, Code, Icon } from "@astrojs/starlight/components"; You can use a web form to gather information with text inputs, then create a data request that is prefilled with the data from the web form. diff --git a/guides/index.mdx b/guides/index.mdx index 1748968..4900e99 100644 --- a/guides/index.mdx +++ b/guides/index.mdx @@ -3,7 +3,7 @@ title: DocSpring Guides description: Step-by-step tutorials and implementation guides for DocSpring --- -import { CardGrid, LinkCard } from '@astrojs/starlight/components' +import { CardGrid, LinkCard } from "@astrojs/starlight/components"; Welcome to the DocSpring Guides section! Here you'll find detailed tutorials and step-by-step instructions for implementing various DocSpring features. diff --git a/guides/integrations/aws-s3-integration.mdx b/guides/integrations/aws-s3-integration.mdx index 06c685a..0075d05 100644 --- a/guides/integrations/aws-s3-integration.mdx +++ b/guides/integrations/aws-s3-integration.mdx @@ -10,7 +10,7 @@ import { Tabs, TabItem, LinkCard, -} from '@astrojs/starlight/components' +} from "@astrojs/starlight/components"; This guide walks you through setting up AWS S3 integration to automatically upload generated PDFs to your own S3 bucket. @@ -231,11 +231,11 @@ clients/{{ metadata.client_id }}/{{ date }}_{{ submission_id }}.pdf Check if a PDF has been uploaded to S3: ```javascript -if (submission['actions'].length === 0) return false -const action = submission['actions'].find( - (a) => a.action_type === 'aws_s3_upload' -) -return action && action.state === 'processed' +if (submission["actions"].length === 0) return false; +const action = submission["actions"].find( + (a) => a.action_type === "aws_s3_upload", +); +return action && action.state === "processed"; ``` ### Using AWS S3 Event Notifications diff --git a/html-templates/liquid-filters.mdx b/html-templates/liquid-filters.mdx index 4cadf8a..f870a22 100644 --- a/html-templates/liquid-filters.mdx +++ b/html-templates/liquid-filters.mdx @@ -3,7 +3,7 @@ title: Liquid Filters description: Reference guide for Liquid filters available in HTML/CSS templates --- -import { Aside, Code } from '@astrojs/starlight/components' +import { Aside, Code } from "@astrojs/starlight/components"; [HTML/CSS Templates](/docs/html-templates/overview/) use the [Liquid markup language](https://shopify.github.io/liquid/basics/introduction/). You can use "filters" to format and modify any values before inserting them into the page. diff --git a/html-templates/overview.mdx b/html-templates/overview.mdx index dd33d5a..d54dacd 100644 --- a/html-templates/overview.mdx +++ b/html-templates/overview.mdx @@ -6,7 +6,7 @@ sidebar: label: Overview --- -import { Aside, Tabs, TabItem } from '@astrojs/starlight/components' +import { Aside, Tabs, TabItem } from "@astrojs/starlight/components"; DocSpring supports two different kinds of templates: diff --git a/index.mdx b/index.mdx index 7ed83bb..4ae1d62 100644 --- a/index.mdx +++ b/index.mdx @@ -14,7 +14,7 @@ hero: # icon: right-arrow --- -import { Card, CardGrid } from '@astrojs/starlight/components' +import { Card, CardGrid } from "@astrojs/starlight/components"; diff --git a/integrations/aws-s3.mdx b/integrations/aws-s3.mdx index 2f94d6f..e458d35 100644 --- a/integrations/aws-s3.mdx +++ b/integrations/aws-s3.mdx @@ -3,7 +3,7 @@ title: AWS S3 Integration description: Automatically upload generated PDFs to your own S3 bucket --- -import { Aside, LinkCard, CardGrid } from '@astrojs/starlight/components' +import { Aside, LinkCard, CardGrid } from "@astrojs/starlight/components"; DocSpring's AWS S3 integration automatically copies generated PDFs into an S3 bucket in your own AWS account, giving you full control over your document storage. @@ -114,12 +114,12 @@ For example, here's how you could wait for the PDF to be uploaded to your own S3 ```js const pdfHasBeenUploadedToS3Bucket = () => { - if (submission['actions'].length === 0) return false - const action = submission['actions'].find( - (a) => a.action_type === 'aws_s3_upload' - ) - return action && action.state === 'processed' -} + if (submission["actions"].length === 0) return false; + const action = submission["actions"].find( + (a) => a.action_type === "aws_s3_upload", + ); + return action && action.state === "processed"; +}; ``` Another thing you could do is set up an [AWS S3 event notification](https://docs.aws.amazon.com/AmazonS3/latest/dev/NotificationHowTo.html). You could send a webhook to your server as soon as the PDF has been uploaded to your S3 bucket. This means that you wouldn't need to do any polling. diff --git a/integrations/overview.mdx b/integrations/overview.mdx index ef47fa1..336cdcb 100644 --- a/integrations/overview.mdx +++ b/integrations/overview.mdx @@ -3,7 +3,7 @@ title: Integrations Overview description: Configure integrations for your DocSpring account --- -import { LinkCard, Aside } from '@astrojs/starlight/components' +import { LinkCard, Aside } from "@astrojs/starlight/components"; Configure integrations for your DocSpring account. diff --git a/introduction.mdx b/introduction.mdx index 8dd6978..697bbc1 100644 --- a/introduction.mdx +++ b/introduction.mdx @@ -3,7 +3,7 @@ title: DocSpring Documentation description: DocSpring is a service that makes it easy to fill out and generate PDF documents. --- -import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components' +import { Card, CardGrid, LinkCard } from "@astrojs/starlight/components"; DocSpring is a service that makes it easy to fill out and generate PDF documents. diff --git a/reference/field-data-types.mdx b/reference/field-data-types.mdx index 836d3c0..9164a24 100644 --- a/reference/field-data-types.mdx +++ b/reference/field-data-types.mdx @@ -5,7 +5,7 @@ sidebar: order: 0 --- -import { Aside, Badge } from '@astrojs/starlight/components' +import { Aside, Badge } from "@astrojs/starlight/components"; export const DisplayTypes = ({ types }) => (
@@ -92,21 +46,13 @@ Or if you set the display type to "Text", the field could display the text "true If you add some Field Options, then the value must be one of those options. A select list will be displayed on online forms. -Field Options +Field Options ### Conditions When a _String_ field is displayed as a _Check_ or _Shape_, you can define a Condition. The field will only be displayed when the value matches the condition. The condition predicate can be one of: _Equals_, _Contains_, _Starts With_, _Ends With_, or _Regex_. -Conditions +Conditions ### Display Types @@ -125,31 +71,23 @@ You can define a Minimum and Maximum value. You can check the "Exclusive" checkb In the following example, the value must be an integer. The value must be greater than `0`, and less than or equal to `1000`. -Number Options +Number Options ### Formulas A _Number_ field can be a formula that performs a calculation. Formulas can reference other _Number_ fields. View the [Formula documentation](/docs/template-editor/formulas/) for more information about formula syntax, operators, and functions. -Formulas +Formula editor ### Conditions When a _Number_ field is displayed as a _Check_ or _Shape_, you can define a Condition. The field will only be displayed when the value matches the condition. The condition predicate can be one of: _Equals_, _Greater or Equal_, _Greater_, _Less or Equal_, _Less_, or _In Range_. -Number Conditions ### Display Types @@ -164,11 +102,7 @@ A _Boolean_ value must be either `true` or `false`. When a _Boolean_ field is displayed as _Text_, the text will be either "Yes" or "No". These strings can be configured for each field. You can also set default values in the template settings. -Boolean Text +Boolean text settings ### Check or Shape @@ -186,11 +120,7 @@ When _Include Time_ is checked, the value must be a timestamp formatted as: `YYY A _Date_ field can be formatted using a format string. DocSpring supports the [`strftime` format directives from the Ruby programming language](https://apidock.com/ruby/DateTime/strftime). -Date Options +Date field options ### Example @@ -200,11 +130,7 @@ Some forms may have separate fields for month, day, and year. You could configur - `%-d` for day - `%Y` for year -Date Formats +Separate date fields ### Display Types @@ -281,46 +207,21 @@ See the [Image Display Type](/docs/reference/field-display-types/#image) section ## Signature -A _Signature_ field adds a signature pad to the online form: - -Signature Field +A _Signature_ field allows you to collect legally binding e-signatures using our data requests feature. -The online form will submit the signature as a Base64 encoded image. +Signature field modal -When you are generating a PDF via an API request, the _Signature_ type is a subset of the [Image](#image) type: You can submit a Base64 encoded image (`base64`), or a URL where the image can be downloaded (`url`). - - - -You can also ask the user to type their full name. Then submit a `text` object with the user's name and their choice of typeface: - -```json -"signature": { - "text": { - "name": "John Smith", - "typeface": "Dancing Script" - }, -} -``` +You can also ask the user to type their full name and select a typeface from one of the following options: -- `name` must be the user's full name. -- `typeface` must be one of the following fonts: - - [Dancing Script](https://fonts.google.com/specimen/Dancing%20Script) - - [Satisfy](https://fonts.google.com/specimen/Satisfy) - - [Cookie](https://fonts.google.com/specimen/Cookie) - - [Great Vibes](https://fonts.google.com/specimen/Great%20Vibes) - - [Caveat](https://fonts.google.com/specimen/Caveat) - - [Sunshiney](https://fonts.google.com/specimen/Sunshiney) - - [Sedgwick Ave](https://fonts.google.com/specimen/Sedgwick%20Ave) - - [Sacramento](https://fonts.google.com/specimen/Sacramento) - - [Lovtony Script](https://www.dafont.com/lovtony.font) +- [Dancing Script](https://fonts.google.com/specimen/Dancing%20Script) +- [Satisfy](https://fonts.google.com/specimen/Satisfy) +- [Cookie](https://fonts.google.com/specimen/Cookie) +- [Great Vibes](https://fonts.google.com/specimen/Great%20Vibes) +- [Caveat](https://fonts.google.com/specimen/Caveat) +- [Sunshiney](https://fonts.google.com/specimen/Sunshiney) +- [Sedgwick Ave](https://fonts.google.com/specimen/Sedgwick%20Ave) +- [Sacramento](https://fonts.google.com/specimen/Sacramento) +- [Lovtony Script](https://www.dafont.com/lovtony.font)