Skip to content

OP-FLATTEN-FORM-FIELDS: Flatten form fields

Flattens the form fields in a submitted PDF and returns the flattened document bytes, using the caller-selected inspection/flattening client.

Field Value
Operation ID OP-FLATTEN-FORM-FIELDS
Trigger Client submits POST v1/info/fields/flatten with PDF bytes
Entry endpoint POST v1/info/fields/flatten
Owning component InfoController.FlattenFormFields(byte[], bool) → PdfClientService.Flatten | PdfHelper (Syncfusion)
Inputs Request body: byte[] PDF; query: useClient (default true)
Outputs Bare byte[] (flattened PDF bytes; base64-encoded string in the JSON response)*
Failure response No try/catch on this action — any exception produces framework exception detail (IncludeErrorDetailPolicy.Always) before ApiResponseHandler runs; the final client-visible envelope is unknown** (see Endpoints: Error response shape)

Steps

  1. useClient (default true) selects the flattening implementation (BR-PDFAPI-021):
  2. true (default): PdfClientService.Flatten (iTextSharp) is invoked, which first validates the %PDF- signature (BR-PDFAPI-005).
  3. false: PdfHelper.FlattenFormFields (Syncfusion) is invoked instead.

PdfClientService.Flatten is implemented in PdfAPI.Core, documented in full at Flatten form fields (OP-07). PdfHelper.FlattenFormFields is implemented in PdfApi.SyncFusionCore, documented in full at Inspect and flatten PDF form fields (OP-SFC-013). Both behaviors are summarized here only as observed on this request path.

Origin: The useClient = true flattening behavior in this step is implemented in PdfAPI.Core; the useClient = false flattening behavior is implemented in PdfApi.SyncFusionCore. See the linked operation pages for the full delegated logic. 2. On the useClient = true path, a non-PDF payload raises PdfException, which escapes uncaught to the framework, producing exception detail before ApiResponseHandler runs; the final client-visible envelope is unknown**. 3. The bare byte[] result is returned — HTTP 200, serialized as a base64 string by the default JSON formatter.

Process flow

The following diagram shows the client-selection and validation sequence for flattening form fields.

flowchart TD
    A["POST v1/info/fields/flatten"] --> B{"useClient?"}
    B -->|true default| C["PdfClientService.Flatten: iTextSharp"]
    B -->|false| D["PdfHelper.FlattenFormFields: Syncfusion"]
    C --> E{"Valid PDF?"}
    E -->|No| F["PdfException escapes to framework: 500"]
    E -->|Yes| G["Return flattened bytes, 200"]
    D --> G

Transaction and side effects

Aspect Finding
Unit of work None
Commit point Not applicable — no database access
Records written None
Downstream calls None
Repeat-call behavior Same output for the same input; safe to repeat*

Logging

Surface Written content
— No dedicated logging observed on this path beyond framework-level exception logging on an uncaught failure

Error handling

  • Non-PDF payload on the useClient = true path: PdfException escapes uncaught, producing framework exception detail before ApiResponseHandler runs; the final client-visible envelope is unknown** (BR-PDFAPI-005; see Endpoints: Error response shape).

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts. Statements marked with ** could not be confirmed; treat as unknown until verified.

Sources

  • PdfAPI\Controllers\v1\InfoController.cs
  • PdfAPI.Core\Services\PdfClientService.cs
  • PdfApi.SyncFusionCore\PdfHelper.cs