Mindee Getting Started: API Integration Guide (2026)

Getting started overview

Integrating with Mindee involves a sequence of steps designed to enable rapid development and deployment of document processing capabilities. This guide outlines the essential procedures for setting up your environment, obtaining credentials, and executing a foundational API request. The process typically begins with account creation, followed by API key generation, and culminates in sending your first document for processing using either direct HTTP requests or one of Mindee's client SDKs. Mindee provides a developer documentation portal that offers comprehensive resources for all supported APIs and SDKs.

The following table summarizes the initial steps:

Create an account and get keys

To access Mindee's document processing services, you must first create a developer account. This account serves as your primary interface for managing API keys, monitoring usage, and accessing documentation. Upon successful registration, Mindee automatically provisions a unique API key for your account. This key is crucial for authenticating all requests sent to Mindee's APIs.

1. Register for a Mindee Account: Navigate to the Mindee sign-up page. Provide the required information, such as your email address and a password, to create your account. Mindee offers a free tier that allows processing up to 50 documents per month, which is sufficient for initial testing and development.
2. Locate Your API Key: After logging into your newly created account, access your Mindee dashboard. Your API key will be prominently displayed in the 'API Keys' section. This key is a unique alphanumeric string that acts as your credential for API access. Treat your API key as sensitive information and store it securely, avoiding hardcoding it directly into client-side code or public repositories.
3. Understand API Key Usage: The API key must be included in the header of every request you send to Mindee's endpoints. Specifically, it should be passed as an Authorization header with the format Token YOUR_API_KEY, or as an X-Api-Key header, depending on the specific API endpoint or SDK implementation. Refer to the Mindee API reference documentation for exact header requirements for each service.

Mindee's API keys function as bearer tokens, a common authentication mechanism for RESTful APIs, as defined in RFC 6750 for OAuth 2.0 Bearer Token Usage. This method simplifies authentication by requiring only the token for authorization.

Your first request

After obtaining your API key, you can make your first request to a Mindee API. This example demonstrates using the Mindee Python SDK to process a receipt. Similar examples are available for other supported SDKs like Node.js, Java, and .NET, or via direct HTTP requests.

Prerequisites

• Python 3.7+ installed.
• Mindee Python SDK installed: pip install mindee
• A sample receipt image file (e.g., receipt.jpg).

Python SDK Example: Processing a Receipt

import os
from mindee import Client, product

# Initialize a Mindee client
# Replace "YOUR_API_KEY" with your actual Mindee API key
mindee_client = Client(api_key="YOUR_API_KEY")

# Load the document from a local file
# Ensure 'receipt.jpg' is in the same directory or provide the full path
input_doc = mindee_client.doc_from_path("receipt.jpg")

# Send the document to the Receipt API
# The 'parse' method automatically handles sending and parsing
result = mindee_client.parse(product.ReceiptV5, input_doc)

# Print a summary of the extracted data
print(result.document.inference.prediction)

# Access specific fields, for example:
# print(f"Total amount: {result.document.inference.prediction.total_amount.value}")
# print(f"Date: {result.document.inference.prediction.date.value}")

Direct HTTP Request Example (using curl)

If you prefer to interact directly with the API without an SDK, you can use curl. This example targets the Receipts API.

Prerequisites

• curl installed (commonly pre-installed on Linux/macOS).
• A sample receipt image file (e.g., receipt.jpg).

curl -X POST "https://api.mindee.net/v1/products/mindee/receipts/v5/predict"
  -H "Authorization: Token YOUR_API_KEY"
  -H "Content-Type: multipart/form-data"
  -F "[email protected]"

Replace YOUR_API_KEY with your actual Mindee API key and ensure receipt.jpg points to your sample file. The response will be a JSON object containing the extracted data from the receipt.

Common next steps

Once you've successfully made your first request, several common next steps can enhance your integration and leverage Mindee's full capabilities:

• Explore Other APIs: Mindee offers a range of specialized APIs for different document types, including Invoices API, Passports API, and ID Cards API. Each API is optimized for its specific document type, providing accurate field extraction.
• Implement Error Handling: Integrate robust error handling into your application. Mindee's APIs return standard HTTP status codes (e.g., 400 for bad request, 401 for unauthorized, 500 for server errors) and detailed JSON error messages. Refer to the API reference documentation for a comprehensive list of error codes and their meanings.
• Utilize Webhooks: For asynchronous processing or to receive notifications when document processing is complete, consider setting up Mindee webhooks. Webhooks allow Mindee to send real-time updates to your application, reducing the need for polling and improving efficiency. This is particularly useful for larger documents or high-volume processing.
• Build Custom Documents: If your use case involves unique document types not covered by Mindee's out-of-the-box APIs, you can use the Custom Document API. This feature allows you to train Mindee's engine to extract specific fields from your proprietary documents, providing flexibility for specialized applications.
• Monitor Usage: Regularly check your Mindee dashboard to monitor API usage and ensure you stay within your plan's limits. This helps manage costs and predict scaling needs.
• Explore Advanced Features: Investigate features like document orientation correction, image quality assessment, and multi-page document processing to further optimize your integration.

Troubleshooting the first call

Encountering issues during your initial API call is common. Here are some troubleshooting steps and common problems:

• Invalid API Key (HTTP 401 Unauthorized):
  • Problem: The most frequent issue is an incorrect or missing API key.
  • Solution: Double-check that your API key is correctly copied from your Mindee dashboard and included in the Authorization: Token YOUR_API_KEY header (or X-Api-Key if specified by the endpoint). Ensure there are no leading or trailing spaces.
• Bad Request (HTTP 400 Bad Request):
  • Problem: This typically indicates an issue with the request payload, such as an incorrect file format, a missing required parameter, or an invalid content type.
  • Solution: Verify that the document you are sending is a supported file type (e.g., JPG, PNG, PDF) and that the Content-Type header is set correctly (e.g., multipart/form-data for file uploads). Review the specific API's documentation for expected parameters and formats.
• File Not Found (SDK-specific error or HTTP 400):
  • Problem: The SDK or API cannot locate the document file you are trying to send.
  • Solution: Ensure the file path provided in your code is correct and that the file exists at that location. For curl, verify the @filename.jpg path.
• Network Issues:
  • Problem: Connectivity problems can prevent your request from reaching Mindee's servers.
  • Solution: Check your internet connection. If you are behind a firewall or proxy, ensure that outbound connections to api.mindee.net are permitted.
• SDK Installation Problems:
  • Problem: The Mindee SDK might not be correctly installed or its dependencies are missing.
  • Solution: Re-run the installation command (e.g., pip install mindee) and check for any error messages. Ensure your Python environment is correctly configured.
• Exceeding Free Tier Limits:
  • Problem: If you've used more than 50 documents in your monthly free tier, subsequent requests will fail.
  • Solution: Check your usage in the Mindee dashboard. You may need to upgrade your plan for continued use.

For persistent issues, consult the Mindee troubleshooting guide or contact Mindee support with your request ID and any error messages received.