> ## 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: ```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. This applies to single-file and multi-file requests. * Page count: Maximum of 500 pages per individual document. This applies to single-file and multi-file requests. Multiple documents may exceed 500 pages 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:** - Maximum file size: 100MB - Maximum number of pages: 500 version: 1.0.0 contact: name: Nitro API Support url: https://help.gonitro.com/support servers: - url: https://api.gonitro.dev description: API server 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 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 ````