---
title: "Detect Mappings"
method: POST
path: "/api/pdf/detect-mappings"
tags: ["PDF Form Processing"]
---

# Detect Mappings

`POST /api/pdf/detect-mappings`

## Request

- Base URL: `https://api.qomplement.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.qomplement.com/api/pdf/detect-mappings`
- Auth: none declared

Use AI to intelligently map document data to PDF form fields.

Supports two modes:
1. Legacy: Single document via document_data field
2. New: Multiple documents via documents array with schema descriptions

The new mode searches across all documents and returns alternatives.

Args:
    request: Contains base64-encoded PDF and document data

Returns:
    DetectMappingsResponse with suggested field mappings and alternatives

## Request body

- PdfRoutesDetectMappingsRequest: Request model for mapping detection - supports multiple documents
  - `pdf_content` string, required
  - `document_data` object, nullable
  - `documents` PdfRoutesDocumentData[], nullable
    - `id` string, required
    - `name` string, required
    - `extracted_data` object, nullable
  - `field_schema` SchemaField[], nullable
    - `name` string, required
    - `type` string
    - `description` string
  - `schema` SchemaField[], nullable
    - `name` string, required
    - `type` string
    - `description` string
  - `high_precision` boolean
  - `field_descriptions` object, nullable
  - `custom_fields` object[], nullable
  - `agent_rules` string, nullable

## Response `200`

Successful Response

- PdfRoutesDetectMappingsResponse: Response model for mapping detection
  - `success` boolean, required
  - `mappings` PDFFieldMapping[], required
    - `pdf_field` string, required
    - `display_name` string, nullable
    - `field_type` string, nullable
    - `description` string, nullable
    - `source_field` string, required
    - `value` string, nullable
    - `confidence` number
    - `reason` string, nullable
    - `document_id` string, nullable
    - `document_name` string, nullable
    - `page_number` integer
    - `alternatives` MappingAlternative[]
      - `value` string, required
      - `document_id` string
      - `document_name` string
      - `page_number` integer
      - `source_field` string
      - `confidence` number
      - `reason` string
  - `error` string, nullable
  - `notice` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/qomplement/apis/qomplement-api.md) - [All operations](https://skmtc.dev/qomplement/apis/qomplement-api/llms.txt) - [OpenAPI document](https://skmtc.dev/qomplement/apis/qomplement-api/revisions/6fe617c112ef?raw)