# FormSight API Reference

External Bearer API for generating ABA bank files.

**Base URL:** `https://formsight.com.au`  
**Prefix:** `/api/v1/*`  
**Auth:** `Authorization: Bearer <api-key>`

Web-app session routes under `/api/*` (without `v1`) are **not** part of this public integration surface.

## Authentication

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

- Create keys in the signed-in FormSight web app.
- Raw key shown once; only a hash is stored server-side.
- Missing/invalid/revoked key → `401`.

## Token costs

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

Tokens are charged only on **successful** generate.

## Endpoints

| Method | Path | Tokens | Description |
|--------|------|--------|-------------|
| GET | `/api/v1/me` | 0 | Balance and costs |
| GET | `/api/v1/meta` | 0 | Public constants (no auth) |
| GET | `/api/v1/profiles` | 0 | List payer profiles |
| POST | `/api/v1/profiles` | 0 | Create payer profile |
| GET | `/api/v1/profiles/{id}` | 0 | Get one profile |
| PUT | `/api/v1/profiles/{id}` | 0 | Update profile |
| DELETE | `/api/v1/profiles/{id}` | 0 | Delete profile |
| GET | `/api/v1/template` | 0 | Download signed Excel template |
| GET | `/api/v1/banks` | 0 | Bank code reference |
| POST | `/api/v1/generate` | **5** | ABA from Excel |
| POST | `/api/v1/generate-json` | **5** | ABA from JSON |
| POST | `/api/v1/check` | 0 | Validate `.aba` |
| GET | `/api/health` | 0 | Liveness (no auth) |

Detail pages:

- [me](https://formsight.com.au/docs/api/me.md)
- [meta](https://formsight.com.au/docs/api/meta.md)
- [profiles](https://formsight.com.au/docs/api/profiles.md)
- [template](https://formsight.com.au/docs/api/template.md)
- [banks](https://formsight.com.au/docs/api/banks.md)
- [generate](https://formsight.com.au/docs/api/generate.md)
- [generate-json](https://formsight.com.au/docs/api/generate-json.md)
- [check](https://formsight.com.au/docs/api/check.md)
- [health](https://formsight.com.au/docs/api/health.md)

## Typical flow

1. `GET /api/v1/me`  
2. `POST /api/v1/profiles` (or inline `payer` on generate-json)  
3. `POST /api/v1/generate-json` **or** template + `POST /api/v1/generate`  
4. Optional `POST /api/v1/check`  

## Limits

Default **300** payment lines per file. Over limit → `422` with `over_limit: true`.

## Related

- [Quickstart](https://formsight.com.au/docs/quickstart.md)
- [Errors](https://formsight.com.au/docs/errors.md)
- [Pricing](https://formsight.com.au/docs/pricing.md)