API endpoints — AccountantOS Docs

Six endpoints, all GET, all scoped to the credential’s one client. Authentication and the error envelope are on the overview; every example below assumes the bearer header. Lists paginate with ?page= and ?pageSize= (default 50, max 200) and answer { data, pagination: { page, pageSize, total, hasMore } }.

Start here

GET/api/v1/ping

Proves the credential authenticates and names the client it is scoped to. The first call every integration should make.

Request

curl https://app.accountantos.co.uk/api/v1/ping \
  -H "Authorization: Bearer aos_sk_YOUR_SECRET"

Response — 200

{
  "ok": true,
  "clientId": "aos_ci_b12ea01c538d23f2",
  "clientName": "Meridian & Co",
  "time": "2026-08-17T11:29:54.333Z"
}

Status	Code	When
401	`unauthorized`	Missing, malformed or wrong bearer token
403	`client_archived`	The credential's client is archived
429	`rate_limited`	Over the per-key budget (see Rate limits)

Client

GET/api/v1/client

The profile of the one client this credential is scoped to. `id` is the credential's public client ID, not an internal key.

Request

curl https://app.accountantos.co.uk/api/v1/client \
  -H "Authorization: Bearer aos_sk_YOUR_SECRET"

Response — 200

{
  "id": "aos_ci_b12ea01c538d23f2",
  "name": "Meridian & Co",
  "companyNumber": "09876543",
  "status": "active",
  "industry": "Architecture",
  "businessType": "business",
  "vatScheme": "Quarterly",
  "contactName": "Dan Meridian",
  "contactEmail": "dan@meridian.co",
  "clientSince": "2024-03-01T00:00:00.000Z"
}

Status	Code	When
401	`unauthorized`	Missing, malformed or wrong bearer token
403	`client_archived`	The credential's client is archived
429	`rate_limited`	Over the per-key budget (see Rate limits)
404	`not_found`	No client record exists for this credential yet

Tasks

GET/api/v1/tasks

The client's tasks, paginated. Each task carries its status, assignee, due date and group.

Parameter	In	Type	Required	Notes
status	query	string	No	Filter: todo · in-progress · review · done · stuck
page	query	integer	No	1-based page, default 1
pageSize	query	integer	No	Default 50, max 200

Request

curl https://app.accountantos.co.uk/api/v1/tasks \
  -H "Authorization: Bearer aos_sk_YOUR_SECRET"

Response — 200

{
  "data": [
    {
      "id": "3f1c…",
      "title": "VAT quarter to 30 September",
      "description": null,
      "status": "todo",
      "assignee": "Priya Shah",
      "dueDate": "2026-11-07T00:00:00.000Z",
      "startedAt": null,
      "completedAt": null,
      "isFilingDeadline": false,
      "group": { "id": "9a2b…", "name": "Q3 close" },
      "createdAt": "2026-08-01T09:12:00.000Z",
      "updatedAt": "2026-08-14T16:03:00.000Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 50, "total": 34, "hasMore": false }
}

Status	Code	When
401	`unauthorized`	Missing, malformed or wrong bearer token
403	`client_archived`	The credential's client is archived
429	`rate_limited`	Over the per-key budget (see Rate limits)
400	`invalid_status`	status is not one of the five values

GET/api/v1/tasks/{id}

One task by id. Another client's task id is simply not found — ids don't resolve across clients.

Parameter	In	Type	Required	Notes
id	path	string	Yes	The task id from the list endpoint

Request

curl https://app.accountantos.co.uk/api/v1/tasks/TASK_ID \
  -H "Authorization: Bearer aos_sk_YOUR_SECRET"

Response — 200

{
  "id": "3f1c…",
  "title": "VAT quarter to 30 September",
  "status": "todo",
  "assignee": "Priya Shah",
  "dueDate": "2026-11-07T00:00:00.000Z",
  "isFilingDeadline": false,
  "group": { "id": "9a2b…", "name": "Q3 close" },
  "createdAt": "2026-08-01T09:12:00.000Z",
  "updatedAt": "2026-08-14T16:03:00.000Z"
}

Status	Code	When
401	`unauthorized`	Missing, malformed or wrong bearer token
403	`client_archived`	The credential's client is archived
429	`rate_limited`	Over the per-key budget (see Rate limits)
404	`not_found`	No such task for this client

Bills

GET/api/v1/bills

The client's supplier bills, paginated server-side. The envelope also carries per-status counts.

Parameter	In	Type	Required	Notes
status	query	string	No	Filter: extracting · ready · synced · failed · archived · pending · voided
page	query	integer	No	1-based page, default 1
pageSize	query	integer	No	Default 50, max 200

Request

curl https://app.accountantos.co.uk/api/v1/bills \
  -H "Authorization: Bearer aos_sk_YOUR_SECRET"

Response — 200

{
  "data": [
    {
      "id": "b7e2…",
      "fileName": "edf-aug.pdf",
      "vendor": "EDF Energy",
      "invoiceNumber": "INV-118423",
      "invoiceDate": "2026-08-11T00:00:00.000Z",
      "currency": "GBP",
      "grossAmount": 1082.44,
      "netAmount": 1030.90,
      "vatAmount": 51.54,
      "vatRate": "5%",
      "category": "Utilities",
      "description": null,
      "status": "synced",
      "source": "email",
      "createdAt": "2026-08-11T08:14:00.000Z",
      "updatedAt": "2026-08-11T09:02:00.000Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 50, "total": 61, "hasMore": true },
  "counts": { "extracting": 2, "ready": 7, "synced": 49, "failed": 1, "archived": 2, "voided": 0 }
}

Status	Code	When
401	`unauthorized`	Missing, malformed or wrong bearer token
403	`client_archived`	The credential's client is archived
429	`rate_limited`	Over the per-key budget (see Rate limits)
400	`invalid_status`	status is not one of the listed values

Deadlines

GET/api/v1/deadlines

Upcoming, uncompleted obligations for the client — statutory filing dates and anything tracked as a deadline. Unpaged.

Parameter	In	Type	Required	Notes
daysAhead	query	integer	No	Window in days, default 14, max 365

Request

curl https://app.accountantos.co.uk/api/v1/deadlines \
  -H "Authorization: Bearer aos_sk_YOUR_SECRET"

Response — 200

{
  "data": [
    {
      "id": "d41a…",
      "title": "Confirmation statement",
      "dueDate": "2026-10-12T00:00:00.000Z",
      "urgency": "amber",
      "isCompleted": false
    }
  ]
}

Status	Code	When
401	`unauthorized`	Missing, malformed or wrong bearer token
403	`client_archived`	The credential's client is archived
429	`rate_limited`	Over the per-key budget (see Rate limits)
400	`invalid_days_ahead`	daysAhead is not an integer between 1 and 365

Start here

GET/api/v1/ping

Proves the credential authenticates and names the client it is scoped to. The first call every integration should make.

Request

curl https://app.accountantos.co.uk/api/v1/ping \
  -H "Authorization: Bearer aos_sk_YOUR_SECRET"

Response — 200

{
  "ok": true,
  "clientId": "aos_ci_b12ea01c538d23f2",
  "clientName": "Meridian & Co",
  "time": "2026-08-17T11:29:54.333Z"
}

Status	Code	When
401	`unauthorized`	Missing, malformed or wrong bearer token
403	`client_archived`	The credential's client is archived
429	`rate_limited`	Over the per-key budget (see Rate limits)

Client

GET/api/v1/client

The profile of the one client this credential is scoped to. `id` is the credential's public client ID, not an internal key.

Request

curl https://app.accountantos.co.uk/api/v1/client \
  -H "Authorization: Bearer aos_sk_YOUR_SECRET"

Response — 200

{
  "id": "aos_ci_b12ea01c538d23f2",
  "name": "Meridian & Co",
  "companyNumber": "09876543",
  "status": "active",
  "industry": "Architecture",
  "businessType": "business",
  "vatScheme": "Quarterly",
  "contactName": "Dan Meridian",
  "contactEmail": "dan@meridian.co",
  "clientSince": "2024-03-01T00:00:00.000Z"
}

Status	Code	When
401	`unauthorized`	Missing, malformed or wrong bearer token
403	`client_archived`	The credential's client is archived
429	`rate_limited`	Over the per-key budget (see Rate limits)
404	`not_found`	No client record exists for this credential yet

Tasks

GET/api/v1/tasks

The client's tasks, paginated. Each task carries its status, assignee, due date and group.

Parameter	In	Type	Required	Notes
status	query	string	No	Filter: todo · in-progress · review · done · stuck
page	query	integer	No	1-based page, default 1
pageSize	query	integer	No	Default 50, max 200

Request

curl https://app.accountantos.co.uk/api/v1/tasks \
  -H "Authorization: Bearer aos_sk_YOUR_SECRET"

Response — 200

{
  "data": [
    {
      "id": "3f1c…",
      "title": "VAT quarter to 30 September",
      "description": null,
      "status": "todo",
      "assignee": "Priya Shah",
      "dueDate": "2026-11-07T00:00:00.000Z",
      "startedAt": null,
      "completedAt": null,
      "isFilingDeadline": false,
      "group": { "id": "9a2b…", "name": "Q3 close" },
      "createdAt": "2026-08-01T09:12:00.000Z",
      "updatedAt": "2026-08-14T16:03:00.000Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 50, "total": 34, "hasMore": false }
}

Status	Code	When
401	`unauthorized`	Missing, malformed or wrong bearer token
403	`client_archived`	The credential's client is archived
429	`rate_limited`	Over the per-key budget (see Rate limits)
400	`invalid_status`	status is not one of the five values

GET/api/v1/tasks/{id}

One task by id. Another client's task id is simply not found — ids don't resolve across clients.

Parameter	In	Type	Required	Notes
id	path	string	Yes	The task id from the list endpoint

Request

curl https://app.accountantos.co.uk/api/v1/tasks/TASK_ID \
  -H "Authorization: Bearer aos_sk_YOUR_SECRET"

Response — 200

{
  "id": "3f1c…",
  "title": "VAT quarter to 30 September",
  "status": "todo",
  "assignee": "Priya Shah",
  "dueDate": "2026-11-07T00:00:00.000Z",
  "isFilingDeadline": false,
  "group": { "id": "9a2b…", "name": "Q3 close" },
  "createdAt": "2026-08-01T09:12:00.000Z",
  "updatedAt": "2026-08-14T16:03:00.000Z"
}

Status	Code	When
401	`unauthorized`	Missing, malformed or wrong bearer token
403	`client_archived`	The credential's client is archived
429	`rate_limited`	Over the per-key budget (see Rate limits)
404	`not_found`	No such task for this client

Bills

GET/api/v1/bills

The client's supplier bills, paginated server-side. The envelope also carries per-status counts.

Parameter	In	Type	Required	Notes
status	query	string	No	Filter: extracting · ready · synced · failed · archived · pending · voided
page	query	integer	No	1-based page, default 1
pageSize	query	integer	No	Default 50, max 200

Request

curl https://app.accountantos.co.uk/api/v1/bills \
  -H "Authorization: Bearer aos_sk_YOUR_SECRET"

Response — 200

{
  "data": [
    {
      "id": "b7e2…",
      "fileName": "edf-aug.pdf",
      "vendor": "EDF Energy",
      "invoiceNumber": "INV-118423",
      "invoiceDate": "2026-08-11T00:00:00.000Z",
      "currency": "GBP",
      "grossAmount": 1082.44,
      "netAmount": 1030.90,
      "vatAmount": 51.54,
      "vatRate": "5%",
      "category": "Utilities",
      "description": null,
      "status": "synced",
      "source": "email",
      "createdAt": "2026-08-11T08:14:00.000Z",
      "updatedAt": "2026-08-11T09:02:00.000Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 50, "total": 61, "hasMore": true },
  "counts": { "extracting": 2, "ready": 7, "synced": 49, "failed": 1, "archived": 2, "voided": 0 }
}

Status	Code	When
401	`unauthorized`	Missing, malformed or wrong bearer token
403	`client_archived`	The credential's client is archived
429	`rate_limited`	Over the per-key budget (see Rate limits)
400	`invalid_status`	status is not one of the listed values

Deadlines

GET/api/v1/deadlines

Upcoming, uncompleted obligations for the client — statutory filing dates and anything tracked as a deadline. Unpaged.

Parameter	In	Type	Required	Notes
daysAhead	query	integer	No	Window in days, default 14, max 365

Request

curl https://app.accountantos.co.uk/api/v1/deadlines \
  -H "Authorization: Bearer aos_sk_YOUR_SECRET"

Response — 200

{
  "data": [
    {
      "id": "d41a…",
      "title": "Confirmation statement",
      "dueDate": "2026-10-12T00:00:00.000Z",
      "urgency": "amber",
      "isCompleted": false
    }
  ]
}

Status	Code	When
401	`unauthorized`	Missing, malformed or wrong bearer token
403	`client_archived`	The credential's client is archived
429	`rate_limited`	Over the per-key budget (see Rate limits)
400	`invalid_days_ahead`	daysAhead is not an integer between 1 and 365

Endpoints

Start here

Client

Tasks

Bills

Deadlines

Endpoints

Start here

Client

Tasks

Bills

Deadlines