Synder Importer API

Import CSV/XLSX files into QuickBooks Online or Xero.

Setup

Getting an API Token

If the user doesn't have a token yet, guide them through these steps:

1. 1. Create an account at importer.synder.com and confirm your email
2. Connect your accounting software — in the web UI, link QuickBooks Online or Xero via OAuth
3. Generate an API key — go to Account → API Keys, click Generate. Copy the token immediately — it's shown only once

CODEBLOCK0

Trial users: Imports are limited by row count without a paid subscription. No subscription is required to use the API itself.

Data Privacy

• - Homepage: importer.synder.com | Docs: importer.synder.com/apidocs
• Operator: Synder Technologies Inc. — synder.com
• What's sent: CSV/XLSX files containing accounting data (invoices, bills, journal entries, etc.) are uploaded to importer.synder.com and forwarded to your connected accounting provider (QuickBooks Online or Xero)
• Retention: Uploaded files are stored for import processing only and are not retained after import completion. Import logs (row counts, status, error messages) are retained for your account history.
• Scope: API tokens are scoped to a single user account and its connected companies. Tokens can be revoked at any time from the web UI.
• Recommendation: Always use dryRun=true first to preview before importing live data. Use non-production data for initial testing.

Quick Reference

Action	Method	Endpoint
Account info	GET	/account
List companies

GET | /companies | | Company settings | GET/POST | /companies/{id}/settings | | List entities | GET | /companies/{id}/entities | | Entity fields | GET | /companies/{id}/entities/{name}/fields | | Create mapping | POST | /companies/{id}/mappings | | List mappings | GET | /companies/{id}/mappings | | Update mapping | PUT | /companies/{id}/mappings/{mid} | | Delete mapping | DELETE | /companies/{id}/mappings/{mid} | | Execute import | POST | /companies/{id}/imports | | Auto-import | POST | /companies/{id}/imports/auto | | List imports | GET | /companies/{id}/imports | | Import status | GET | /companies/{id}/imports/{iid} | | Cancel import | POST | /companies/{id}/imports/{iid}/cancel | | Revert import | POST | /companies/{id}/imports/{iid}/revert | | Import results | GET | /companies/{id}/imports/{iid}/results |

Core Workflow

1. Find the company

CODEBLOCK1

Response is an array. Pick the company with status: "ACTIVE". Save its id.

2. Choose entity and check fields

Common entities: Invoice, Bill, JournalEntry, Customer, Vendor, Expense, SalesReceipt, Payment, INLINECODE11

CODEBLOCK2

Fields with isRequired: true MUST be mapped. Fields with isForGrouping: true (e.g., DocNumber) combine multiple CSV rows into one entity (multi-line invoices).

Important: Check GET /companies/{id}/settings for dateFormat (e.g., MM/dd/yyyy). CSV date columns must match this format or the import will fail. Update with POST /companies/{id}/settings if needed.

3. Option A: Smart Auto-Import (recommended)

Skip manual mapping — auto-match CSV headers to fields:

CODEBLOCK3

• - dryRun=true (default): Returns proposed mapping without importing. Check missingRequired array — if empty, safe to import. Response: proposedFields, missingRequired, totalFieldsMapped.
• INLINECODE23: Maps AND imports in one call. Returns {"id": "42", "status": "SCHEDULED", "mappingId": "33", ...} — use the id to poll for completion (same as step 5).

Confidence levels in proposedFields: high = exact title match, medium = matched via alternative title. Review medium matches before importing with dryRun=false.

3. Option B: Manual Mapping

Create a mapping linking CSV columns to entity fields:

CODEBLOCK4

• - sourceFieldTitle: CSV column header name
• INLINECODE32: from the fields endpoint
• INLINECODE33: constant value for every row (set sourceFieldTitle to null)

4. Upload and Execute Import

CODEBLOCK5

Returns 202 with status: "SCHEDULED". Always send Idempotency-Key to prevent duplicate imports on retry.

5. Poll for Completion

CODEBLOCK6

Terminal statuses: FINISHED, FINISHED_WITH_WARNINGS, FAILED, CANCELED.

Poll with exponential backoff: start 2s, multiply 1.5x, cap 30s.

6. Check Results

CODEBLOCK7

Result types: INFO (success), WARNING, ERROR.

File Requirements

• - CSV: UTF-8, comma-delimited, header row required, max 50MB
• XLSX: First sheet by default (use sheetName param for others), header row required, max 50MB

Error Handling

All errors return {"error": {"code": "...", "message": "..."}}.

Code	HTTP	Action
UNAUTHORIZED	401	Check/refresh API token
NOT_FOUND

404 | Verify company/mapping/import/entity ID |
| BAD_REQUEST | 400 | Check request format, file validity, provider connection |
| VALIDATION_ERROR | 422 | Map all required fields — call GET .../fields to see which |
| DUPLICATE_REQUEST | 409 | Same Idempotency-Key reused within 24h — use new UUID |
| CONFLICT | 409 | Import not in valid state for cancel/revert |
| RATE_LIMITED | 429 | Wait Retry-After header seconds, then retry |

Rate Limits

• - Standard: 60 requests/minute per account
• Imports: 30 imports/hour per company

Check X-RateLimit-Remaining header. On 429, wait Retry-After seconds.

Tips

• - Use dryRun=true on auto-import before committing — all operations hit live accounting data
• Revert mistakes with POST .../imports/{id}/revert (deletes created entities from QBO/Xero)
• INLINECODE51 on fields show what CSV headers auto-mapping recognizes
• For multi-line entities (invoices with line items), use a grouping field (DocNumber) — rows with same value become one entity
• Paginated endpoints accept page and perPage (max 100, default 20)

Full API Details

For complete field schemas, response examples, and OpenAPI spec: see references/api.md