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

# Detect Mappings

`POST /api/pdf/detect-mappings`

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.net/qomplement/apis/fastapi.md) · [All operations](https://skmtc.net/qomplement/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/qomplement/fastapi/versions/718de1c0d866/schema)