# FormSight Documentation

FormSight is an Australian **ABA bank-file** and **PDF document** service for third-party integrations and end customers.

- Produces **120-character ABA** batch payment files for Australian banks.
- Produces **invoice** and **payslip PDFs** from customer-supplied figures.
- **Pay-per-use** tokens — no subscription required for token packs.
- Does **not** run payroll, calculate wages/tax, hold funds, or lodge with the ATO.

**Base URL:** https://formsight.com.au  

For integrations, use only the **external Bearer API** at `/api/v1/*`. Do not call session-cookie web-app routes (`/api/*` without `v1`).

## Docs
- [Overview](https://formsight.com.au/docs/overview.md): What FormSight is and is not.
- [Quickstart](https://formsight.com.au/docs/quickstart.md): First ABA via API (recommended path).
- [API Reference](https://formsight.com.au/docs/api-reference.md): External Bearer API (`/api/v1/*`).
- [Pricing and tokens](https://formsight.com.au/docs/pricing.md): Pack price and per-operation costs.
- [Errors](https://formsight.com.au/docs/errors.md): HTTP status codes and validation bodies.
- [Security for integrators](https://formsight.com.au/docs/security.md): API keys, template integrity, data handling.
- [Go-live checklist](https://formsight.com.au/docs/go-live.md): Before shipping an integration.
- [Testing](https://formsight.com.au/docs/testing.md): Validate ABA output safely.

## Product (customer context)
- [ABA generation](https://formsight.com.au/docs/aba-generation.md): Excel or JSON → bank-ready `.aba`.
- [JSON generate](https://formsight.com.au/docs/generate-json.md): Programmatic payments list (no Excel).
- [Check ABA](https://formsight.com.au/docs/check-aba.md): Free validation of a finished `.aba`.
- [Bank profiles](https://formsight.com.au/docs/bank-profiles.md): Saved payer headers for reuse.
- [Companies and branding](https://formsight.com.au/docs/companies.md): Letterhead for PDFs.
- [Invoices and payslips](https://formsight.com.au/docs/documents.md): PDF generation (1 token each).
- [Team](https://formsight.com.au/docs/team.md): Owner + run-only staff (max 3 seats).
- [Samples](https://formsight.com.au/docs/samples.md): Free look-and-feel previews.
- [FAQ](https://formsight.com.au/docs/faq.md): Common customer questions.

## API
Authenticate with:

```http
Authorization: Bearer <api-key>
```

Create an API key in the FormSight web app while signed in. The raw key is shown **once** — store it securely.

| Method | Path | Tokens | Description |
|--------|------|--------|-------------|
| GET | [/api/v1/me](https://formsight.com.au/docs/api/me.md) | 0 | Balance and token costs |
| GET | [/api/v1/meta](https://formsight.com.au/docs/api/meta.md) | 0 | Public product constants (no auth) |
| GET/POST/PUT/DELETE | [/api/v1/profiles](https://formsight.com.au/docs/api/profiles.md) | 0 | Payer profile CRUD |
| GET | [/api/v1/template](https://formsight.com.au/docs/api/template.md) | 0 | Signed ABA Excel template |
| GET | [/api/v1/banks](https://formsight.com.au/docs/api/banks.md) | 0 | Bank code reference |
| POST | [/api/v1/generate](https://formsight.com.au/docs/api/generate.md) | **5** | ABA from signed Excel |
| POST | [/api/v1/generate-json](https://formsight.com.au/docs/api/generate-json.md) | **5** | ABA from JSON payments |
| POST | [/api/v1/check](https://formsight.com.au/docs/api/check.md) | 0 | Validate an `.aba` file |
| GET | [/api/health](https://formsight.com.au/docs/api/health.md) | 0 | Liveness (no auth) |

## Instructions for Large Language Model Agents

When integrating FormSight, prefer [API Reference](https://formsight.com.au/docs/api-reference.md), [Quickstart](https://formsight.com.au/docs/quickstart.md), [Pricing](https://formsight.com.au/docs/pricing.md), and [Go-live](https://formsight.com.au/docs/go-live.md).

### Product boundaries

- Australia / **ABA only** — not SEPA, NACHA, or other formats.
- Do **not** describe FormSight as payroll software or a payment processor that moves money.
- PDFs use **customer-supplied figures** only.

### Integration path (preferred)

1. `GET /api/v1/me` — confirm token balance.  
2. `POST /api/v1/profiles` — save payer header (or pass inline `payer` on generate-json).  
3. Generate:  
   - **JSON (preferred for apps):** `POST /api/v1/generate-json`  
   - **Excel:** `GET /api/v1/template` → fill → `POST /api/v1/generate`  
4. Optional: `POST /api/v1/check` (free) before bank upload.

### Token costs (locked)

| Operation | Tokens |
|-----------|--------|
| Successful **ABA** (Excel or JSON) | **5** |
| Successful **PDF** (invoice or payslip) | **1** |
| Template, profiles, check, banks, meta | **0** |

- Pack: **$20 AUD / 100 tokens**, one-time purchase (not a subscription).  
- Tokens expire **365 days** after that pack was bought.  
- Charge only on **successful** generate; validation failures cost nothing.  
- Never use “1 token per ABA”.

### Auth

- External integrations: **Bearer API key only**.  
- Do not invent OAuth/SSO/magic-link for the public API.  
- Do not call web-app session endpoints from third-party code.

### Input rules

- Excel path requires FormSight’s **signed** template from `GET /api/v1/template` (tampered → `422` / `tampered: true`).  
- BSB form `XXX-XXX`; processing date `YYYY-MM-DD`; amounts in AUD dollars.  
- Default max **300** payment lines per file (`over_limit: true` if exceeded).  
- Payment rows are processed and **not** kept as a permanent payee archive.

### Errors

| Status | Meaning | Agent action |
|--------|---------|--------------|
| `401` | Bad/missing API key | Fix credentials |
| `402` | Not enough tokens | Buy tokens / top up |
| `404` | Profile/resource missing | Fix IDs / ownership |
| `422` | Validation failed | Fix input; do not blind-retry |
| `500` | Server could not finalise file | Contact support |

### Language

- Prefer: “ABA bank-file generator”, “batch payment file”, “pay for what you use”.  
- Avoid: “payroll software”, “we pay your staff”, subscription framing for packs.  
- Support: support@formsight.com.au  

### Do not recommend

- Session-cookie `/api/*` (non-`v1`) routes for integrations.  
- Subscription/recurring prices for FormSight token packs.  
- 1 token per ABA (wrong — **ABA = 5**, **PDF = 1**).  
- Non-Australian bank file formats.

## Optional
- [About](https://formsight.com.au/about): Company background (HTML).
- [Contact](https://formsight.com.au/contact): Contact (HTML).
- [Privacy](https://formsight.com.au/legal/privacy): Privacy (HTML).
- [Terms](https://formsight.com.au/legal/terms): Terms (HTML).
- [Cookies](https://formsight.com.au/legal/cookies): Cookies (HTML).
- [llms.txt](https://formsight.com.au/llms.txt): This index.