API Documentation

Simple, predictable endpoints for parsing receipts into clean, typed JSON. Start parsing in minutes.

Quick Start

Get started with Parsetto in seconds. Choose your preferred method:

JavaScript/Node.js

const formData = new FormData();
formData.append('file', fileInput.files[0]);

const response = await fetch('https://api.parsetto.com/v1/parse', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk-your-api-key'
  },
  body: formData
});

const result = await response.json();
console.log(result.data.vendor); // "Starbucks"
console.log(result.data.total);  // 12.45

cURL

curl -X POST https://api.parsetto.com/v1/parse \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: multipart/form-data" \
  -F "[email protected]"

Authentication

Include your API key in the Authorization header:

CURLExample Request

curl -X POST https://api.parsetto.com/v1/parse \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: multipart/form-data" \
  -F "[email protected]"

Parse Receipt

POST/v1/parse

Upload an image or PDF receipt to extract structured data.

cURL Example

curl -X POST https://api.parsetto.com/v1/parse \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: multipart/form-data" \
  -F "[email protected]" \
  -F "format=json"

Request Parameters

JSONMultipart Form Data

{
  "file": "<binary data>",
  "format": "json"
}

Success Response

JSON200 OK

{
  "id": "parse_1234567890",
  "status": "completed",
  "data": {
    "vendor": "Starbucks",
    "total": 12.45,
    "subtotal": 11.50,
    "tax": 0.95,
    "date": "2025-08-02",
    "time": "14:30:00",
    "items": [
      {
        "name": "Grande Latte",
        "quantity": 1,
        "price": 5.75
      },
      {
        "name": "Blueberry Muffin",
        "quantity": 1,
        "price": 5.75
      }
    ],
    "payment_method": "credit_card",
    "currency": "USD"
  },
  "confidence": 0.95,
  "processing_time_ms": 1250
}

Error Handling

All API errors return a consistent JSON format with helpful error messages and codes.

400

Bad Request

Invalid file format, missing required fields, or malformed request data.

{
  "error": {
    "code": "invalid_file_format",
    "message": "File must be JPEG, PNG, or PDF",
    "details": {
      "received_format": "text/plain",
      "supported_formats": ["image/jpeg", "image/png", "application/pdf"]
    }
  }
}

401

Unauthorized

Invalid, expired, or missing API key in the Authorization header.

{
  "error": {
    "code": "invalid_api_key",
    "message": "API key is invalid or has been revoked",
    "details": {
      "hint": "Check your API key at https://app.parsetto.com/settings"
    }
  }
}

413

File Too Large

Uploaded file exceeds the maximum allowed size limit.

{
  "error": {
    "code": "file_too_large",
    "message": "File size exceeds 10MB limit",
    "details": {
      "max_size_mb": 10,
      "received_size_mb": 15.2
    }
  }
}

429

Rate Limit Exceeded

Too many requests in a given time period. Check rate limit headers.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Monthly request limit reached",
    "details": {
      "limit": 100,
      "reset_date": "2025-09-01T00:00:00Z",
      "upgrade_url": "https://app.parsetto.com/billing"
    }
  }
}

500

Internal Server Error

Something went wrong on our end. These are rare and automatically reported.

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred while processing your request",
    "details": {
      "request_id": "req_1234567890",
      "support_email": "[email protected]"
    }
  }
}

Rate Limits

Rate limits are enforced per API key on a monthly basis:

Free

100

requests/month

Pro

5,000

requests/month

Enterprise

Custom

unlimited available

Response Schema

All successful responses follow a consistent schema with typed fields for reliable parsing:

JSONComplete Response Schema

{
  "id": "string",              // Unique parsing job ID
  "status": "completed",       // Job status: "completed" | "failed" | "processing"
  "confidence": 0.95,          // AI confidence score (0-1)
  "processing_time_ms": 1250,  // Time taken to process
  "data": {
    // Merchant Information
    "vendor": "string",        // Business name
    "vendor_address": "string", // Optional business address
    "vendor_phone": "string",   // Optional phone number
    
    // Financial Details
    "total": 12.45,            // Final amount (number)
    "subtotal": 11.50,         // Pre-tax amount (number)
    "tax": 0.95,              // Tax amount (number)
    "tip": 0.00,              // Tip amount (number)
    "currency": "USD",         // Currency code (ISO 4217)
    
    // Date & Time
    "date": "2025-08-02",      // Transaction date (YYYY-MM-DD)
    "time": "14:30:00",        // Transaction time (HH:MM:SS)
    
    // Line Items
    "items": [
      {
        "name": "string",      // Item description
        "quantity": 1,         // Quantity (number)
        "price": 5.75,         // Unit price (number)
        "total": 5.75          // Line total (number)
      }
    ],
    
    // Payment Details
    "payment_method": "credit_card", // "cash" | "credit_card" | "debit_card" | "other"
    "card_last_four": "4242",       // Optional last 4 digits
    
    // Receipt Metadata
    "receipt_number": "string",     // Optional receipt/transaction ID
    "cashier": "string"            // Optional cashier name
  }
}