Getting started with Parsie API

Parsie is an Intelligent Document Processing platform that automates the extraction and processing of data from your documents. Use the endpoints below to create tables, upload files to them, manage your table schemas, and retrieve data.

Getting started

Sign up for an account on the Parsie website.
Obtain your API key from the Parsie dashboard.

Authentication

All API requests require an API key. Include your API key in the x-api-key header:

x-api-key: YOUR_API_KEY

API Endpoints

Note: For detailed information about table schema structure and limitations, see the Table Schema Structure section at the end of this document.

Base URL

https://parsie.pro

1. List Tables

Endpoint:
GET {{baseUrl}}/api/tables

Description:
Retrieves a list of all tables associated with your account.

Headers:

x-api-key: YOUR_API_KEY

Response:

[
  {
    "id": "931637d2-ca0a-47be-aae3-aafd262cdaf0",
    "name": "Invoice Table",
    "description": "Table for storing invoice data"
  }
]

2. Create Table

Endpoint:
POST {{baseUrl}}/api/tables

Description:
Creates a new table with a defined schema for storing extracted data.

Schema Details: The definition field must follow our schema structure with specific limitations.

Headers:

x-api-key: YOUR_API_KEY

Request Body:

{
  "name": "Invoice Table",
  "description": "Table for storing invoice data",
  "definition": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
      "name": "Invoice Table",
      "description": "Table for storing invoice data",
      "columns": [
        {
          "id": "invoice_number",
          "title": "Invoice Number",
          "type": "string",
          "description": "Unique identifier for the invoice",
          "examples": "INV-100",
          "isList": false,
          "properties": []
        }
      ]
    },
    "required": ["name", "description", "columns"],
    "additionalProperties": false
  }
}

Response:

{
  "id": "931637d2-ca0a-47be-aae3-aafd262cdaf0",
  "name": "Invoice Table",
  "description": "Table for storing invoice data",
  "definition": { ... }
}

3. Delete Table

Endpoint:
DELETE {{baseUrl}}/api/tables

Description:
Deletes an existing table by providing its unique ID.

Headers:

x-api-key: YOUR_API_KEY

Request Body:

{
  "id": "284bd9dd-0c10-4e67-aab7-bf9f1af3e5c1"
}

Response:

{
  "message": "Table with id 284bd9dd-0c10-4e67-aab7-bf9f1af3e5c1 has been deleted"
}

4. Get Table Schema

Endpoint:
GET {{baseUrl}}/api/tables/{tableId}/schema

Description:
Retrieves the schema definition for a specified table. Replace {tableId} with the table's ID.

Headers:

x-api-key: YOUR_API_KEY

Response:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": "Invoice Table",
    "description": "Table for storing invoice data",
    "columns": [
      {
        "id": "invoice_number",
        "title": "Invoice Number",
        "type": "string",
        "description": "Unique identifier for the invoice",
        "examples": "INV-100",
        "isList": false,
        "properties": []
      }
    ]
  },
  "required": ["name", "description", "columns"],
  "additionalProperties": false
}

5. Update Table Schema

Endpoint:
PUT {{baseUrl}}/api/tables/{tableId}/schema

Description:
Updates the schema definition for a specified table. Replace {tableId} with the table's ID.

Schema Details: The definition field must follow our schema structure with specific limitations.

Headers:

x-api-key: YOUR_API_KEY

Request Body:

{
  "definition": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
      "name": "Invoice Table",
      "description": "Table for storing invoice data",
      "columns": [
        {
          "id": "invoice_number",
          "title": "Invoice Number",
          "type": "string",
          "description": "Unique identifier for the invoice",
          "examples": "INV-100",
          "isList": false,
          "properties": []
        }
      ]
    },
    "required": ["name", "description", "columns"],
    "additionalProperties": false
  }
}

Response:

{
  "success": true
}

6. Upload File to Table (Deprecated)

⚠️ Deprecated: This synchronous file upload endpoint is deprecated. Use the asynchronous extraction endpoints (see 9. Submit Extraction Job and 10. Poll Extraction Job Status) instead.

Endpoint:
POST {{baseUrl}}/api/tables/{tableId}/upload

7. Upload Base64 File to Table (Deprecated)

⚠️ Deprecated: This synchronous base64 upload endpoint is deprecated. Use the asynchronous extraction endpoints (see 9. Submit Extraction Job and 10. Poll Extraction Job Status) instead.

Endpoint:
POST {{baseUrl}}/api/tables/{tableId}/upload-base64

8. Get Table Data by Row IDs

Endpoint:
POST {{baseUrl}}/api/tables/{tableId}/data

Description:
Retrieves data for specific rows from a table.

Headers:

x-api-key: YOUR_API_KEY

Request Body:

{
  "rowIds": ["929e7f55-f210-4639-b300-0179ad5820bd"]
}

Example (curl):

curl -X POST "{{baseUrl}}/api/tables/{tableId}/data" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "rowIds": ["929e7f55-f210-4639-b300-0179ad5820bd"]
}'

Response (200):

[
  {
    "id": "929e7f55-f210-4639-b300-0179ad5820bd",
    "invoice_number": "INV-100",
    "invoice_date": "2023-01-15",
    // ... additional fields ...
  }
]

9. Submit Extraction Job

Endpoint: POST {{baseUrl}}/api/tables/{tableId}/extract-data

Description: Submits a document file (base64-encoded) for processing. Returns a job ID for polling.

Headers:

x-api-key: YOUR_API_KEY
Content-Type: application/json

Request Body:

{
  "fileName": "sample.pdf",
  "base64String": "JVBERi0xLjcNJeLjz9MNCjI1NCAwIG9...",
  "fileSize": 123456,           // optional, size of file in bytes
}

Response (202 Accepted):
Headers:

Location: /api/jobs/{jobId}
Retry-After: 2

Body:

{
  "message": "Extraction job submitted successfully",
  "jobId": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
  "retryAfter": 2
}

Example (curl):

curl -X POST "{{baseUrl}}/api/tables/{tableId}/extract-data" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "fileName": "sample.pdf",
  "base64String": "JVBERi0xLjcNJeLjz9MNCjI1NCAwIG9..."
}'

10. Poll Extraction Job Status

Endpoint: GET {{baseUrl}}/api/jobs/{jobId}

Description: Retrieves the status of an extraction job and, if completed, the result.

Headers:

x-api-key: YOUR_API_KEY

Responses:

Pending or Processing
Headers:

Retry-After: 2

Body:

{
  "status": "pending" {/* or "running" */}
}

Completed
Body:

{
  "status": "completed",
  "resultUrl": "https://storage.example.com/...",
  "result": { 
    "id": "535d2c2a-78a9-41ea-9f88-fdaad413baf0",
    { /* Data for the row here */ }
   }
}

Failed
Body:

{
  "status": "failed",
  "error": "Error message"
}

Example (curl):

curl -X GET "{{baseUrl}}/api/jobs/{jobId}" \
  -H "x-api-key: YOUR_API_KEY"

Error Handling

Errors are returned in the following format:

{
  "error": "Error message description"
}

Common error status codes:

400 - Bad Request (invalid input)
401 - Unauthorized (invalid or missing API key)
404 - Not Found (resource doesn't exist)
500 - Internal Server Error

Rate Limits

The API enforces rate limits based on your user plan:

Beta Plan: 5 requests per second

Exceeding the limit returns a 429 Too Many Requests response.

Table Schema Structure

When creating or updating tables, you need to define a schema that specifies the structure of your data. Our schema follows the JSON Schema Draft-07 format with specific limitations:

Schema Structure

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the table."
    },
    "description": {
      "type": "string",
      "description": "A description of the table."
    },
    "columns": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "A unique identifier for the column."
          },
          "title": {
            "type": "string",
            "description": "The display name of the column."
          },
          "type": {
            "type": "string",
            "enum": ["string", "number", "boolean", "object"],
            "description": "The data type of the column."
          },
          "description": {
            "type": "string",
            "description": "A brief description of the column."
          },
          "examples": {
            "type": "string",
            "description": "Example values for the column."
          },
          "isList": {
            "type": "boolean",
            "description": "Indicates if the column is a list (array)."
          },
          "properties": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "A unique identifier for the sub-property."
                },
                "title": {
                  "type": "string",
                  "description": "The display name of the sub-property."
                },
                "type": {
                  "type": "string",
                  "enum": ["string", "number", "boolean"],
                  "description": "The data type of the sub-property."
                },
                "description": {
                  "type": "string",
                  "description": "A brief description of the sub-property."
                },
                "examples": {
                  "type": "string",
                  "description": "Example values for the sub-property."
                }
              },
              "required": ["id", "title", "type", "description", "examples"],
              "additionalProperties": false
            },
            "description": "List of sub-properties if the column type is 'object'."
          }
        },
        "required": ["id", "title", "type", "description", "examples", "isList", "properties"],
        "additionalProperties": false
      },
      "description": "An array of column definitions."
    }
  },
  "required": ["name", "description", "columns"],
  "additionalProperties": false
}

Schema Limitations

Based on our schema structure, please note the following limitations:

Column Types: We support the following column types:
- string: Text data
- number: Numeric data
- boolean: True/false values
- object: Structured data with sub-properties
Object Columns: For columns of type object:
- ✅ Can contain sub-properties of type string, number, or boolean
- ❌ Cannot contain nested objects (sub-properties cannot be of type object)
- ❌ Cannot contain arrays of objects
Array Support: For any column type:
- ✅ Can be marked as a list using the isList property
- ✅ Lists can contain primitive values (string, number, boolean)
- ✅ Lists can contain objects (but those objects can only have primitive properties or arrays of primitives)
- ❌ Lists cannot contain nested arrays of objects

Example Schema

Here's a practical example of a valid schema for an invoice table:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": "Invoice Table",
    "description": "Table for storing invoice data",
    "columns": [
      {
        "id": "invoice_number",
        "title": "Invoice Number",
        "type": "string",
        "description": "Unique identifier for the invoice",
        "examples": "INV-100",
        "isList": false,
        "properties": []
      },
      {
        "id": "invoice_date",
        "title": "Invoice Date",
        "type": "string",
        "description": "The date the invoice was issued",
        "examples": "2023-01-15",
        "isList": false,
        "properties": []
      },
      {
        "id": "customer",
        "title": "Customer Information",
        "type": "object",
        "description": "Customer details",
        "examples": "",
        "isList": false,
        "properties": [
          {
            "id": "name",
            "title": "Customer Name",
            "type": "string",
            "description": "Full name of the customer",
            "examples": "John Doe"
          },
          {
            "id": "email",
            "title": "Email",
            "type": "string",
            "description": "Customer email address",
            "examples": "john@example.com"
          }
        ]
      },
      {
        "id": "items",
        "title": "Items",
        "type": "object",
        "description": "List of items in the invoice",
        "examples": "",
        "isList": true,
        "properties": [
          {
            "id": "name",
            "title": "Item Name",
            "type": "string",
            "description": "Name of the item",
            "examples": "Product A"
          },
          {
            "id": "price",
            "title": "Price",
            "type": "number",
            "description": "Price of the item",
            "examples": "29.99"
          },
          {
            "id": "tags",
            "title": "Tags",
            "type": "string",
            "description": "Tags associated with the item",
            "examples": "electronics, gadgets",
            "isList": true
          }
        ]
      }
    ]
  },
  "required": ["name", "description", "columns"],
  "additionalProperties": false
}

Getting started with Parsie API

Learn how to get started with Parsie API using our latest endpoints.

Getting started

Authentication

API Endpoints

Base URL

1. List Tables

2. Create Table

3. Delete Table

4. Get Table Schema

5. Update Table Schema

6. Upload File to Table (Deprecated)

7. Upload Base64 File to Table (Deprecated)

8. Get Table Data by Row IDs

9. Submit Extraction Job

10. Poll Extraction Job Status

Error Handling

Rate Limits

Table Schema Structure

Schema Structure

Schema Limitations

Example Schema