{
 "openapi": "3.0.3",
 "info": {
  "title": "Bramble SimpleBooks API",
  "version": "2026-11-13",
  "description": "Bramble SimpleBooks: bookkeeping for sole traders. Companies, receipts read automatically from photos and PDFs, categories, income, customers and invoices, the Self Assessment summary, and exports. Companies and who can use them are set up in the [Admin Centre API](/apps/admin/api/simplebooks).\n"
 },
 "servers": [
  {
   "url": "https://{org}.brambleit.cloud/simplebooks",
   "variables": {
    "org": {
     "default": "your-org"
    }
   }
  },
  {
   "url": "https://{org}.brambleit.cloud/api",
   "variables": {
    "org": {
     "default": "your-org"
    }
   }
  }
 ],
 "components": {
  "securitySchemes": {
   "apiKey": {
    "type": "apiKey",
    "in": "header",
    "name": "X-API-Key"
   },
   "session": {
    "type": "apiKey",
    "in": "cookie",
    "name": "sso_session"
   },
   "bearer": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "JWT"
   }
  }
 },
 "tags": [
  {
   "name": "Companies",
   "description": "A company's details, categories summary, tax years, summary figures and activity."
  },
  {
   "name": "Receipts",
   "description": "Receipts and their files, read automatically (merchant, date, total, VAT), categories, the bin, and reprocessing.\n"
  },
  {
   "name": "Invoices & customers",
   "description": "Customers, invoice settings, invoices, sending them, PDFs, and payments."
  },
  {
   "name": "Income",
   "description": "Money received (cash basis), including invoice payments."
  },
  {
   "name": "Self Assessment",
   "description": "The year's figures for Self Assessment, marking it filed, and the PDF."
  },
  {
   "name": "Exports",
   "description": "A tax year as CSV, or a zip of receipts and files for one or more years."
  },
  {
   "name": "Share to SimpleBooks",
   "description": "Where \"Share to SimpleBooks\" from a phone lands."
  },
  {
   "name": "Legacy (SimpleBooks v1)",
   "description": "Endpoints of the original SimpleBooks, kept for reference."
  },
  {
   "name": "Export"
  }
 ],
 "paths": {
  "/api/me": {
   "get": {
    "tags": [
     "Companies"
    ],
    "summary": "Who you are: the signed-in person and what they can do here",
    "operationId": "get-api-me",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "user": {
           "type": "object",
           "properties": {
            "id": {
             "type": "integer"
            },
            "name": {
             "type": "string"
            },
            "first_name": {
             "type": "string"
            },
            "email": {
             "type": "string"
            }
           }
          },
          "companies": {
           "type": "array",
           "items": {}
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/companies/{companyId}": {
   "get": {
    "tags": [
     "Companies"
    ],
    "summary": "Get a company",
    "operationId": "get-api-companies-companyid",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "company": {
           "type": "object",
           "properties": {
            "id": {
             "type": "integer"
            },
            "name": {
             "type": "string"
            },
            "trading_name": {
             "type": "string",
             "nullable": true
            },
            "business_type": {
             "type": "string",
             "enum": [
              "sole_trader",
              "partnership",
              "limited"
             ]
            },
            "owner_name": {
             "type": "string",
             "nullable": true
            },
            "utr": {
             "type": "string",
             "nullable": true
            },
            "vat_number": {
             "type": "string",
             "nullable": true
            },
            "address": {
             "type": "string",
             "nullable": true
            },
            "email": {
             "type": "string",
             "nullable": true
            },
            "phone": {
             "type": "string",
             "nullable": true
            },
            "year_end": {
             "type": "string",
             "enum": [
              "mar31",
              "apr5"
             ]
            },
            "role": {},
            "modules": {
             "type": "array",
             "items": {}
            }
           }
          },
          "categories": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "id": {
              "type": "integer"
             },
             "name": {
              "type": "string"
             },
             "tax_key": {
              "type": "string",
              "nullable": true
             },
             "icon": {
              "type": "string"
             },
             "sort": {
              "type": "integer"
             },
             "archived": {
              "type": "boolean"
             },
             "uses": {
              "type": "integer"
             }
            }
           }
          },
          "tax_keys": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "key": {
              "type": "string"
             },
             "label": {
              "type": "string"
             }
            }
           }
          },
          "current_tax_year": {},
          "permissions": {
           "type": "object",
           "properties": {
            "see_all": {},
            "reports": {
             "type": "array",
             "items": {}
            },
            "manage_company": {},
            "manage_categories": {
             "type": "boolean"
            },
            "add_receipts": {
             "type": "boolean"
            },
            "invoices": {
             "type": "boolean"
            },
            "manage_invoices": {
             "type": "boolean"
            },
            "tax": {
             "type": "boolean"
            },
            "income": {
             "type": "boolean"
            },
            "manage_income": {
             "type": "boolean"
            }
           }
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "put": {
    "tags": [
     "Companies"
    ],
    "summary": "Update a company",
    "operationId": "put-api-companies-companyid",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "The company needs a name"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "k": {}
        }
       }
      }
     }
    }
   }
  },
  "/api/companies/{companyId}/categories": {
   "post": {
    "tags": [
     "Receipts"
    ],
    "summary": "Add a category",
    "operationId": "post-api-companies-companyid-categories",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "201": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "id": {
           "type": "integer"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Give the category a name"
     },
     "409": {
      "description": "There is already a category with that name"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "name": {
          "type": "string"
         },
         "tax_key": {
          "type": "string"
         },
         "icon": {}
        }
       }
      }
     }
    }
   }
  },
  "/api/companies/{companyId}/categories/{id}": {
   "patch": {
    "tags": [
     "Receipts"
    ],
    "summary": "Update a category",
    "operationId": "patch-api-companies-companyid-categories-id",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Give the category a name"
     },
     "404": {
      "description": "Category not found"
     },
     "409": {
      "description": "There is already a category with that name"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "name": {
          "type": "string"
         },
         "tax_key": {
          "type": "string"
         },
         "archived": {}
        }
       }
      }
     }
    }
   }
  },
  "/api/companies/{companyId}/receipts": {
   "get": {
    "tags": [
     "Receipts"
    ],
    "summary": "List receipts",
    "operationId": "get-api-companies-companyid-receipts",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "deleted",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "`1` for the bin."
     },
     {
      "name": "tax_year",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "A tax year, e.g. `2025-26`."
     },
     {
      "name": "month",
      "in": "query",
      "required": false,
      "schema": {},
      "description": "A month within it."
     },
     {
      "name": "status",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Processing status."
     },
     {
      "name": "category_id",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "A category."
     },
     {
      "name": "q",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Text to search for."
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "offset",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "receipts": {
           "type": "array",
           "items": {}
          },
          "more": {
           "type": "boolean"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "post": {
    "tags": [
     "Receipts"
    ],
    "summary": "Add a receipt",
    "operationId": "post-api-companies-companyid-receipts",
    "description": "`multipart/form-data` with the photo or PDF. It's read automatically; check `ocr_status`.\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "400": {
      "description": "Attach a photo or PDF of the receipt"
     },
     "duplicateUpload ? 200 : 201": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "id": {
           "type": "integer"
          },
          "duplicate_upload": {}
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "multipart/form-data": {
       "schema": {
        "type": "object",
        "properties": {
         "client_ref": {
          "description": "Your own reference, so a retried upload isn't added twice."
         },
         "source": {
          "description": "Where it came from (camera, share, upload)."
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/companies/{companyId}/receipts/{id}": {
   "get": {
    "tags": [
     "Receipts"
    ],
    "summary": "Get a receipt",
    "operationId": "get-api-companies-companyid-receipts-id",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "receipt": {},
          "suggestions": {
           "type": "array",
           "items": {}
          },
          "ocr_text": {
           "type": "string"
          },
          "original": {
           "type": "object",
           "nullable": true,
           "properties": {
            "mime": {
             "type": "string"
            },
            "bytes": {
             "type": "integer"
            },
            "sha256": {
             "type": "string"
            },
            "width": {
             "type": "integer",
             "nullable": true
            },
            "height": {
             "type": "integer",
             "nullable": true
            }
           }
          },
          "possible_duplicates": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "id": {
              "type": "integer"
             },
             "merchant": {
              "type": "string",
              "nullable": true
             },
             "total": {
              "type": "number",
              "nullable": true
             },
             "receipt_date": {
              "type": "string",
              "format": "date",
              "nullable": true
             }
            }
           }
          },
          "can_edit": {
           "type": "boolean"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "patch": {
    "tags": [
     "Receipts"
    ],
    "summary": "Update a receipt",
    "operationId": "patch-api-companies-companyid-receipts-id",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "A receipt needs a total and a date before it can be saved"
     },
     "403": {
      "description": "You can't change this receipt"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "merchant": {
          "type": "string"
         },
         "description": {
          "type": "string"
         },
         "notes": {
          "type": "string"
         },
         "payment_method": {},
         "receipt_date": {
          "type": "string",
          "format": "date"
         },
         "business_pct": {
          "type": "number",
          "description": "The business share of it, 0–100."
         },
         "category_id": {
          "type": "string"
         },
         "confirm": {}
        }
       }
      }
     }
    }
   },
   "delete": {
    "tags": [
     "Receipts"
    ],
    "summary": "Move a receipt to the bin",
    "operationId": "delete-api-companies-companyid-receipts-id",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "403": {
      "description": "You can't delete this receipt"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/companies/{companyId}/receipts/{id}/restore": {
   "post": {
    "tags": [
     "Receipts"
    ],
    "summary": "Restore a receipt from the bin",
    "operationId": "post-api-companies-companyid-receipts-id-restore",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "403": {
      "description": "You can't restore this receipt"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/companies/{companyId}/receipts/{id}/reprocess": {
   "post": {
    "tags": [
     "Receipts"
    ],
    "summary": "Read a receipt again",
    "operationId": "post-api-companies-companyid-receipts-id-reprocess",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Text can only be read from photos"
     },
     "403": {
      "description": "You can't change this receipt"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/companies/{companyId}/receipts/{id}/file/{kind}": {
   "get": {
    "tags": [
     "Receipts"
    ],
    "summary": "Decrypted file. Only ever served from here — authenticated and checked against the user's access to this receipt",
    "operationId": "get-api-companies-companyid-receipts-id-file-kind",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "kind",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "original",
        "display",
        "thumb"
       ]
      }
     },
     {
      "name": "download",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "File, page or redirect"
     },
     "404": {
      "description": "No file for this receipt"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/companies/{companyId}/tax-years": {
   "get": {
    "tags": [
     "Companies"
    ],
    "summary": "Tax years with data",
    "operationId": "get-api-companies-companyid-tax-years",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "current": {},
          "years": {
           "type": "array",
           "items": {}
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/companies/{companyId}/summary": {
   "get": {
    "tags": [
     "Companies"
    ],
    "summary": "A tax year's figures",
    "operationId": "get-api-companies-companyid-summary",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "tax_year",
      "in": "query",
      "required": false,
      "schema": {}
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "tax_year": {},
          "range": {},
          "totals": {
           "type": "object",
           "properties": {
            "receipts": {
             "type": "integer"
            },
            "spent": {},
            "claimable": {},
            "vat": {},
            "to_review": {
             "type": "number"
            },
            "undated": {
             "type": "integer"
            }
           }
          },
          "by_category": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "category_id": {
              "type": "integer",
              "nullable": true
             },
             "name": {
              "type": "string"
             },
             "icon": {
              "type": "string"
             },
             "tax_key": {
              "type": "string",
              "nullable": true
             },
             "n": {
              "type": "integer"
             },
             "spent": {},
             "claimable": {}
            }
           }
          },
          "by_month": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "month": {
              "type": "string"
             },
             "n": {
              "type": "integer"
             },
             "spent": {}
            }
           }
          },
          "by_tax_key": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/companies/{companyId}/export.csv": {
   "get": {
    "tags": [
     "Export"
    ],
    "summary": "One tax year as a spreadsheet — same columns as the CSV inside the ZIP",
    "operationId": "get-api-companies-companyid-export-csv",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "tax_year",
      "in": "query",
      "required": false,
      "schema": {}
     }
    ],
    "responses": {
     "200": {
      "description": "File, page or redirect"
     },
     "403": {
      "description": "Your role in this company doesn't allow exports"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/companies/{companyId}/exports": {
   "post": {
    "tags": [
     "Exports"
    ],
    "summary": "Start a zip export",
    "operationId": "post-api-companies-companyid-exports",
    "description": "Bulk download (lib/exports.js): POST starts collating a ZIP of one or more tax years in the background, GET polls it, /download fetches it. Submitters get a ZIP of their own receipts only.\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "202": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "export": {}
         }
        }
       }
      }
     },
     "400": {
      "description": "There are no receipts to download for that choice"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "tax_years": {
          "type": "array",
          "items": {},
          "description": "The years to include."
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/companies/{companyId}/exports/{exportId}": {
   "get": {
    "tags": [
     "Exports"
    ],
    "summary": "An export's progress",
    "operationId": "get-api-companies-companyid-exports-exportid",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "exportId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "export": {}
         }
        }
       }
      }
     },
     "404": {
      "description": "That download has expired — start a new one"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/companies/{companyId}/exports/{exportId}/download": {
   "get": {
    "tags": [
     "Exports"
    ],
    "summary": "Download an export",
    "operationId": "get-api-companies-companyid-exports-exportid-download",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "exportId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "File, page or redirect"
     },
     "404": {
      "description": "That download has expired — start a new one"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/companies/{companyId}/activity": {
   "get": {
    "tags": [
     "Companies"
    ],
    "summary": "Recent activity",
    "operationId": "get-api-companies-companyid-activity",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "activity": {
           "type": "array",
           "items": {}
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/companies/{companyId}/customers": {
   "get": {
    "tags": [
     "Invoices & customers"
    ],
    "summary": "List customers",
    "operationId": "get-api-companies-companyid-customers",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "archived",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "customers": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "id": {
              "type": "integer"
             },
             "company_id": {
              "type": "integer"
             },
             "name": {
              "type": "string"
             },
             "email": {
              "type": "string",
              "nullable": true
             },
             "phone": {
              "type": "string",
              "nullable": true
             },
             "address": {
              "type": "string",
              "nullable": true
             },
             "cis_rate": {
              "type": "number",
              "nullable": true
             },
             "terms_days": {
              "type": "integer",
              "nullable": true
             },
             "notes": {
              "type": "string",
              "nullable": true
             },
             "created_at": {
              "type": "string",
              "format": "date-time"
             },
             "updated_at": {
              "type": "string",
              "format": "date-time"
             },
             "archived_at": {
              "type": "string",
              "format": "date-time",
              "nullable": true
             },
             "invoices": {
              "type": "boolean"
             },
             "owed": {},
             "last_invoice": {
              "type": "boolean"
             },
             "contacts": {
              "type": "array",
              "items": {}
             }
            }
           }
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "post": {
    "tags": [
     "Invoices & customers"
    ],
    "summary": "Add a customer",
    "operationId": "post-api-companies-companyid-customers",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "201": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "id": {
           "type": "integer"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "contacts": {
          "type": "array",
          "items": {}
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/companies/{companyId}/customers/{id}": {
   "put": {
    "tags": [
     "Invoices & customers"
    ],
    "summary": "Update a customer",
    "operationId": "put-api-companies-companyid-customers-id",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Customer not found"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "name": {
          "type": "string"
         },
         "email": {
          "type": "string"
         },
         "phone": {
          "type": "string"
         },
         "address": {
          "type": "string"
         },
         "notes": {
          "type": "string"
         },
         "cis_rate": {
          "description": "CIS deduction rate for construction customers."
         },
         "terms_days": {
          "type": "string",
          "description": "Payment terms in days."
         },
         "archived": {},
         "contacts": {
          "type": "array",
          "items": {}
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/companies/{companyId}/invoice-settings": {
   "get": {
    "tags": [
     "Invoices & customers"
    ],
    "summary": "Invoice settings",
    "operationId": "get-api-companies-companyid-invoice-settings",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "settings": {
           "type": "array",
           "items": {}
          },
          "email_enabled": {
           "type": "boolean"
          },
          "email_from": {
           "type": "string",
           "nullable": true
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "put": {
    "tags": [
     "Invoices & customers"
    ],
    "summary": "Update invoice settings",
    "operationId": "put-api-companies-companyid-invoice-settings",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "The prefix can only use letters, numbers, - _ /"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "invoice_prefix": {},
         "next_invoice_no": {
          "type": "number"
         },
         "default_terms_days": {
          "type": "number"
         },
         "bank_account_name": {
          "type": "string"
         },
         "bank_sort_code": {},
         "bank_account_no": {},
         "invoice_footer": {
          "type": "string"
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/companies/{companyId}/invoices": {
   "get": {
    "tags": [
     "Invoices & customers"
    ],
    "summary": "List invoices",
    "operationId": "get-api-companies-companyid-invoices",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "status",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "customer_id",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "tax_year",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "q",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "offset",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "invoices": {
           "type": "array",
           "items": {}
          },
          "more": {
           "type": "boolean"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "post": {
    "tags": [
     "Invoices & customers"
    ],
    "summary": "Create an invoice",
    "operationId": "post-api-companies-companyid-invoices",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "201": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "id": {
           "type": "integer"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/companies/{companyId}/invoices/summary": {
   "get": {
    "tags": [
     "Invoices & customers"
    ],
    "summary": "Money owed right now, plus this tax year's invoicing — for Home and Tax year",
    "operationId": "get-api-companies-companyid-invoices-summary",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "tax_year",
      "in": "query",
      "required": false,
      "schema": {}
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "owed": {
           "type": "object",
           "properties": {
            "invoices": {
             "type": "integer"
            },
            "amount": {},
            "overdue_invoices": {
             "type": "number"
            },
            "overdue": {}
           }
          },
          "drafts": {
           "type": "integer"
          },
          "tax_year": {},
          "year": {
           "type": "object",
           "properties": {
            "invoices": {
             "type": "integer"
            },
            "invoiced": {},
            "invoiced_net": {},
            "vat": {},
            "cis": {},
            "received": {}
           }
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/companies/{companyId}/invoices/{id}": {
   "get": {
    "tags": [
     "Invoices & customers"
    ],
    "summary": "Get an invoice",
    "operationId": "get-api-companies-companyid-invoices-id",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "invoice": {},
          "editable": {
           "type": "boolean"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "put": {
    "tags": [
     "Invoices & customers"
    ],
    "summary": "Update an invoice",
    "operationId": "put-api-companies-companyid-invoices-id",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "409": {
      "description": "Imported invoices can't be edited"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "delete": {
    "tags": [
     "Invoices & customers"
    ],
    "summary": "Delete a draft invoice",
    "operationId": "delete-api-companies-companyid-invoices-id",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "409": {
      "description": "Only drafts can be deleted — void a sent invoice instead"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/companies/{companyId}/invoices/{id}/duplicate": {
   "post": {
    "tags": [
     "Invoices & customers"
    ],
    "summary": "Copy an invoice",
    "operationId": "post-api-companies-companyid-invoices-id-duplicate",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "201": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "id": {
           "type": "integer"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/companies/{companyId}/invoices/{id}/void": {
   "post": {
    "tags": [
     "Invoices & customers"
    ],
    "summary": "Void an invoice",
    "operationId": "post-api-companies-companyid-invoices-id-void",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "409": {
      "description": "Delete the draft instead"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/companies/{companyId}/invoices/{id}/send": {
   "post": {
    "tags": [
     "Invoices & customers"
    ],
    "summary": "Send an invoice",
    "operationId": "post-api-companies-companyid-invoices-id-send",
    "description": "Channel 'share' (phone share / download — just records it) or 'email' (sent from here with the PDF attached): { to: [], cc: [], message }\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "number": {}
         }
        }
       }
      }
     },
     "400": {
      "description": "Choose who to send it to"
     },
     "409": {
      "description": "This invoice is void"
     },
     "502": {
      "description": "The email couldn't be sent: …. The invoice is saved as … — try again or use Share."
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "channel": {
          "type": "string",
          "description": "`email` (Bramble emails it) or `share` (you sent it yourself; just records it)."
         },
         "to": {
          "description": "Recipient, with `email`."
         },
         "cc": {
          "description": "Copy recipients."
         },
         "message": {
          "type": "string",
          "description": "The email's message."
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/companies/{companyId}/invoices/{id}/pdf": {
   "get": {
    "tags": [
     "Invoices & customers"
    ],
    "summary": "An invoice as PDF",
    "operationId": "get-api-companies-companyid-invoices-id-pdf",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "download",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "File, page or redirect"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/companies/{companyId}/invoices/{id}/payments": {
   "post": {
    "tags": [
     "Invoices & customers"
    ],
    "summary": "Record a payment",
    "operationId": "post-api-companies-companyid-invoices-id-payments",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "201": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Enter the date it was paid (not in the future)"
     },
     "409": {
      "description": "Send the invoice before recording a payment"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "paid_on": {
          "description": "The date."
         },
         "amount": {
          "description": "How much."
         },
         "method": {
          "type": "string",
          "description": "How it was paid."
         },
         "note": {
          "type": "string"
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/companies/{companyId}/invoices/{id}/payments/{paymentId}": {
   "delete": {
    "tags": [
     "Invoices & customers"
    ],
    "summary": "Remove a payment",
    "operationId": "delete-api-companies-companyid-invoices-id-payments-paymentid",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "paymentId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Payment not found"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/companies/{companyId}/income": {
   "get": {
    "tags": [
     "Income"
    ],
    "summary": "List income",
    "operationId": "get-api-companies-companyid-income",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "tax_year",
      "in": "query",
      "required": false,
      "schema": {}
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "income": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "id": {
              "type": "integer"
             },
             "company_id": {
              "type": "integer"
             },
             "customer_id": {
              "type": "integer",
              "nullable": true
             },
             "payer": {
              "type": "string",
              "nullable": true
             },
             "received_on": {
              "type": "string",
              "format": "date"
             },
             "tax_year": {
              "type": "string"
             },
             "description": {
              "type": "string",
              "nullable": true
             },
             "gross": {
              "type": "number"
             },
             "cis_deducted": {
              "type": "number"
             },
             "vat": {
              "type": "number"
             },
             "net": {
              "type": "number"
             },
             "reference": {
              "type": "string",
              "nullable": true
             },
             "notes": {
              "type": "string",
              "nullable": true
             },
             "created_by": {
              "type": "integer",
              "nullable": true
             },
             "created_at": {
              "type": "string",
              "format": "date-time"
             },
             "updated_at": {
              "type": "string",
              "format": "date-time"
             },
             "deleted_at": {
              "type": "string",
              "format": "date-time",
              "nullable": true
             },
             "customer_name": {
              "type": "string"
             }
            }
           }
          },
          "payers": {
           "type": "array",
           "items": {}
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "post": {
    "tags": [
     "Income"
    ],
    "summary": "Record income",
    "operationId": "post-api-companies-companyid-income",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "201": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "id": {
           "type": "integer"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Unknown customer"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/companies/{companyId}/income/summary": {
   "get": {
    "tags": [
     "Income"
    ],
    "summary": "Income received in a tax year (cash basis): invoice payments + the log",
    "operationId": "get-api-companies-companyid-income-summary",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "tax_year",
      "in": "query",
      "required": false,
      "schema": {}
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "tax_year": {}
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/companies/{companyId}/income/{id}": {
   "put": {
    "tags": [
     "Income"
    ],
    "summary": "Update income",
    "operationId": "put-api-companies-companyid-income-id",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Not found"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "received_on": {
          "type": "string",
          "format": "date"
         },
         "customer_id": {
          "type": "number"
         },
         "payer": {
          "type": "string"
         },
         "description": {
          "type": "string"
         },
         "reference": {
          "type": "string"
         },
         "notes": {
          "type": "string"
         },
         "gross": {
          "type": "array",
          "items": {}
         },
         "cis_deducted": {},
         "vat": {}
        }
       }
      }
     }
    }
   },
   "delete": {
    "tags": [
     "Income"
    ],
    "summary": "Delete income",
    "operationId": "delete-api-companies-companyid-income-id",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Not found"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/companies/{companyId}/tax-return": {
   "get": {
    "tags": [
     "Self Assessment"
    ],
    "summary": "A year's Self Assessment figures",
    "operationId": "get-api-companies-companyid-tax-return",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "tax_year",
      "in": "query",
      "required": false,
      "schema": {}
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "tax_year": {},
          "status": {
           "type": "string"
          },
          "filed_at": {
           "type": "string",
           "format": "date-time"
          },
          "hmrc_reference": {},
          "notes": {
           "type": "array",
           "items": {}
          },
          "use_trading_allowance": {
           "type": "boolean"
          },
          "figures": {
           "type": "array",
           "items": {}
          },
          "changed_since_filing": {},
          "company": {
           "type": "object",
           "properties": {
            "name": {
             "type": "string"
            },
            "utr": {},
            "year_end": {}
           }
          },
          "can_edit": {
           "type": "boolean"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "put": {
    "tags": [
     "Self Assessment"
    ],
    "summary": "Save Self Assessment choices",
    "operationId": "put-api-companies-companyid-tax-return",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Unknown tax year"
     },
     "409": {
      "description": "This return is marked as filed — reopen it first"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "tax_year": {},
         "use_trading_allowance": {
          "description": "Use the £1,000 trading allowance instead of expenses."
         },
         "notes": {
          "type": "string"
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/companies/{companyId}/tax-return/file": {
   "post": {
    "tags": [
     "Self Assessment"
    ],
    "summary": "Mark a year filed",
    "operationId": "post-api-companies-companyid-tax-return-file",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Unknown tax year"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "tax_year": {},
         "hmrc_reference": {
          "type": "string",
          "description": "HMRC's submission reference."
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/companies/{companyId}/tax-return/reopen": {
   "post": {
    "tags": [
     "Self Assessment"
    ],
    "summary": "Reopen a filed year",
    "operationId": "post-api-companies-companyid-tax-return-reopen",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "tax_year": {}
        }
       }
      }
     }
    }
   }
  },
  "/api/companies/{companyId}/tax-return/pdf": {
   "get": {
    "tags": [
     "Self Assessment"
    ],
    "summary": "Self Assessment summary as PDF",
    "operationId": "get-api-companies-companyid-tax-return-pdf",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: SimpleBooks.",
    "parameters": [
     {
      "name": "companyId",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "tax_year",
      "in": "query",
      "required": false,
      "schema": {}
     },
     {
      "name": "download",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "File, page or redirect"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/share-target": {
   "post": {
    "tags": [
     "Share to SimpleBooks"
    ],
    "summary": "\"Share → SimpleBooks\" is normally caught by the service worker; if it isn't running yet, just open the app",
    "operationId": "post-share-target",
    "description": "Requires: None: public, or protected by a token in the address or body.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "File, page or redirect"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/app/simplebooks/version": {
   "get": {
    "tags": [
     "Legacy (SimpleBooks v1)"
    ],
    "summary": "Version (legacy)",
    "operationId": "get-app-simplebooks-version",
    "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`).",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "versions": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "latest_version": {
              "type": "string",
              "nullable": true
             }
            }
           }
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Data not found"
     },
     "500": {
      "description": "Internal Server Error"
     }
    },
    "security": [
     {
      "apiKey": []
     },
     {
      "session": []
     },
     {
      "bearer": []
     }
    ]
   }
  },
  "/app/simplebooks/companies": {
   "get": {
    "tags": [
     "Legacy (SimpleBooks v1)"
    ],
    "summary": "List companies (legacy)",
    "operationId": "get-app-simplebooks-companies",
    "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`).",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "companies": {
           "type": "array",
           "items": {}
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "No companies found for this user"
     },
     "500": {
      "description": "Internal Server Error"
     }
    },
    "security": [
     {
      "apiKey": []
     },
     {
      "session": []
     },
     {
      "bearer": []
     }
    ]
   }
  },
  "/app/simplebooks/companies/has-membership": {
   "get": {
    "tags": [
     "Legacy (SimpleBooks v1)"
    ],
    "summary": "Does the person have a company? (legacy)",
    "operationId": "get-app-simplebooks-companies-has-membership",
    "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`).",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "isMember": {}
         }
        }
       }
      }
     },
     "500": {
      "description": "Internal Server Error"
     }
    },
    "security": [
     {
      "apiKey": []
     },
     {
      "session": []
     },
     {
      "bearer": []
     }
    ]
   }
  },
  "/app/simplebooks/companies/create": {
   "post": {
    "tags": [
     "Legacy (SimpleBooks v1)"
    ],
    "summary": "Create a company (legacy)",
    "operationId": "post-app-simplebooks-companies-create",
    "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`).",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "message": {
           "type": "string"
          },
          "company_id": {
           "type": "integer"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "User not found"
     },
     "500": {
      "description": "Failed to create company"
     }
    },
    "security": [
     {
      "apiKey": []
     },
     {
      "session": []
     },
     {
      "bearer": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "formObject": {}
        }
       }
      }
     }
    }
   }
  },
  "/app/simplebooks/company/receipts": {
   "post": {
    "tags": [
     "Legacy (SimpleBooks v1)"
    ],
    "summary": "Receipts for a month (legacy)",
    "operationId": "post-app-simplebooks-company-receipts",
    "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`).",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "result": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "title": {},
             "amount": {},
             "receipt_date": {
              "type": "string",
              "format": "date",
              "nullable": true
             },
             "category": {},
             "fiscal_year": {},
             "fiscal_month": {},
             "created_at": {
              "type": "string",
              "format": "date-time"
             }
            }
           }
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Missing required parameters"
     },
     "404": {
      "description": "User not found"
     },
     "500": {
      "description": "Internal Server Error"
     }
    },
    "security": [
     {
      "apiKey": []
     },
     {
      "session": []
     },
     {
      "bearer": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "company_id": {
          "type": "integer"
         },
         "fiscal_year": {},
         "fiscal_month": {}
        },
        "required": [
         "company_id",
         "fiscal_year",
         "fiscal_month"
        ]
       }
      }
     }
    }
   }
  },
  "/app/simplebooks/company/receipts/total/year": {
   "post": {
    "tags": [
     "Legacy (SimpleBooks v1)"
    ],
    "summary": "Year total (legacy)",
    "operationId": "post-app-simplebooks-company-receipts-total-year",
    "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`).",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "total": {
           "type": "integer"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Missing required parameters"
     },
     "404": {
      "description": "User not found"
     },
     "500": {
      "description": "Internal Server Error"
     }
    },
    "security": [
     {
      "apiKey": []
     },
     {
      "session": []
     },
     {
      "bearer": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "company_id": {
          "type": "integer"
         },
         "fiscal_year": {}
        },
        "required": [
         "company_id",
         "fiscal_year"
        ]
       }
      }
     }
    }
   }
  },
  "/app/simplebooks/company/receipts/total/month": {
   "post": {
    "tags": [
     "Legacy (SimpleBooks v1)"
    ],
    "summary": "Month total (legacy)",
    "operationId": "post-app-simplebooks-company-receipts-total-month",
    "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`).",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "total": {
           "type": "integer"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Missing required parameters"
     },
     "404": {
      "description": "User not found"
     },
     "500": {
      "description": "Internal Server Error"
     }
    },
    "security": [
     {
      "apiKey": []
     },
     {
      "session": []
     },
     {
      "bearer": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "company_id": {
          "type": "integer"
         },
         "fiscal_year": {},
         "fiscal_month": {}
        },
        "required": [
         "company_id",
         "fiscal_year",
         "fiscal_month"
        ]
       }
      }
     }
    }
   }
  }
 }
}