home / skills / cleanexpo / ato / myob_api_integration

myob_api_integration skill

This skill enables read-only MYOB data extraction, normalising transactions, accounts, and reports for tax analysis and multi-year insights.

npx playbooks add skill cleanexpo/ato --skill myob_api_integration

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.1 KB

---
name: myob-api-integration
description: Read-only MYOB AccountRight and Essentials API access for historical transaction data extraction
---

# MYOB API Integration Skill

Provides read-only access to MYOB accounting data through the MYOB API. Extracts historical transactions, chart of accounts, contacts, and financial reports for tax analysis.

## When to Use

- Connecting a MYOB client for tax analysis (instead of Xero)
- Extracting historical transaction data from MYOB
- Fetching chart of accounts for GL mapping
- Pulling profit & loss and balance sheet reports
- Multi-year data sync for carry-forward analysis

## Integration Architecture

```
MYOB API → myob-adapter.ts → canonical-schema.ts → analysis engines
```

All MYOB data is normalised to the canonical schema (`lib/integrations/canonical-schema.ts`) before being consumed by analysis engines. This ensures all 16 engines work identically regardless of whether data comes from Xero, MYOB, or QuickBooks.

## Key Files

- **Adapter**: `lib/integrations/adapters/myob-adapter.ts` — MYOB API client
- **Historical Fetcher**: `lib/integrations/myob-historical-fetcher.ts` — Multi-year data sync
- **Canonical Schema**: `lib/integrations/canonical-schema.ts` — Normalised data model
- **Config**: `lib/integrations/myob-config.ts` — OAuth configuration
- **Auth Route**: `app/api/auth/myob/route.ts` — OAuth 2.0 callback

## Access Scopes

All access is **read-only**:
- General Ledger transactions
- Chart of accounts
- Contacts
- Bank transactions
- Payroll data (if available)

## Data Normalisation

| MYOB Field | Canonical Field | Notes |
|------------|----------------|-------|
| UID | externalId | MYOB unique identifier |
| DisplayID | reference | Account/transaction code |
| Date | date | ISO 8601 |
| Total/Amount | amount | Decimal precision preserved |
| Account.DisplayID | accountCode | GL account code |
| Contact.DisplayID | contactId | Contact reference |

## OAuth Flow

1. User clicks "Connect MYOB"
2. Redirect to MYOB OAuth consent screen
3. User grants read-only access
4. Callback stores encrypted tokens
5. Select company file (MYOB-specific)
6. Begin historical data sync

Overview

This skill provides read-only access to MYOB AccountRight and Essentials for extracting historical accounting data. It normalises MYOB responses into a canonical schema so downstream analysis engines can consume consistent financial records. The focus is on secure, audited data extraction for tax and multi-year financial analysis.

How this skill works

The integration authenticates via MYOB OAuth 2.0 and retrieves company files, then performs multi-year fetches of transactions, chart of accounts, contacts, bank entries, and available payroll records. All retrieved records are transformed into a canonical data model (standard fields like externalId, date, amount, accountCode, contactId) before being emitted to analysis engines. Tokens are stored encrypted and API access remains strictly read-only.

When to use it

Connect an MYOB client to perform tax or audit analysis instead of using Xero or QuickBooks
Extract multi-year transaction history for carry-forward and trend analysis
Fetch chart of accounts for general ledger mapping and consolidation
Pull profit & loss and balance sheet reports for financial statement review
Ingest contacts and bank transactions for reconciliation and cashflow analysis

Best practices

Use read-only OAuth credentials restricted to required company files and scopes
Start with a full historical sync, then switch to incremental pulls to reduce API usage
Validate canonical mappings against a sample company file before large-scale syncs
Preserve original MYOB identifiers (externalId) to support idempotent re-syncs and reconciliation
Encrypt and rotate stored tokens per security policy

Example use cases

Tax preparation: extract multi-year transactions and P&L statements for return preparation
GL mapping: pull chart of accounts to map client accounts to a firm-wide chart
Historical analysis: build trend reports across multiple years for advisory work
Reconciliation: ingest bank and contacts to assist bank reconciliation and contact-based matching

FAQ

Is the integration write-capable or destructive?

No. Access is strictly read-only and cannot modify MYOB data.

What data is normalised into the canonical schema?

Transactions, chart of accounts, contacts, bank transactions and available payroll fields are mapped to standard fields like externalId, reference, date, amount, accountCode and contactId.

How does authentication work and where are tokens stored?

Authentication uses MYOB OAuth 2.0; tokens are stored encrypted and used to select the company file before starting a historical sync.