GL importer

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. 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

export IMPORTER_API_TOKEN="your_token_here"
export BASE="https://importer.synder.com/api/v1"

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

Data Privacy

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

curl "$BASE/companies" -H "Authorization: Bearer $IMPORTER_API_TOKEN"

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, CreditMemo

curl "$BASE/companies/$CID/entities/$ENTITY/fields" -H "Authorization: Bearer $IMPORTER_API_TOKEN"

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:

curl -X POST "$BASE/companies/$CID/imports/auto" \
  -H "Authorization: Bearer $IMPORTER_API_TOKEN" \
  -F "file=@data.csv" \
  -F "entityName=Invoice" \
  -F "dryRun=true"

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:

curl -X POST "$BASE/companies/$CID/mappings" \
  -H "Authorization: Bearer $IMPORTER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Invoice Mapping",
    "entityName": "Invoice",
    "fields": [
      {"sourceFieldTitle": "Invoice #", "targetFieldId": "231"},
      {"sourceFieldTitle": "Customer",  "targetFieldId": "176"},
      {"sourceFieldTitle": null, "targetFieldId": "234", "fixedValue": "Imported via API"}
    ]
  }'

4. Upload and Execute Import

curl -X POST "$BASE/companies/$CID/imports" \
  -H "Authorization: Bearer $IMPORTER_API_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@data.csv" \
  -F "mappingId=$MAPPING_ID"

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

5. Poll for Completion

curl "$BASE/companies/$CID/imports/$IMPORT_ID" -H "Authorization: Bearer $IMPORTER_API_TOKEN"

Terminal statuses: FINISHED, FINISHED_WITH_WARNINGS, FAILED, CANCELED.

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

6. Check Results

# All results
curl "$BASE/companies/$CID/imports/$IMPORT_ID/results" -H "Authorization: Bearer $IMPORTER_API_TOKEN"
Errors only
curl "$BASE/companies/$CID/imports/$IMPORT_ID/results?type=ERROR" -H "Authorization: Bearer $IMPORTER_API_TOKEN"

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

File Requirements

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

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

Tips

Full API Details

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

Getting an API Token

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

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

export IMPORTER_API_TOKEN="your_token_here"
export BASE="https://importer.synder.com/api/v1"

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