← Home

Structured Data Extraction API

The /ocr.json endpoint extracts named fields from an image or document.

The endpoint returns typed JSON. Use the fields query parameter to select the values in the response.

Endpoint

POST https://api.ocrskill.com/ocr.json

Each request requires a bearer token.

Authorization: Bearer sk-your-key-here

Use this command to get a free API key.

curl https://api.ocrskill.com/get-key.json

Quick start

Add the field names to fields. Then upload a file.

curl "https://api.ocrskill.com/ocr.json?fields=last_name,first_name,nationality,birthdate" \
  -H "Authorization: Bearer sk-your-key-here" \
  -F "file=@identity-card.pdf"

The endpoint returns this JSON.

{
  "last_name": "MUSTERMANN",
  "first_name": "ERIKA",
  "nationality": "DEUTSCH",
  "birthdate": "1964-08-12"
}

Send a file

The endpoint accepts multipart uploads, raw files, and JSON data URIs.

The maximum file size is 20 MB.

Multipart upload

Send the file in the file, image, document, or data form field.

curl "https://api.ocrskill.com/ocr.json?fields=thumbnail_hook_text,video_title,video_channel" \
  -H "Authorization: Bearer sk-your-key-here" \
  -F "file=@thumbnail.jpg"

Raw binary upload

Send the file bytes with the correct Content-Type.

curl "https://api.ocrskill.com/ocr.json?fields=company_name,invoice_date" \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Content-Type: application/pdf" \
  --data-binary "@invoice.pdf"

JSON body with a data URI

Send a JSON object with a data URI in document_url (similar/compatible with the Mistral API).

curl "https://api.ocrskill.com/ocr.json?fields=title,publish_date" \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "document_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
  }'

Supported file types

The endpoint supports these image types:

  • PNG
  • JPEG
  • WebP
  • GIF
  • BMP
  • TIFF

The endpoint also supports these document types:

  • PDF
  • Microsoft Word (DOC and DOCX)
  • Microsoft Excel (XLS and XLSX)
  • Microsoft PowerPoint (PPT and PPTX)
  • OpenDocument text, spreadsheet, and presentation files (ODT, ODS, and ODP)
  • RTF
  • CSV

Select fields

The fields parameter contains a comma-separated list of field names.

Required fields

A field name without a suffix requires a value. The endpoint returns 400 when it cannot find that value.

?fields=last_name,first_name,birthdate

Optional fields

Add ? to make a field optional. The response does not include an optional field when the endpoint cannot find it.

?fields=last_name,first_name,birthdate?,nationality?

Use discovery mode

Omit fields to use discovery mode. In this mode, the endpoint treats all supported fields as optional.

The response includes only fields that the endpoint finds.

curl "https://api.ocrskill.com/ocr.json" \
  -H "Authorization: Bearer sk-your-key-here" \
  -F "file=@report.docx"

Handle errors

Situation Status Notes
Unknown field name in fields 400 The error identifies the unsupported field.
Empty field name 400 Remove blank values and trailing commas.
Duplicate field name 400 List each field only once.
Missing required field 400 The error includes extraction details and the extracted input_text.
Missing or invalid bearer token 401 Send Authorization: Bearer sk-....
Unsupported or unknown file type 400 Send one of the supported file types.

The endpoint formats date fields as YYYY-MM-DD. It removes spaces from the start and end of string values.

The endpoint rejects the literal string "null".

Supported fields

You can select any mix of these field names in one request.

People

Field Type Description
last_name string Family name or surname.
first_name string Given name.
birthdate date Date of birth (YYYY-MM-DD).
sex_gender string Sex / gender.

Addresses

Field Type Description
street_name string Street name from a postal address.
street_number string Street, building, or house number.
address_rest string Block, entrance, floor, apartment, or PO box.
town_or_city string Town, city, municipality, or locality.
county string County, district, or administrative subdivision.
judet string Romanian judet or equivalent county-level subdivision.
region string Region, province, state, or larger area.
country string Country name.

ID Card

Field Type Description
nationality string Nationality.
cnp string Personal identification number (Cod numeric personal).
id_card_series_number string ID card series/number.
expiration_date date ID card date of expiry (YYYY-MM-DD).
issue_date date ID card date of issue (YYYY-MM-DD).
id_card_issuer string Name of ID card issuer.
id_card_birth_place string Place of birth as written on the ID card.

Vehicle Registration

Field Type Description
certificate_id string Registration certificate number or series.
license_plate string A: vehicle registration number or license plate.
first_registration_date date B: date of first registration (YYYY-MM-DD).
holder_last_name string C.1.1: family name of the holder.
holder_company string C.1.1: company name of the holder.
holder_first_name string C.1.2: given name of the holder.
holder_full_address string C.1.3: full address or headquarters of the holder.
owner_last_name string C.2.1: family name of the owner.
owner_company string C.2.1: company name of the owner.
owner_first_name string C.2.2: given name of the owner.
owner_full_address string C.2.3: full address or headquarters of the owner.
vehicle_brand string D.1: vehicle make or brand.
vehicle_model string D.2: type, variant, version, or model.
vehicle_commercial_summary string D.3: commercial description or model summary.
vehicle_identification_number string E: VIN or chassis number.
max_technical_weight string F.1: maximum technically permissible laden mass.
vehicle_mass string G: mass of the vehicle in service.
registration_valid_until date H: registration validity end date (YYYY-MM-DD).
registration_date date I: registration date (YYYY-MM-DD).
certificate_issue_date date I.1: certificate issue date (YYYY-MM-DD).
vehicle_category string J: vehicle category.
type_approval_number string K: type approval number.
engine_capacity string P.1: engine cylinder capacity.
engine_power string P.2: maximum net engine power.
fuel_type string P.3: fuel type or power source.
power_to_weight_ratio string Q: power-to-weight ratio, when present.
vehicle_color string R: vehicle color.
seats string S.1: number of seats, including the driver.
standing_places string S.2: number of standing places, when present.
vehicle_identification_series string Y: series of the vehicle identification book.
certificate_issuer string Z: name of certificate issuer.
last_itp_date date Date of last periodic technical inspection (YYYY-MM-DD).

Companies, invoices, and receipts

Field Type Description
company_name string Company, organization, or legal entity name.
buyer_name string Buyer name.
seller_name string Seller name.
total_amount number Total amount invoiced or paid.
invoice_date date Invoice issue date.
receipt_date date Receipt issue date.

Written Works

Field Type Description
title string Article title.
sub_title string Article subtitle.
article_abstract string Article abstract/summary section.
article_body string Article content body.
publish_date date Content publish date (YYYY-MM-DD).
article_tags string Content tags, comma separated.
tags string Content tags, comma separated.
concise_summary string A concise summary of the content, written fresh if none is present.

Events

Field Type Description
event_name string Event name or title.
event_venue string Event venue, location, or venues.
event_dates string Event date or interval, in text form.
event_date date Event date or partial date (YYYY-MM-DD).

Video Thumbnails

Field Type Description
thumbnail_hook_text string Video/clip hook text as written.
video_title string Video/clip title.
video_channel string Creator channel name.
video_length_str string Video/clip length, exactly as written.
date_posted_str string Publish date, exactly as written.

Extract as Markdown instead of structured JSON

Use the /ocr endpoint when you need Markdown instead of structured fields. It accepts the same file types.

curl https://api.ocrskill.com/ocr \
  -H "Authorization: Bearer sk-your-key-here" \
  -F "file=@example.pdf"

Frequently asked questions

What does structured data mean?

Structured data uses named fields and consistent types. The /ocr.json endpoint returns strings, numbers, and dates that your application can read directly.

Is this Google structured data or schema.org markup?

No. Google structured data describes web pages for search engines. It uses JSON-LD or microdata in a web page.

OCRskill extracts typed JSON from files. Your application can store or process this JSON.

Does the output have a JSON schema?

Yes. OCRskill creates the response schema from the requested fields.

Date fields use YYYY-MM-DD. Each field in this reference maps to one typed JSON property.

Can I do PDF to JSON, image to PDF, or PDF to image?

You can send a PDF directly to /ocr.json. You do not have to convert its pages to images.

OCRskill does not convert images to PDFs or PDFs to images.

How do I extract text from an image (image to text)?

Call /ocr to extract Markdown. Call /ocr.json with fields to extract named values.

Can I turn an image into a prompt (image to prompt)?

Call /ocr to extract Markdown for a prompt. Use /ocr.json when the prompt needs only specific values.

Why did the extraction fail?

The endpoint returns 400 when it cannot complete an extraction. Read the error message for the cause.

Common causes include a missing required field, an unknown field, a duplicate field, or an unsupported file type.

The error also includes input_text. Use this value to check the text that OCRskill extracted before the structured extraction failed.

Can I use OCRskill with Claude?

Yes. Use OCRskill to extract Markdown or JSON. Then send the result to Claude.