From 1b2197670d6e747be1f7133c4a9c3726298f9f1a Mon Sep 17 00:00:00 2001
From: Jonathan Rhyne <jonathan@pspdfkit.com>
Date: Thu, 5 Feb 2026 10:55:52 -0500
Subject: [PATCH 1/2] feat: add applyInstantJson build action for form filling

- Add ApplyInstantJsonActionSchema for PDF form filling, form field creation, and annotation import
- Include schema in BuildActionSchema discriminated union
- Add unit tests for schema validation (valid input, missing file rejection)
---
 src/schemas.ts     | 18 ++++++++++++++++--
 tests/unit.test.ts | 16 +++++++++++++++-
 2 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/src/schemas.ts b/src/schemas.ts
index 9e97706..78a7341 100644
--- a/src/schemas.ts
+++ b/src/schemas.ts
@@ -197,6 +197,21 @@ export const ApplyXfdfActionSchema = z.object({
     ),
 })
 
+export const ApplyInstantJsonActionSchema = z.object({
+  type: z
+    .literal('applyInstantJson')
+    .describe(
+      'Apply Instant JSON to the document. Used for filling PDF form fields, creating form fields, ' +
+        'and importing annotations. The file should be in Nutrient Instant JSON format.',
+    ),
+  file: z
+    .string()
+    .describe(
+      'The path to the Instant JSON file or a reference to a file in the multipart request. ' +
+        'Resolves to sandbox path if enabled, otherwise resolves to the local file system.',
+    ),
+})
+
 export const FlattenActionSchema = z.object({
   type: z.literal('flatten').describe('Flatten the annotations in the document.'),
 
@@ -359,8 +374,7 @@ export const ApplyRedactionsActionSchema = z.object({
 })
 
 export const BuildActionSchema = z.discriminatedUnion('type', [
-  // For now, we will not support applying Instant JSON.
-  // ApplyInstantJsonActionSchema,
+  ApplyInstantJsonActionSchema,
   ApplyXfdfActionSchema,
   FlattenActionSchema,
   OcrActionSchema,
diff --git a/tests/unit.test.ts b/tests/unit.test.ts
index 6f1773e..9285b39 100644
--- a/tests/unit.test.ts
+++ b/tests/unit.test.ts
@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import fs, { Stats } from 'fs'
 import { Readable } from 'stream'
-import { AiRedactArgsSchema, Instructions, SignatureOptions } from '../src/schemas.js'
+import { AiRedactArgsSchema, BuildActionSchema, Instructions, SignatureOptions } from '../src/schemas.js'
 import { config as dotenvConfig } from 'dotenv'
 import { performBuildCall } from '../src/dws/build.js'
 import { performSignCall } from '../src/dws/sign.js'
@@ -40,6 +40,20 @@ function createMockStream(content: string | Buffer): Readable {
   return readable
 }
 
+describe('BuildActionSchema', () => {
+  it('should parse applyInstantJson actions', () => {
+    const result = BuildActionSchema.safeParse({ type: 'applyInstantJson', file: '/test.json' })
+
+    expect(result.success).toBe(true)
+  })
+
+  it('should reject applyInstantJson actions without a file', () => {
+    const result = BuildActionSchema.safeParse({ type: 'applyInstantJson' })
+
+    expect(result.success).toBe(false)
+  })
+})
+
 describe('API Functions', () => {
   const originalEnv = process.env
 

From 13571c2f26116590d21066bb949f7d6f51be46e7 Mon Sep 17 00:00:00 2001
From: Jonathan Rhyne <jonathan@pspdfkit.com>
Date: Thu, 5 Feb 2026 20:07:35 -0500
Subject: [PATCH 2/2] fix: handle applyInstantJson file refs and add build
 example

---
 src/dws/build.ts            |  4 ++++
 tests/build-api-examples.ts | 21 +++++++++++++++++++++
 2 files changed, 25 insertions(+)

diff --git a/src/dws/build.ts b/src/dws/build.ts
index 66c3696..8a39c47 100644
--- a/src/dws/build.ts
+++ b/src/dws/build.ts
@@ -88,6 +88,10 @@ async function processActionFileReferences(action: Action): Promise<FileReferenc
     const fileReference = await processFileReference(action.file)
     action.file = fileReference.key
     return fileReference
+  } else if (action.type === 'applyInstantJson' && 'file' in action && typeof action.file === 'string') {
+    const fileReference = await processFileReference(action.file)
+    action.file = fileReference.key
+    return fileReference
   }
 
   // No need to parse files for the other actions
diff --git a/tests/build-api-examples.ts b/tests/build-api-examples.ts
index 58ecbc5..c50b396 100644
--- a/tests/build-api-examples.ts
+++ b/tests/build-api-examples.ts
@@ -290,6 +290,27 @@ export const applyXfdfExample: BuildAPIArgs = {
   outputPath: 'output_pdf.pdf',
 }
 
+// Example with applying Instant JSON
+export const applyInstantJsonExample: BuildAPIArgs = {
+  instructions: {
+    parts: [
+      {
+        file: 'example.pdf',
+      },
+    ],
+    actions: [
+      {
+        type: 'applyInstantJson',
+        file: 'example.json',
+      },
+    ],
+    output: {
+      type: 'pdf',
+    },
+  },
+  outputPath: 'output_pdf.pdf',
+}
+
 // Example with redactions using preset
 export const redactionsPresetExample: BuildAPIArgs = {
   instructions: {