Skip to main content

List Documents

This endpoint allows you to retrieve a list of documents in your account. You can use various query parameters to filter and paginate the results.

API Endpoint#

GET https://api.documentpro.ai/v1/documents

Query Parameters#

All parameters are optional:

  • limit (optional): Number of documents to return. Default is 100.
  • document_id (optional): Filter by a specific document ID.
  • created_at (optional): Filter by creation date.
  • search_term (optional): Search for documents by name or content.

Headers#

  • x-api-key (required): Your API key for authentication.

Example Implementation#

Using cURL#

curl --location 'https://api.documentpro.ai/v1/documents?limit=10' \--header 'x-api-key: YOUR_API_KEY' \--header 'Accept: application/json'

Using Python#

import requests
url = "https://api.documentpro.ai/v1/documents"headers = {    "x-api-key": "YOUR_API_KEY",    "Accept": "application/json"}params = {    "limit": 10,    # Add other optional parameters as needed}
response = requests.get(url, headers=headers, params=params)
if response.status_code == 200:    result = response.json()    print("Documents retrieved successfully:")    for doc in result['files']:        print(f"Document ID: {doc['document_id']}, Name: {doc['file_name']}")    if result['pagination_key']:        print("More documents available. Use pagination_key for next request.")else:    print("Failed to retrieve documents")    print(response.text)

Response#

The response will contain an array of document objects and a pagination key if there are more results.

Successful Response (Status Code: 200)#

{    "files": [        {            "document_id": "0b33c9f2-5148-4ffb-bb7b-de03bb071ca8",            "user_id": "24d9b25a-9bba-4de4-be67-c06233d2f305",            "source_name": "api",            "s3_key": "https://documentpro-user-accounts.s3.amazonaws.com/...",            "file_name": "file_name.pdf",            "file_extension": "pdf",            "num_pages": 1,            "meta_tags": {},            "parser_runs": [                {                    "template_id": "a62e2b5f-ccc2-4e2a-8fda-d7bd6579a692",                    "template_title": "Invoice",                    "request_id": "123e337c-0294-4cf8-b684-1310c8cd6a4e",                    "params": {                        "end_regex": null,                        "page_ranges": "5",                        "use_ocr": true,                        "detect_tables": true,                        "start_regex": null,                        "query_model": "gpt-4o-mini",                        "use_all_matches": false,                        "detect_layout": true,                        "split_regex": null                    },                    "datetime": "2024-07-25T10:01:06.536970"                },                // ... additional parser runs ...            ],            "created_at": "2024-07-25T14:16:44.540197",            "updated_at": "2024-07-25T14:16:44.540223"        },        {            "document_id": "8edd4104-cb56-42eb-b1f4-cbd6da0894ca",            "user_id": "2s49b2ca-9bba-4de4-be67-c06233d2f305",            "source_name": "web",            "s3_key": "https://documentpro-user-accounts.s3.amazonaws.com/...",            "file_name": "file_name.pdf",            "file_extension": "pdf",            "num_pages": 8,            "meta_tags": {},            "parser_runs": [],            "created_at": "2024-07-25T10:00:30.677936",            "updated_at": "2024-07-25T10:01:07.109837"        }    ],    "pagination_key": {        "document_id": "8ed94104-cb56-42eb-b1f4-cbd6da0894ca",        "created_at": "2024-07-25T10:00:30.677936"    }}

Error Response (Status Codes: 400, 401, 403, 500)#

{    "success": false,    "error": "error_code",    "message": "descriptive error message"}

Response Fields Explained#

  • files: An array of document objects, each containing:

    • document_id: Unique identifier for the document.
    • user_id: ID of the user who owns the document.
    • source_name: Source of the document upload (e.g., "api", "web").
    • s3_key: S3 URL for accessing the document.
    • file_name: Name of the document file.
    • file_extension: File extension (e.g., "pdf").
    • num_pages: Number of pages in the document.
    • meta_tags: Any metadata associated with the document.
    • parser_runs: Array of parsing operations performed on the document.
    • created_at: Timestamp of document creation.
    • updated_at: Timestamp of last update.

  • pagination_key: If present, contains document_id and created_at of the last document in the current set. Use these values to fetch the next set of results.

Pagination#

To retrieve the next set of results, include the pagination_key values in your next request:

GET https://api.documentpro.ai/v1/documents?document_id=8ed94104-cb56-42eb-b1f4-cbd6da0894ca&created_at=2024-07-25T10:00:30.677936

Important Notes#

  1. The default limit is 100 documents per request. Adjust using the limit parameter.
  2. The parser_runs array shows the history of parsing operations on each document.
  3. Use the pagination_key to fetch subsequent pages of results if available.
  4. The s3_key URLs are temporary and will expire after a certain period.

Next Steps#