Overview The Imports API allows you to upload CSV files to import transactions, trades, accounts, categories, and other data into Sure. The import process involves uploading a file, configuring column mappings, and publishing the import.
Authentication
List/Show : Requires read or read_write scopeCreate : Requires read_write scope
Endpoints List All Imports Retrieve all imports for the family.
Query Parameters Filter by status: pending, complete, importing, reverting, revert_failed, or failed
Filter by type: TransactionImport, TradeImport, AccountImport, MintImport, CategoryImport, RuleImport, or PdfImport
Items per page (1-100, default: 25)
Response Returns a paginated list of imports ordered by most recent first.
{ "data" : [ { "id" : "1" , "type" : "TransactionImport" , "status" : "complete" , "created_at" : "2024-03-01T10:00:00Z" , "updated_at" : "2024-03-01T10:05:00Z" , "account_id" : "123" , "rows_count" : 45 , "error" : null }, { "id" : "2" , "type" : "TransactionImport" , "status" : "pending" , "created_at" : "2024-03-04T14:00:00Z" , "updated_at" : "2024-03-04T14:00:00Z" , "account_id" : "456" , "rows_count" : 120 , "error" : null } ], "meta" : { "current_page" : 1 , "next_page" : null , "prev_page" : null , "total_pages" : 1 , "total_count" : 2 , "per_page" : 25 } }
Example Request curl -X GET "https://your-domain.com/api/v1/imports?status=complete&page=1&per_page=25" \ -H "X-Api-Key: your_api_key_here"
Get a Specific Import Retrieve detailed information about an import.
The unique identifier of the import
Response { "data" : { "id" : "1" , "type" : "TransactionImport" , "status" : "complete" , "created_at" : "2024-03-01T10:00:00Z" , "updated_at" : "2024-03-01T10:05:00Z" , "account_id" : "123" , "error" : null , "configuration" : { "date_col_label" : "Date" , "amount_col_label" : "Amount" , "name_col_label" : "Description" , "category_col_label" : "Category" , "tags_col_label" : "Tags" , "notes_col_label" : "Notes" , "account_col_label" : null , "date_format" : "%Y-%m-%d" , "number_format" : "1,234.56" , "signage_convention" : "inflows_positive" }, "stats" : { "rows_count" : 45 , "valid_rows_count" : 45 } } }
Example Request curl -X GET https://your-domain.com/api/v1/imports/1 \ -H "X-Api-Key: your_api_key_here"
Create an Import Upload and create a new import.
Request Parameters Import type (default: TransactionImport). Options: TransactionImport, TradeImport, AccountImport, MintImport, CategoryImport, RuleImport, PdfImport
ID of the account to associate with this import
CSV file to upload (max 10MB for CSV, 25MB for PDF)
Alternatively, provide raw CSV content as a string
Set to "true" to automatically publish the import after configuration
Configuration Parameters (optional)Header name of the date column
Header name of the amount column
Header name of the description/name column
Header name of the category column
Header name of the tags column
Header name of the notes column
Header name of the account column
Header name of the quantity column (for trades)
Header name of the ticker symbol column (for trades)
Header name of the price column (for trades)
Header name of the currency column
Date format string (e.g., %Y-%m-%d, %m/%d/%Y)
Number format: 1,234.56 (US), 1.234,56 (EU), 1 234,56 (French), or 1,234 (JPY)
Sign convention: inflows_positive or inflows_negative
Column separator: , (comma) or ; (semicolon)
Strategy: signed_amount or custom_column
Value that identifies inflows when using custom_column strategy
Response Returns the created import with status 201 Created.
curl -X POST https://your-domain.com/api/v1/imports \ -H "X-Api-Key: your_api_key_here" \ -F "type=TransactionImport" \ -F "account_id=123" \ -F "[email protected] " \ -F "date_col_label=Date" \ -F "amount_col_label=Amount" \ -F "name_col_label=Description" \ -F "number_format=1,234.56" \ -F "signage_convention=inflows_positive"
JSON Request (with raw content)
{ "type" : "TransactionImport" , "account_id" : "123" , "raw_file_content" : "Date,Amount,Description \n 2024-01-01,100.00,Salary \n 2024-01-02,-50.00,Groceries" , "date_col_label" : "Date" , "amount_col_label" : "Amount" , "name_col_label" : "Description" , "number_format" : "1,234.56" , "signage_convention" : "inflows_positive" , "publish" : "true" }
{ "data" : { "id" : "3" , "type" : "TransactionImport" , "status" : "pending" , "created_at" : "2024-03-04T16:00:00Z" , "updated_at" : "2024-03-04T16:00:00Z" , "account_id" : "123" , "error" : null , "configuration" : { "date_col_label" : "Date" , "amount_col_label" : "Amount" , "name_col_label" : "Description" , "category_col_label" : null , "tags_col_label" : null , "notes_col_label" : null , "account_col_label" : null , "date_format" : null , "number_format" : "1,234.56" , "signage_convention" : "inflows_positive" }, "stats" : { "rows_count" : 2 , "valid_rows_count" : 2 } } }
Import Types Show Available Import Types
Import bank transactions from CSV
Import investment trades from CSV
Import account information
Import data from Mint.com exports
Import category definitions
Import categorization rules
Import PDF statements (requires AI features)
Import Statuses Import has been created but not yet published
Import is currently being processed
Import has been successfully completed
Import failed with an error
Import revert operation failed
Supported number format patterns:
1,234.56 - US/UK/Asia format (comma thousands separator, period decimal)1.234,56 - Most of Europe (period thousands separator, comma decimal)1 234,56 - French/Scandinavian (space thousands separator, comma decimal)1,234 - Zero-decimal currencies like JPY
Error Responses { "error" : "not_found" , "message" : "Import not found" }
{ "error" : "file_too_large" , "message" : "File is too large. Maximum size is 10MB." }
{ "error" : "invalid_file_type" , "message" : "Invalid file type. Please upload a CSV file." }
{ "error" : "validation_failed" , "message" : "Import could not be created" , "errors" : [ "Account must belong to your family" ] }
500 Internal Server Error
{ "error" : "internal_server_error" , "message" : "Error processing import" }
Important Notes File Size Limits :
CSV files: Maximum 10MB
PDF files: Maximum 25MB
Row Limits :
Maximum 10,000 rows per import
Accepted MIME Types for CSV : text/csv, text/plain, application/vnd.ms-excel, application/csvAccepted MIME Types for PDF : application/pdf
Auto-Publishing : Set publish=true to automatically process the import after upload. Otherwise, you’ll need to configure column mappings through the web interface before publishing.
Template Reuse : Sure automatically suggests configuration templates based on previous successful imports to the same account, making repeat imports faster.