API Reference

Complete reference for all SmartBills API endpoints.

Base URL

All API requests should be made to:

https://api.smartbills.com/v1

Authentication

All requests require authentication using an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Response Format

All responses are returned in JSON format with the following structure:

{
  "success": true,
  "data": { /* response data */ },
  "error": null
}

For errors:

{
  "success": false,
  "data": null,
  "error": {
    "code": "INVALID_FILE_FORMAT",
    "message": "The uploaded file format is not supported"
  }
}

Content Type

For file uploads, use multipart/form-data. For other requests, use application/json.

Rate Limiting

See Getting Started for current rate limits.

Invoices

Extract Invoice Data

POST/v1/invoices/extract

POST

Upload and extract data from an invoice file

Parameters

Parameter	Type	Required	Description
`file`	File	Yes	The invoice file (PDF, JPG, PNG)
`webhook_url`	String	No	URL to receive webhook notifications
`extract_line_items`	Boolean	No	Whether to extract individual line items (default: true)

::code-example{ curlExample="curl -X POST https://api.smartbills.com/v1/invoices/extract \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: multipart/form-data" \ -F "file=@invoice.pdf" \ -F "webhook_url=https://yourapp.com/webhooks/smartbills\" \ -F "extract_line_items=true""

javascriptExample="const formData = new FormData(); formData.append('file', fileInput.files0); formData.append('webhook_url', 'https://yourapp.com/webhooks/smartbills'); formData.append('extract_line_items', 'true');

const response = await fetch('https://api.smartbills.com/v1/invoices/extract', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY' }, body: formData });"

pythonExample="import requests

url = 'https://api.smartbills.com/v1/invoices/extract' files = {'file': open('invoice.pdf', 'rb')} data = { 'webhook_url': 'https://yourapp.com/webhooks/smartbills', 'extract_line_items': True } headers = {'Authorization': 'Bearer YOUR_API_KEY'}

response = requests.post(url, files=files, data=data, headers=headers)"

responseExample="{ "success": true, "data": { "id": "inv_123456789", "status": "processing", "created_at": "2024-01-15T10:30:00Z", "file_url": "https://files.smartbills.com/inv_123456789.pdf\", "estimated_completion": "2024-01-15T10:31:00Z" } }" } ::

Get Invoice

GET/v1/invoices/{id}

GET

Retrieve invoice extraction results

Path Parameters

Parameter	Type	Required	Description
`id`	String	Yes	The invoice ID

::code-example{ curlExample="curl -X GET https://api.smartbills.com/v1/invoices/inv_123456789 \ -H "Authorization: Bearer YOUR_API_KEY""

javascriptExample="const response = await fetch('https://api.smartbills.com/v1/invoices/inv_123456789', { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } });

const invoice = await response.json();"

pythonExample="import requests

url = 'https://api.smartbills.com/v1/invoices/inv_123456789' headers = {'Authorization': 'Bearer YOUR_API_KEY'}

response = requests.get(url, headers=headers) invoice = response.json()"

responseExample="{ "success": true, "data": { "id": "inv_123456789", "status": "completed", "created_at": "2024-01-15T10:30:00Z", "completed_at": "2024-01-15T10:30:45Z", "file_url": "https://files.smartbills.com/inv_123456789.pdf\", "extracted_data": { "invoice_number": "INV-2024-001", "date": "2024-01-15", "due_date": "2024-02-15", "total_amount": 1250.00, "currency": "USD", "vendor": { "name": "Acme Corp", "address": "123 Business St, City, State 12345", "tax_id": "12-3456789" }, "customer": { "name": "Your Company", "address": "456 Customer Ave, City, State 67890" }, "line_items": { "description": "Professional Services", "quantity": 10, "unit_price": 125.00, "total": 1250.00 } } } }" }

List Invoices

GET/v1/invoices

GET

List all invoices with optional filtering

Query Parameters

Parameter	Type	Required	Description
`limit`	Integer	No	Number of results to return (default: 20, max: 100)
`offset`	Integer	No	Number of results to skip
`status`	String	No	Filter by status: `processing`, `completed`, `failed`
`created_after`	String	No	ISO 8601 timestamp
`created_before`	String	No	ISO 8601 timestamp

::code-example{ curlExample="curl -X GET "https://api.smartbills.com/v1/invoices?limit=10&status=completed\" \ -H "Authorization: Bearer YOUR_API_KEY""

javascriptExample="const params = new URLSearchParams({ limit: '10', status: 'completed' });

const response = await fetch(https://api.smartbills.com/v1/invoices?${params}, { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } });"

pythonExample="import requests

url = 'https://api.smartbills.com/v1/invoices' params = {'limit': 10, 'status': 'completed'} headers = {'Authorization': 'Bearer YOUR_API_KEY'}

response = requests.get(url, params=params, headers=headers)"

responseExample="{ "success": true, "data": { "invoices": { "id": "inv_123456789", "status": "completed", "created_at": "2024-01-15T10:30:00Z", "total_amount": 1250.00, "currency": "USD" } , "pagination": { "total": 150, "limit": 10, "offset": 0, "has_more": true } } }" } ::

Status Codes

The SmartBills API returns standard HTTP status codes:

Code	Description
200	OK - Request succeeded
201	Created - Resource created successfully
400	Bad Request - Invalid request parameters
401	Unauthorized - Invalid API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource not found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Something went wrong on our end

Processing Status

Invoice processing goes through several statuses:

Status	Description
`processing`	File is being processed
`completed`	Extraction completed successfully
`failed`	Processing failed (see error details)

Supported File Formats

PDF: Single or multi-page documents
Images: JPG, JPEG, PNG, WEBP
Maximum file size: 10 MB
Maximum pages: 50 pages per PDF

File Format Tips

For best results:

Use high-resolution images (300 DPI or higher)
Ensure text is clearly readable
Avoid heavily compressed or blurry images

Next Steps

Webhooks - Set up real-time notifications
Error Codes - Handle errors gracefully
Examples - See practical implementations