Skip to content
pdfconversionapi

Read PDF metadata API

Send a PDF to POST /v2/convert/pdf/to/meta and get one JSON file describing it: document properties, every page's size, bookmarks, form fields with their values, comments, links, attachments, fonts and protection. The PDF itself is only read.

Endpoint
POST /v2/convert/pdf/to/meta
Accepts
pdf
Sample timing
23 ms median of 5 runsHow we measure
Request size
Up to 10 MB on the Free plan or 100 MB on paid plans, all files together

Request and response

Every sample below ran against the API before this page was published. Set PDFCONVERSIONAPI_KEY to your key and run it as is.

curl -sS -X POST \
  https://api.pdfconversionapi.com/v2/convert/pdf/to/meta \
  -H "Authorization: Bearer $PDFCONVERSIONAPI_KEY" \
  -F File=@greenhouse-inspection.pdf \
  -o response.json

# FileData is base64. Save the first file in converted/,
# or print the JSON error.
if jq -e '.Files' response.json > /dev/null; then
  mkdir -p converted
  name=$(jq -r '.Files[0].FileName' response.json)
  jq -r '.Files[0].FileData' response.json \
    | base64 --decode > "converted/$name"
else
  cat response.json
fi
200 OK23 ms median1 file, 4.3 KB
{
  "ConversionCost": 1,
  "ConversionTime": 0.023,
  "Files": [
    {
      "FileName": "greenhouse-inspection.json",
      "FileExt": "json",
      "FileSize": 4403,
      "FileData": "ewogICJhbm5vdGF0aW9ucyI6…"
    }
  ]
}

Response from our test run on 2026-11-03. ConversionTime shows the median of 5 runs. FileData is shortened here; the real response carries the whole file as base64.

The sample and the result

The same file the code sends. Download the input and the output and compare them yourself.

greenhouse-inspection.json, first 30 of 215 lines

{  "annotations": [    {      "author": "J. Marlow",      "contents": "Thursday reading looks low. Check sensor B position.",      "in_reply_to": null,      "modified": null,      "name": "note-sensor-b",      "page": 2,      "rect": [        541.3200073242188,        95.62999725341795,        557.3200073242188,        111.62999725341795      ],      "type": "Text"    },    {      "author": "J. Marlow",      "contents": "Both days were sunny; vents opened about 40 minutes late.",      "in_reply_to": null,      "modified": null,      "name": "note-over-limit",      "page": 2,      "rect": [        139.61000061035156,        266.9800109863281,        322.95001220703125,        279.3599853515625      ],
Input
greenhouse-inspection.pdf (115 KB)
Output
greenhouse-inspection.json (4.3 KB)
Source
A three-page greenhouse inspection report for a fictional nursery, with form fields, comments and attached files, made by us for this site. (CC0-1.0). How it was made
Made by
2026-11-04, API build 9eeeb0640aba

Parameters

Send these as form fields next to the file. Names are case-insensitive. If you set one of the documented options below that we don't support yet, the request fails with a 400 that names it instead of returning a file made without it.

ParameterWhat it does
PasswordstringOpens a PDF that needs a password; the open password and the owner password both work. With the owner password, security.opened_as_owner is true and every permission reads true, because the owner may do everything. Send the open password, or none, to see the restrictions readers get. A wrong password on a file that opens without one is ignored: our owner-restricted copy sent with Password=nope returned the same report as with no password, opened_as_owner false.
FileNamestringName of the JSON file without the extension: FileName=report-info gives report-info.json. Left out, the upload's name is used.
StoreFileboolean, default falseReturn a download link (Url and FileId) to the JSON instead of its data; the link expires after 3 hours.

What carries over, and what doesn't

Kept

  • Document properties: title, author, subject and keywords as stored, creator and producer as null when empty, and custom entries such as InspectionID: H3-2026-43 under custom
  • page_count and each page's width, height, rotation and label: 612 x 792, 792 x 612 and 612 x 792 points for the sample
  • The 3 bookmarks with the page each opens
  • All 6 form fields with kind (Text, CheckBox, Signature), name, page and value
  • Comments with type, author, text and page: the sample's highlight, sticky note and pinned file attachment
  • The web link on page 1 with its URL, both attached files with name, size in bytes and description, and each font with its embedded and subset flags
  • Protection: method (AES, 256-bit for our test copies), the printing level and each permission; plus repairs notes for a damaged file

Lost or not yet supported

  • Creation and modification dates. The sample's CreationDate of 28 October 2026 is in the file but not in the JSON.
  • Which page uses which font. Fonts are listed once for the whole document: the sample's 6 font objects, 2 per page, come back as 2 entries, with the six-letter subset prefix removed from the names.
  • The pop-up windows that belong to comments. The sample has 5 annotation objects besides links and fields; the JSON lists the 3 visible ones.
  • Attachment contents. Only names, sizes and descriptions are listed; /v2/convert/pdf/to/extract-attachments returns the files.

Limits

  • A PDF that needs a password returns 422 "the input file is password-protected" until Password is sent. Files that only restrict printing, copying or editing, and signed files, are read without one.
  • Rectangles (rect) are in points measured from the top-left corner of the page, not from the bottom-left as inside a PDF: the sticky note whose box runs from y 500.37 to 516.37 on the 612 pt high page 2 is reported as 95.63 to 111.63.
  • One PDF per request, up to 10 MB on the Free plan or 100 MB on paid plans. PageRange is not read; every page is described.

Where teams use it

Check uploads before converting them

Read page_count, page sizes, security.protected, has_javascript and xfa first, then route or reject the file: ask for a password, refuse forms that run scripts, or send oversized sheets to a different step.

Pull filled-in form values into a database

Each field comes back with its name, kind, page and value. The sample returns inspector: J. Marlow, both dates and the two checkboxes as Yes and Off, ready to store without parsing the PDF yourself.

Collect review comments and index documents

The annotations list carries each comment's author, text and page, and the title, author, keywords and custom properties can feed a search index or a document system's metadata fields.

Questions

Does it return the values typed into form fields?

Yes. Each entry in fields has name, kind, page and value. Checkboxes report their export value (Yes) or Off, and a signature field that holds a signature reports signed.

Why are the creation and modification dates missing?

They are not part of the report today, even though the file stores them: the sample's CreationDate of 28 October 2026 is in the PDF and absent from the JSON. Read them with a PDF library on your side if you need them.

What do the security flags mean?

They say what a reader may do with the file: print (none, low or high), copy, modify, annotate, fill forms, assemble pages and copy for accessibility. Our owner-restricted copy reported printing none and copy false. Opened with the owner password, the same file reports everything allowed and opened_as_owner: true.

Can it read a damaged PDF?

Usually. A copy of the sample with its cross-reference table cut off returned 200 with two repairs notes, the last one "rebuilt cross-reference index from 76 object headers". Its title came back null, because the trailer that pointed to the document information was gone. /v2/convert/pdf/to/repair writes a fixed copy.

Does the request change my PDF?

No. Only the JSON is returned; the PDF you upload is read and not written back.

Convert your first PDF file in a minute.