ReferenceSimpleBooks API

Companies

A company's details, categories summary, tax years, summary figures and activity.

Method	Path	Summary
GET	`/api/me`	Who you are: the signed-in person and what they can do here
GET	`/api/companies/:companyId`	Get a company
PUT	`/api/companies/:companyId`	Update a company
GET	`/api/companies/:companyId/tax-years`	Tax years with data
GET	`/api/companies/:companyId/summary`	A tax year's figures
GET	`/api/companies/:companyId/activity`	Recent activity

#Who you are: the signed-in person and what they can do here

GET/api/me

Address: https://<your-org>.brambleit.cloud/simplebooks/api/me
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: SimpleBooks.

Response 200

Field	Type	Description
`user`	object
`user.id`	integer
`user.name`	string
`user.first_name`	string
`user.email`	string
`companies`	array of any

Example response

JSON

{
  "user": {
    "id": 42,
    "name": "Example name",
    "first_name": "Alex",
    "email": "alex@example.com"
  },
  "companies": []
}

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/simplebooks/api/me', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#Get a company

GET/api/companies/:companyId

Address: https://<your-org>.brambleit.cloud/simplebooks/api/companies/:companyId
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: SimpleBooks.

Path parameters

Name	Type	Description
`companyId`required	integer

Response 200

Field	Type	Description
`company`	object
`company.id`	integer
`company.name`	string
`company.trading_name`	string, or null
`company.business_type`	string: "sole_trader" \| "partnership" \| "limited"
`company.owner_name`	string, or null
`company.utr`	string, or null
`company.vat_number`	string, or null
`company.address`	string, or null
`company.email`	string, or null
`company.phone`	string, or null
`company.year_end`	string: "mar31" \| "apr5"
`company.role`	any
`company.modules`	array of any
`categories`	array of object
`categories[].id`	integer
`categories[].name`	string
`categories[].tax_key`	string, or null
`categories[].icon`	string
`categories[].sort`	integer
`categories[].archived`	boolean
`categories[].uses`	integer
`tax_keys`	array of object
`tax_keys[].key`	string
`tax_keys[].label`	string
`current_tax_year`	any
`permissions`	object
`permissions.see_all`	any
`permissions.reports`	array of any
`permissions.manage_company`	any
`permissions.manage_categories`	boolean
`permissions.add_receipts`	boolean
`permissions.invoices`	boolean
`permissions.manage_invoices`	boolean
`permissions.tax`	boolean
`permissions.income`	boolean
`permissions.manage_income`	boolean

Example response

JSON

{
  "company": {
    "id": 42,
    "name": "Example name",
    "trading_name": "Example trading name",
    "business_type": "sole_trader",
    "owner_name": "Example owner name",
    "utr": "string",
    "vat_number": "string",
    "address": "string",
    "email": "alex@example.com",
    "phone": "string",
    "year_end": "mar31",
    "role": null,
    "modules": []
  },
  "categories": [
    {
      "id": 42,
      "name": "Example name",
      "tax_key": "…",
      "icon": "string",
      "sort": 1,
      "archived": false,
      "uses": 1
    }
  ],
  "tax_keys": [
    {
      "key": "…",
      "label": "Example label"
    }
  ],
  "current_tax_year": null,
  "permissions": {
    "see_all": null,
    "reports": [],
    "manage_company": null,
    "manage_categories": false,
    "add_receipts": false,
    "invoices": false,
    "manage_invoices": false,
    "tax": false,
    "income": false,
    "manage_income": false
  }
}

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/simplebooks/api/companies/1', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#Update a company

PUT/api/companies/:companyId

Address: https://<your-org>.brambleit.cloud/simplebooks/api/companies/:companyId
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: SimpleBooks.

Path parameters

Name	Type	Description
`companyId`required	integer

Request body JSON

Name	Type	Description
`k`	any

Response 200

Field	Type	Description
`ok`	boolean

Example response

JSON

{
  "ok": true
}

Errors

Status	Message
400	The company needs a name
400	A UTR is 10 digits
400	Unknown year end

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/simplebooks/api/companies/1', {
  method: 'PUT',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"k":"…"}),
});
const data = await res.json();

#Tax years with data

GET/api/companies/:companyId/tax-years

Address: https://<your-org>.brambleit.cloud/simplebooks/api/companies/:companyId/tax-years
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: SimpleBooks.

Path parameters

Name	Type	Description
`companyId`required	integer

Response 200

Field	Type	Description
`current`	any
`years`	array of any

Example response

JSON

{
  "current": null,
  "years": []
}

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/simplebooks/api/companies/1/tax-years', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#A tax year's figures

GET/api/companies/:companyId/summary

Address: https://<your-org>.brambleit.cloud/simplebooks/api/companies/:companyId/summary
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: SimpleBooks.

Path parameters

Name	Type	Description
`companyId`required	integer

Query parameters

Name	Type	Description
`tax_year`	any

Response 200

Field	Type	Description
`tax_year`	any
`range`	any
`totals`	object
`totals.receipts`	integer
`totals.spent`	any
`totals.claimable`	any
`totals.vat`	any
`totals.to_review`	number
`totals.undated`	integer
`by_category`	array of object
`by_category[].category_id`	integer, or null
`by_category[].name`	string
`by_category[].icon`	string
`by_category[].tax_key`	string, or null
`by_category[].n`	integer
`by_category[].spent`	any
`by_category[].claimable`	any
`by_month`	array of object
`by_month[].month`	string
`by_month[].n`	integer
`by_month[].spent`	any
`by_tax_key`	string

Example response

JSON

{
  "tax_year": null,
  "range": null,
  "totals": {
    "receipts": 1,
    "spent": null,
    "claimable": null,
    "vat": null,
    "to_review": 12.5,
    "undated": 1
  },
  "by_category": [
    {
      "category_id": 7,
      "name": "Example name",
      "icon": "string",
      "tax_key": "…",
      "n": 3,
      "spent": null,
      "claimable": null
    }
  ],
  "by_month": [
    {
      "month": "string",
      "n": 3,
      "spent": null
    }
  ],
  "by_tax_key": "…"
}

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/simplebooks/api/companies/1/summary', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#Recent activity

GET/api/companies/:companyId/activity

Address: https://<your-org>.brambleit.cloud/simplebooks/api/companies/:companyId/activity
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: SimpleBooks.

Path parameters

Name	Type	Description
`companyId`required	integer

Query parameters

Name	Type	Description
`limit`	number

Response 200

Field	Type	Description
`activity`	array of any

Example response

JSON

{
  "activity": []
}

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/simplebooks/api/companies/1/activity', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

Was this page helpful?