POST$0.01/page

https://pdfmage.app/api/v1/field-mapping

Field Mapping

Analyze PDF form fields and map them to relevant document content using AI. Get detailed field analysis, position data, and intelligent mapping suggestions for each form field.

Request

multipart/form-data

Request Body

filefilerequired

PDF file with form fields to analyze and map

Maximum 10MB, PDF format only, must contain form fields

AI-Powered Mapping

Advanced machine learning analyzes form field names, positions, and document content to provide intelligent mapping suggestions with confidence scores.

Request Example

curl --request POST \
  --url https://pdfmage.app/api/v1/field-mapping \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer pk_live_abc123...' \
  --form 'file=@/path/to/form.pdf'

Response

application/json

Response Body

fileNamestring - Original filename of processed document

processedAtstring (ISO 8601) - Processing completion timestamp

pageCountnumber - Total number of pages in document

fieldsarray

Array of detected form fields with mapping information

namestring - Field name/identifier

typestring - Field type (text, checkbox, radio, dropdown, signature)

requiredboolean - Whether field is required

readonlyboolean - Whether field is read-only

tooltipstring - Help text for the field (optional)

defaultValuestring - Default value for the field (optional)

textMaxLengthnumber - Maximum length for text fields (optional)

pagenumber - Page number containing this field

positionobject - Field bounding box

• x: number - X coordinate

• y: number - Y coordinate

• width: number - Field width

• height: number - Field height

optionsarray - Available options for dropdown/radio fields

mappingobject - AI mapping results

• mainText: string - Most relevant text for this field

• contextText: string - Broader context where text appears

• confidence: number - Mapping confidence score (0-1)

• reasoning: string - AI explanation for mapping decision

extractedTextobject

Comprehensive text extraction with spatial data

fullTextstring - Complete extracted text from document

pagesarray - Per-page structured text data

• pageNumber: number - Page number (1-based)

• dimensions: object - Page dimensions

• text: string - Page text content

• blocks: array - Text blocks with bounding boxes

• paragraphs: array - Paragraphs with bounding boxes

metadataobject

Processing metadata and statistics

pageCountnumber - Total pages in document

hasAcroFormboolean - Whether PDF has proper form structure

extractionMethodstring - Method used to extract fields ('pdf-lib' or 'fallback')

processingTimeMsnumber - Total processing time in milliseconds

statisticsobject - Mapping statistics

• totalFields: number - Total fields detected

• mappedFields: number - Successfully mapped

• unmappedFields: number - Could not be mapped

• averageConfidence: number - Average confidence (0-1)

Success Response Example

{
  "fileName": "employment-form.pdf",
  "processedAt": "2024-01-15T10:30:45.123Z",
  "fields": [
    {
      "name": "firstName",
      "type": "text",
      "required": true,
      "readonly": false,
      "tooltip": "Enter your legal first name",
      "defaultValue": "",
      "textMaxLength": 50,
      "page": 1,
      "position": {
        "x": 120.5,
        "y": 680.2,
        "width": 200,
        "height": 20
      },
      "options": null,
      "mapping": {
        "mainText": "First Name: John",
        "contextText": "Personal Information Section",
        "confidence": 0.95,
        "reasoning": "Direct label match 'First Name' found adjacent to field with value 'John'"
      }
    },
    {
      "name": "employmentDate",
      "type": "text",
      "required": false,
      "readonly": false,
      "tooltip": null,
      "defaultValue": null,
      "textMaxLength": null,
      "page": 1,
      "position": {
        "x": 120.5,
        "y": 640.8,
        "width": 200,
        "height": 20
      },
      "options": null,
      "mapping": {
        "mainText": "Start Date: January 15, 2024",
        "contextText": "Employment Details",
        "confidence": 0.87,
        "reasoning": "Field name 'employmentDate' semantically matches 'Start Date' in employment section"
      }
    }
  ],
  "extractedText": {
    "fullText": "Employment Application\n\nFirst Name: John\nLast Name: Doe\nStart Date: January 15, 2024...",
    "pages": [
      {
        "pageNumber": 1,
        "dimensions": {"width": 612, "height": 792, "unit": "px"},
        "text": "Employment Application Form...",
        "blocks": [...],
        "paragraphs": [...]
      }
    ]
  },
  "metadata": {
    "pageCount": 1,
    "hasAcroForm": true,
    "extractionMethod": "pdf-lib",
    "processingTimeMs": 2847,
    "statistics": {
      "totalFields": 12,
      "mappedFields": 10,
      "unmappedFields": 2,
      "averageConfidence": 0.83
    }
  }
}

Response Headers

HTTP/1.1 200 OK
Content-Type: application/json
X-Credits-Used: 0.01
X-Credits-Remaining: 4.99
X-Credits-Currency: USD

Error Responses

400

Bad Request

Invalid file format, missing file, or corrupted PDF

401

Unauthorized

Invalid or missing API key

402

Payment Required

Insufficient credit balance

413

Payload Too Large

File exceeds maximum size limit (10MB)

422

Unprocessable Entity

PDF contains no fillable form fields

No Fields Error

{
  "error": "Unprocessable Entity",
  "message": "No form fields found in PDF",
  "details": {
    "code": "NO_FORM_FIELDS",
    "pageCount": 2,
    "suggestion": "Ensure PDF contains fillable form fields"
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "requestId": "req_abc123"
}

Processing Error

{
  "error": "Bad Request", 
  "message": "Invalid file format",
  "details": {
    "code": "INVALID_FILE_FORMAT",
    "allowedFormats": ["pdf"],
    "receivedFormat": "docx"
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "requestId": "req_def456"
}