# #GoFile Connect API

> Authorise with HMRC, retrieve tax information and prepare a submission for hosted human approval. Six signed POST endpoints: three each for VAT and Income Tax. Connection IDs and tax identifiers go in JSON bodies.

## Guides

- [Quickstart](/docs/start/): Self-contained signing, authorisation, VAT retrieval and preparation examples.
- [Authorisation basics](/docs/connections/): HMRC consent, connection storage, renewal, software-user identity, fraud evidence and optional browser buttons/webhooks/MCP.
- [VAT](/docs/vat/): Retrieve VAT information, prepare the nine-box return and retrieve receipts.
- [Income Tax](/docs/income-tax/): Retrieve obligations and prepare cumulative Self Employment or UK Property updates.
- [Errors and troubleshooting](/docs/errors/): Response states, validation, safe retries and browser failures.

Each guide has a Markdown twin, for example `/docs/vat.md`.

## Contracts and examples

- [OpenAPI](/openapi.yaml)
- [JSON Schemas](/schemas/v1/schema-bundle.json)
- [Strict AI function tools](/openai-tools.json)
- [Full guide text](/llms-full.txt)
- [Complete VAT browser authorisation](/examples/authorise-vat-web.php.txt)
- [Complete Income Tax browser authorisation](/examples/authorise-itsa-web.php.txt)
- [Command-line PHP quickstart](/examples/quickstart.php.txt)
- [Command-line TypeScript quickstart](/examples/quickstart.ts)
- [Command-line Python quickstart](/examples/quickstart.py)
- [Command-line Bash quickstart](/examples/quickstart.sh)

Signed responses contain request_id, fetched_at, state and data. Errors have state=error and data.code/data.message; absent retry guidance means no automatic retry. Preparation never submits. Only a hosted human confirmation can submit; submission_unconfirmed must never be resubmitted. Return figures are integer pence; VAT balance amounts are decimal-pound strings. HMRC tokens remain on GoFile; store completed connection IDs encrypted in your customer database, not permanently in the example PHP session. HMAC secrets stay on the backend. Sandbox example identifiers are dummy data.