Using Rows Vision API to Import data from images and PDFs

Introduction

Rows Vision API lets you turn any image or PDF into structured spreadsheet data. Instead of typing or copy-pasting, the Vision endpoint scans files (PDFs, JPG/PNG/WebP images) and extracts tables or key values using AI. This is perfect for invoices, receipts, charts, or any “trapped” data. You simply upload the file via API, and Rows gives you back the data ready to analyze or save in your workspace.

How does it work?

The Vision API has three modes, set by the mode query parameter. Each mode serves a different need:

• Read mode (mode=read): Extracts table data and returns it immediately as JSON. No spreadsheet is created.
• Read simplified mode (mode=read_simplified): Similar to Read mode but returns a simpler JSON format (tables with name and items where each item is a 2D array of strings). This is useful for easy parsing or feeding into other tools.
• Create mode (mode=create): Extracts tables and creates a new Rows spreadsheet with the data. The response includes the new spreadsheet’s ID or URL. (You can include the folder_id for where to save the sheet, and your API key must have Editor access to that folder. If not present the system will use the first available folder.)

Read mode

Use Read mode when you want to pull data from an image/PDF on the fly. For example, to get a spreadsheet of an invoice without saving it in Rows. The API call returns a JSON object with the extracted table data.

Example cURL request:

1curl --location --request POST 'https://api.rows.com/v1/vision/import' \
2--header 'Authorization: Bearer {YOUR API TOKEN}' \
3--header 'Accept: application/json' \
4--form 'folder_id="7cbc1000-8141-11ed-a1eb-0242ac120002"' \
5--form 'mode="read"' \
6--form 'instructions="Extract table data from images"' \
7--form 'files=@"path/to/image1.png"' \
8--form 'files=@"path/to/image2.pdf"'

Example response (JSON):

1{
2  "tables": [
3    {
4      "name": "Sheet 1",
5      "items": [
6        [
7          {
8            "col": "0",
9            "row": "0",
10            "value": "Product"
11          },
12          {
13            "col": "1",
14            "row": "0",
15            "value": "Price"
16          }
17        ],
18        [
19          {
20            "col": "0",
21            "row": "1",
22            "value": "Widget A"
23          },
24          {
25            "col": "1",
26            "row": "1",
27            "value": "$10.00"
28          }
29        ]
30      ]
31    }
32  ],
33  "file_status": "{\"success_files\":[\"image1.png\",\"image2.pdf\"],\"failed_files\":[]}"
34}

Read simplified mode

Read simplified mode returns a clean JSON with just the table rows/columns (no extra metadata). This is handy if you want the data in a very simple format (e.g. to insert into another database or tool). The request is almost the same, just with mode=read_simplified.

Example cURL request:

1curl --location --request POST 'https://api.rows.com/v1/vision/import' \
2--header 'Authorization: Bearer {YOUR API TOKEN}' \
3--header 'Accept: application/json' \
4--form 'folder_id="7cbc1000-8141-11ed-a1eb-0242ac120002"' \
5--form 'mode="read_simplified"' \
6--form 'instructions="Extract table data from images"' \
7--form 'files=@"path/to/image1.png"' \
8--form 'files=@"path/to/image2.pdf"'

Example response (JSON):

1{
2  "tables": [
3    {
4      "name": "Sheet 1",
5      "items": [
6        [
7          "Product",
8          "Price"
9        ],
10        [
11          "Widget A",
12          "$10.00"
13        ],
14        [
15          "Widget B",
16          "$15.00"
17        ]
18      ]
19    }
20  ],
21  "file_status": "{\"success_files\":[\"image1.png\",\"image2.pdf\"],\"failed_files\":[]}"
22}

Create mode

Create mode builds a new Rows spreadsheet for you. All tables extracted from the files are inserted into that sheet. You must include a folder_id (the destination folder in your workspace). The response will include the new spreadsheet’s details.

Example cURL request:

1curl --location --request POST 'https://api.rows.com/v1/vision/import' \
2--header 'Authorization: Bearer {YOUR API TOKEN}' \
3--header 'Accept: application/json' \
4--form 'folder_id="7cbc1000-8141-11ed-a1eb-0242ac120002"' \
5--form 'mode="create"' \
6--form 'instructions="Extract table data from images"' \
7--form 'merge="false"' \
8--form 'files=@"path/to/image1.png"' \
9--form 'files=@"path/to/image2.pdf"'

Example response (JSON):

1{
2  "spreadsheet_id": "5HGcWJFcQVVAv4mNTYb2RS",
3  "spreadsheet_url": "rows.com/workspace/folder/app-abc123",
4  "folder_id": "7cbc1000-8141-11ed-a1eb-0242ac120002",
5  "status": "success",
6  "tables": [
7    {
8      "table_id": "45d48dd6-c6fe-4674-a59a-60c0acc524ae"
9    },
10    {
11      "table_id": "78e23ff7-d7gf-5785-b60b-71d16b635e5f"
12    }
13  ],
14  "file_status": "{\"success_files\":[\"image1.png\",\"image2.pdf\"],\"failed_files\":[]}"
15}

What can I use it for?

Rows Vision API helps you turn unstructured files into ready-to-use data inside Rows. Here are some common examples:

• Financial documents: Extract transaction tables, invoice details, or expense summaries from PDFs or scanned receipts.
• Reports and statements: Convert tables from PDF exports (e.g. quarterly sales reports, performance summaries) into live spreadsheet data.
• Forms and surveys: Capture structured responses from paper or image forms to analyze or combine with other datasets.
• Inventory or logistics sheets: Digitize printed stock lists or shipment manifests into Rows for real-time tracking.
• Research or audit support: Quickly extract data from large document sets — like balance sheets or audit reports — to standardize and compare across files.

You can use these workflows as-is or combine them with automations and integrations (like email or storage apps) to update your Rows spreadsheet automatically.

Tips and best practices

• Supported file types: Vision API works on PDFs and images (JPG, PNG, WebP). (Rows also supports CSV/XLS imports, but those don’t require Vision AI.)
• File size: Each file can be up to 20 MB. For larger documents, split them into smaller files.
• Multiple files: In Create mode you can upload multiple images/PDFs in one request. This batches work and can generate one spreadsheet with multiple tables.
• Guiding the AI: You can include an instructions prompt to focus the extraction (for example, “only extract the invoice line items” or “include dates and totals only”). If you leave instructions blank, Rows will try to extract all visible tables and data.
• Permissions: Ensure your API key’s user has the right access. For read modes, “Live” (view) access to the target folder/spreadsheet is sufficient. For create mode, you need Editor access to the destination folder.
• Quality: Clear, high-contrast scans work best. Handwritten or very low-resolution images may yield worse accuracy.
• Validation: Always check the returned table(s) for accuracy, especially with complex layouts. You can use the simplified mode for an easy review.

How do I start?

1. Get an API key: In your Rows workspace, go to Settings > Rows API and generate a new key. (Keep it secret!)
2. Choose a folder: Decide where new spreadsheets should go. Use the List folders API endpoint to find your folder_id
3. Make a request: Use curl (or your HTTP tool) with your API key.
4. Check the result: The API will return JSON or create a new sheet (with its URL). You can open that sheet in Rows (switch to Edit mode) to see and use the table.

Usage and billing

Each time you use the Vision API, Rows will count:

• 1 AI Task — for the document or image analyzed by the Vision model.
• 1 API Call — for the HTTP request made to the Vision endpoint.

If you upload multiple files in a single request, each file counts as one AI Task, but the whole batch still counts as one API Call.

For example:

• Uploading one PDF → 1 AI Task + 1 API Call
• Uploading three files in one request → 3 AI Tasks + 1 API Call

These usage units appear in your workspace’s billing and usage dashboards, under AI Analyst✨ and Rows API, respectively.