REST API

Status: planned, not live. Endpoints below are the agreed design and may change before launch. Use the client MCP server today.

Design

Base address: https://mcp.goforma.com/v1, served next to the MCP server, so one sign-in covers both.
Auth: OAuth 2.0 authorisation code with PKCE, on the same sign-in as the MCP server. Scopes are the same as MCP: read, act, finance:read. If your client sends an RFC 8707 resource, use https://mcp.goforma.com/v1. A token issued for the MCP server (…/mcp) is not accepted by the API.
Data: JSON. Deadlines and post carry stable ids for deduplication. Errors are RFC 9457 problem details (application/problem+json), and a missing permission returns 403 with required_scopes. Rate limit: 120 requests a minute per person.
Reference: an OpenAPI 3.1 file will be published at /openapi.json on this site.

Method and path	Scope	Returns or does
`GET /v1/me`	read	The signed-in person
`GET /v1/companies`	read	Companies this person can see
`GET /v1/company`	read	The active company's profile
`GET /v1/deadlines`	read	Upcoming deadlines
`GET /v1/filings`, `GET /v1/filings/{id}`	read	Filing status, or one filing
`GET /v1/mail?since=&limit=`	read	Post received, newest first
`GET /v1/onboarding`	read	Onboarding progress
`GET /v1/verification`	read	Identity check status
`GET /v1/accountant`	read	Your accountant and how to book a call
`POST /v1/requests`	act	Sends a request to your GoForma team
`POST /v1/deadlines/{id}/chase`	act	Asks for an update on a deadline
`GET /v1/finance/snapshot`, `GET /v1/finance/invoices`	finance:read	Figures from FreeAgent

Never in the API: filing with HMRC or Companies House, payments or card details, FreeAgent writes.