> ## Documentation Index > Fetch the complete documentation index at: https://developers.gonitro.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Fill Forms > Fill PDF form fields with the Nitro API — supply values inline or via a CSV, JSON, XFDF, or FDF data file and get back a completed PDF. ## Parameters A JSON-encoded array of `{ "field": "", "value": }` objects. Each `field` must match the field name as it appears in the PDF template. Omit or pass `null` to read values from the attached data file instead. If no data file is provided and this field is empty, a 422 error is raised. **Example** ```json theme={null} [ {"field": "first_name", "value": "Jane"}, {"field": "last_name", "value": "Doe"}, {"field": "is_active", "value": "yes"} ] ``` When `true`, the request fails if any supplied field name does not match a field present in the PDF. When `false` (default), unrecognised field names are silently ignored and the remaining fields are still filled. ## Strict mode By default, extra field names in your payload are discarded without error. Enable `strict` when you want a hard guarantee that every key you supply maps to a real form field — useful for catching typos or schema drift between your data source and the PDF template. ### File Upload There are two ways to provide form field values: #### Inline form fields (using `params`): Pass the PDF document via the `file` parameter, and provide field values directly in the `fields` array within `params`: ```bash theme={null} curl --request POST \ --url https://api.gonitro.dev/generations \ --header 'Authorization: Bearer ' \ --header 'Accept: application/json' \ --form method=fill-forms \ --form 'params={"strict": false, "fields": [{"field": "first_name", "value": "Jane"}, {"field": "last_name", "value": "Doe"}]}' \ --form 'file=@document.pdf;type=application/pdf' ``` #### Data file (using `files[0]` and `files[1]`): Pass the PDF as `files[0]` and the data file as `files[1]`. The data file can be CSV, JSON, XFDF, or FDF format. Fill Forms accepts up to 25 input files per request, and their combined size must not exceed the 100 MB per-request limit. ```bash theme={null} curl --request POST \ --url https://api.gonitro.dev/generations \ --header 'Authorization: Bearer ' \ --header 'Accept: application/json' \ --form method=fill-forms \ --form 'params={"strict": false}' \ --form 'files[0]=@document.pdf;type=application/pdf' \ --form 'files[1]=@form.csv;type=text/csv' ``` Fill a PDF form by supplying field values against a form template. The endpoint maps the provided field data onto the template's form fields and returns a flattened PDF with the fields populated. ### Supported data file formats The `files[1]` data file must be sent with one of the following content types: | Format | Content type | | ------ | ---------------------------- | | CSV | `text/csv` | | JSON | `application/json` | | XFDF | `application/vnd.adobe.xfdf` | | FDF | `application/vnd.fdf` | The data file must use one of the four content types above. Other content types (including `application/octet-stream` and `text/plain`) are rejected with a `415` error. The formats are equivalent — each maps form field names to the values to set. The following all fill the same fields: CSV example: ```csv theme={null} first_name,last_name,is_active Jane,Doe,yes ``` JSON example: ```json theme={null} [ {"field": "first_name", "value": "Jane"}, {"field": "last_name", "value": "Doe"}, {"field": "is_active", "value": "yes"} ] ``` XFDF example: ```xml theme={null} Jane Doe yes ``` FDF example: ```text theme={null} %FDF-1.2 1 0 obj << /FDF << /Fields [ << /T (first_name) /V (Jane) >> << /T (last_name) /V (Doe) >> << /T (is_active) /V (yes) >> ] >> >> endobj trailer << /Root 1 0 R >> %%EOF ``` The field names must match the respective AcroForms names. Recognized checkbox values are: `true`, `yes`, `1`, `x` (case insensitive). All values are stringified (e.g. `{"age": 27}` is interpreted as `{"age": "27"}`). ### Output File Format The endpoint can return output either as JSON or as a binary file. The format depends on the `Accept` header (details below), which defaults to application/json. ### Processing When requesting JSON, you can run the operation synchronously or asynchronously. This is determined by the `Prefer` header (details below). * In sync mode, the response includes a URL pointing to the processed file. * In async mode, the request creates a Job, and the response contains the Job ID and status so you can track progress. Binary (octet-stream) responses are only available for synchronous operations. ### Custom File Delivery The endpoint supports custom file-delivery destinations through the optional delivery parameter. You can provide an upload target, such as your own PUT endpoint or a pre-signed S3 URL, and Nitro will upload the resulting file there. This works for both synchronous and asynchronous processing. * ### Sync delivery In synchronous calls, the [delivery](#body-delivery) parameter lets you direct Nitro to upload the output file to a custom URL endpoint or a pre-signed URL (e.g S3), by providing an upload url in the `uploadResultTo` or `uploadResultsTo` properties. #### Custom endpoint If implementing the upload endpoint by yourself, make sure your code or middleware configuration accepts requests without content-type headers. #### S3 delivery If you are using S3 to manage delivery uploads, follow this [AWS documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html) to generate a pre-signed PUT URL. If using the AWS provided Python script, omit the `Content-Type` in Params to get the pre-signed url. For example: ```python theme={null} url = generate_presigned_url( s3_client, "put_object", { "Bucket": args.bucket, "Key": args.key, # Content-Type: "application/octet-stream" => Omit! }, 1000) ``` * ### Async delivery In asynchronous flows, you can also provide a custom URL or pre-signed S3 object via `uploadResultTo` or `uploadResultsTo`, to upload your file(s) once the Job is done processing. #### Callback For asynchronous processing, you can also include a [callback](#body-delivery-callback) URL within the delivery parameter. This callback is a POST endpoint that Nitro will call once the Job is created and running, providing details about the file-processing job. Example of Nitro’s callback request body: ```json theme={null} { "jobID": "babe2aa7-9b5d-4eb2-a679-5fc12cf0a490", "location": "https://api.gonitro.dev/jobs/babe2aa7-9b5d-4eb2-a679-5fc12cf0a490" } ``` #### Response behavior Matrix This matrix shows the expected response behavior based on content type, sync/async mode, and custom file-delivery settings. | | **JSON (`application/json`)** | **Binary (`application/octet-stream`)** | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | **Synchronous** | Returns a JSON object with a file(s) URL(s). | Returns the processed file directly as binary. | | **Asynchronous (`respond-async`)** | Returns a JSON object with a Job ID and status. | Async preference ignored, returns sync binary. | | **Synchronous delivery** | File delivered to custom endpoint / Bucket, returns success confirmation. | N/A | | **Asynchronous delivery** | Returns a JSON object with a Job ID and status. The file(s) will be uploaded to the provided PUT endpoint / S3 Bucket at the end of process. If `callback` url is provided, Nitro will notify the endpoint with a JOB ID and location. | N/A | #### Limits The Platform API has the following limits: * File size: Maximum of 100 MB per request for direct uploads and synchronous requests; asynchronous requests with remote-file (URL) input allow up to 300 MB. This applies to single-file and multi-file requests (multi-file requests are limited by their combined size). Some operations allow more — Merge accepts up to 1.5 GB for asynchronous remote-file input. * Page count: Maximum of 500 pages per individual document, or 2500 pages for asynchronous requests with remote-file (URL) input. This applies to single-file and multi-file requests. Multiple documents may exceed the page limit in total. * Retention time: Inputs and outputs are deleted approximately 15 minutes after the operation completes. ### Request ## OpenAPI ````yaml fill-forms POST /generations openapi: 3.0.3 info: title: Nitro API - Document Intelligence Platform description: >- Consolidated API for document intelligence operations including conversions, extractions, transformations, and job management. **Supported Operations:** - **Conversions**: PDF ↔ MS Office, Images ↔ PDF, Various formats to PDF - **Extractions**: Text extraction, PII detection, Bounding box extraction, PDF properties - **Transformations**: Rotate, Split, Merge, Flatten, Password protection, Redaction - **Jobs**: Asynchronous processing with status monitoring and result retrieval **Global Limits:** - Standard requests (direct upload or synchronous): maximum file size 100MB, maximum 500 pages per document - Asynchronous requests with remote-file (URL) input: maximum file size 300MB, maximum 2500 pages per document Some operations allow more (e.g. Merge accepts up to 1.5GB for asynchronous remote-file input) — see the endpoint pages and changelog. version: 1.0.0 contact: name: Nitro API Support url: https://help.gonitro.com/support servers: - url: https://api.gonitro.dev description: Europe - url: https://api.us.gonitro.dev description: US security: [] tags: - name: Conversions description: >- Document format conversion operations including PDF to/from MS Office, images, and various other formats - name: Extractions description: >- Data extraction operations for text, metadata, PII detection, and bounding box information - name: Transformations description: >- PDF transformation operations including rotation, splitting, merging, compression, protection, and redaction - name: Generations description: >- Document generation operations such as filling PDF AcroForm fields from a data file or inline values - name: Jobs description: >- Asynchronous job management for monitoring, retrieving results, and canceling long-running operations - name: Presigned URLs description: >- Generate presigned URL pairs for uploading files directly to storage and referencing them in operations paths: /generations: post: tags: - Generations summary: Fill Forms description: Generate PDF document with filled form fields parameters: - name: Accept in: header schema: $ref: '#/components/schemas/AcceptHeader' - name: Prefer in: header schema: $ref: '#/components/schemas/PreferHeader' requestBody: required: true content: multipart/form-data: schema: type: object properties: method: type: string description: 'The Generations'' endpoint method: `fill-forms`' default: fill-forms enum: - fill-forms params: $ref: '#/components/schemas/FormFillParams' file: type: string format: binary description: >- The source PDF document when using inline field values via `params.fields`. Use this parameter when providing form field values directly instead of a data file. files: type: array items: type: string format: binary description: >- The source PDF and data file when using a data file. `files[0]` is the source PDF document (application/pdf). `files[1]` is the data file containing form field values (CSV, JSON, XFDF, or FDF format). delivery: $ref: '#/components/schemas/DeliverySingleFileOut' required: - method - params responses: '200': description: >- Returns either JSON or binary output depending on the Accept header (defaults to JSON). JSON responses include a file URL for synchronous tasks or a job status for asynchronous tasks. content: application/json: schema: oneOf: - $ref: '#/components/schemas/PlatformOperationFileResult' - $ref: '#/components/schemas/AsyncJobResponse' application/octet-stream: schema: type: string format: binary '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '413': $ref: '#/components/responses/ContentTooLarge' '415': $ref: '#/components/responses/UnsupportedMediaType' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/InternalServerError' security: - BearerAuth: [] components: schemas: AcceptHeader: type: string enum: - application/json - application/octet-stream - '*/*' default: '*/*' description: >- Controls response format and behavior. See endpoint description above for detailed response combinations. - `application/json`: Returns JSON response with operation result - `application/octet-stream`: Returns binary file content - `*/*`: Defaults to JSON response PreferHeader: type: string enum: - respond-async description: >- Controls synchronous vs asynchronous operation. See endpoint description above for behavior details. - `respond-async`: Makes request asynchronous, returns job status for polling - No value: Synchronous response FormFillParams: title: Fill Forms type: object properties: strict: type: boolean default: false description: >- Controls validation behavior when filling form fields. When `true`, requests fail with 422 if the input contains unknown field names or omits required fields; when `false`, unrecognized fields are silently ignored and only matching fields are filled. example: true fields: type: array nullable: true default: null description: >- Inline field name/value pairs to fill, as an alternative to supplying the values in a CSV, JSON, XFDF, or FDF data file. items: type: object properties: field: type: string description: Name of the PDF form field to fill. value: description: >- Value to set for the field. May be a string, number, boolean, or null. nullable: true oneOf: - type: string - type: integer - type: number - type: boolean required: - field - value example: - field: firstName value: Jane - field: lastName value: Doe DeliverySingleFileOut: type: object properties: uploadResultTo: $ref: '#/components/schemas/HTTPCall' callback: $ref: '#/components/schemas/Callback' description: >- This endpoint lets you supply your own URL to receive the single-file output. The URL may point to a custom API endpoint or a pre-signed S3 URL. The HTTP method defaults to PUT, but you can change it based on your implementation needs via the `verb` parameter. You can also provide custom headers, such as authentication headers or any others required by your endpoint. PlatformOperationFileResult: type: object title: Sync - Single File properties: file: $ref: '#/components/schemas/FileInfo' AsyncJobResponse: type: object title: Async - Job properties: jobID: type: string example: 01234567-89ab-cdef-0123-456789abcdef status: type: string enum: - running progress: type: number description: Progress of the job as a float between 0.0 and 1.0 format: float default: 0 example: 0 HTTPCall: type: object properties: URL: type: string description: Your delivery endpoint URL nullable: false format: uri verb: type: string description: The HTTP method default: PUT enum: - GET - POST - PUT - DELETE - PATCH headers: type: array nullable: true description: Headers your file delivery endpoint might need (Optional) items: $ref: '#/components/schemas/Header' required: - URL - verb Callback: type: object description: >- POST endpoint that will get JOB ID and location when processing starts only on async processesing (see example above) properties: URL: type: string description: Your POST endpoint callback URL. nullable: false format: uri headers: type: array description: Headers your callback endpoint might need items: $ref: '#/components/schemas/Header' required: - URL FileInfo: type: object properties: URL: type: string format: uri description: >- URL with processed file for download. Field will be `null` if `delivery` parameter for post-processing upload is defined. nullable: true contentType: type: string description: The file type example: application/json metadata: type: object properties: fileSizeBytes: type: number nullable: true pageCount: type: number description: Number of pages in resulting document. nullable: true BadRequestProblemDetail: type: object description: Bad Request error details example: type: https://developers.gonitro.com/docs/build-nitro/errors#400-bad-request title: Bad Request status: 400 detail: Request validation failed instance: /platform/generations allOf: - $ref: '#/components/schemas/ErrorResponse' UnauthorizedProblemDetail: type: object description: Unauthorized error details example: type: >- https://developers.gonitro.com/docs/build-nitro/errors#401-unauthorized title: Unauthorized status: 401 detail: Missing or invalid Authorization header instance: /platform/generations allOf: - $ref: '#/components/schemas/ErrorResponse' NotFoundProblemDetail: type: object description: Not Found error details example: type: https://developers.gonitro.com/docs/build-nitro/errors#404-not-found title: Not Found status: 404 detail: Resource not found instance: /platform/generations allOf: - $ref: '#/components/schemas/ErrorResponse' ContentTooLargeProblemDetail: type: object description: Content too large error details example: type: >- https://developers.gonitro.com/docs/build-nitro/errors#413-content-too-large title: Content too large status: 413 detail: Uploaded document exceeds the file size limit instance: /platform/generations allOf: - $ref: '#/components/schemas/ErrorResponse' UnsupportedMediaTypeProblemDetail: type: object description: Unsupported Media Type error details example: type: >- https://developers.gonitro.com/docs/build-nitro/errors#415-unsupported-media-type title: Unsupported Media Type status: 415 detail: The provided media type is not supported instance: /platform/generations allOf: - $ref: '#/components/schemas/ErrorResponse' UnprocessableEntityProblemDetail: type: object description: Unprocessable Entity error details example: type: >- https://developers.gonitro.com/docs/build-nitro/errors#422-unprocessable-entity title: Unprocessable Entity status: 422 detail: The request was well-formed but could not be processed instance: /platform/generations allOf: - $ref: '#/components/schemas/ErrorResponse' InternalServerErrorProblemDetail: type: object description: Internal Server Error details example: type: >- https://developers.gonitro.com/docs/build-nitro/errors#500-internal-server-error title: Internal Server Error status: 500 detail: An unexpected error occurred instance: /platform/generations allOf: - $ref: '#/components/schemas/ErrorResponse' Header: type: object properties: name: type: string value: type: string required: - name - value ErrorResponse: type: object properties: type: type: string description: A URI reference that identifies the problem type title: type: string description: A short, human-readable summary of the problem type status: type: integer format: int32 description: The HTTP status code detail: type: string description: A human-readable explanation specific to this occurrence instance: type: string description: A URI reference that identifies the specific occurrence responses: BadRequest: description: Bad Request - Invalid request parameters content: application/problem+json: schema: $ref: '#/components/schemas/BadRequestProblemDetail' Unauthorized: description: Unauthorized - Invalid or missing Authorization header content: application/problem+json: schema: $ref: '#/components/schemas/UnauthorizedProblemDetail' NotFound: description: Not Found - Resource not found content: application/problem+json: schema: $ref: '#/components/schemas/NotFoundProblemDetail' ContentTooLarge: description: Content Too Large - File size exceeds limit content: application/problem+json: schema: $ref: '#/components/schemas/ContentTooLargeProblemDetail' UnsupportedMediaType: description: Unsupported Media Type - File format not supported content: application/problem+json: schema: $ref: '#/components/schemas/UnsupportedMediaTypeProblemDetail' UnprocessableEntity: description: Unprocessable Entity - Request cannot be processed content: application/problem+json: schema: $ref: '#/components/schemas/UnprocessableEntityProblemDetail' InternalServerError: description: Internal Server Error - An unexpected error occurred content: application/problem+json: schema: $ref: '#/components/schemas/InternalServerErrorProblemDetail' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT ````