Insights tools
Insights gives an assistant the firm’s reports: the business overview, revenue, and accounts receivable. It is read only.
The toolset also has search_records, and list_projects and get_project. The three report tools are also in Sales.
Each report needs the same insights permission as its screen in Drum.
Tools
Each tool below shows what the server sends: its description (written for the AI), its kind, the permissions it needs, the fields it returns, and its inputs. An input in a.b or a[].b form is a field inside an object or a list. For the shared rules on results, pages, money and errors, see Results, errors and limits.
get_overview_report
Read the financial overview of one month for the account. It gives net revenue, credit notes, expenses, and what is unpaid now on outstanding and overdue invoices. The default is the current month. Use get_revenue_report for a date range, and get_receivables_report for the invoices one by one.
| Title | Get overview report |
| Toolsets | Sales, Insights |
| Kind | Read only, Idempotent |
| Needs | api_read, and access to business insights |
| Returns | month, monthly_revenue, monthly_credit_notes, monthly_expenses, outstanding_invoices, overdue_invoices |
| Input | Type | Required | Description |
|---|---|---|---|
date |
string | A day in the month to report, yyyy-mm-dd. Default: today. |
get_revenue_report
Read the invoiced revenue of a date range. Revenue is invoices less credit notes by issued date, excluding tax, as on the Insights dashboard. It gives the total, the total for each project type, and the five projects with the most revenue. The default is the current month. Use get_receivables_report for the invoices one by one.
| Title | Get revenue report |
| Toolsets | Sales, Insights |
| Kind | Read only, Idempotent |
| Needs | api_read, and access to business insights |
| Returns | start_date, end_date, total, per_project_type, top_projects |
| Input | Type | Required | Description |
|---|---|---|---|
start_date |
string | First day, yyyy-mm-dd. Default: the first day of the current month. | |
end_date |
string | Last day, yyyy-mm-dd. Default: the last day of the current month. |
get_receivables_report
Read the accounts receivable report, with the invoices and credit notes of the account, newest issue date first, and the report totals. A row has the client, project, due date, status, and the amounts without and with tax. A credit note has negative amounts. Filter with an issue date range, project_id, client_id, status or overdue_only. Send response_format detailed for the issue date, reference and original invoice number.
| Title | Get receivables report |
| Toolsets | Sales, Insights |
| Kind | Read only, Idempotent |
| Needs | api_read, and access to accounts receivable insights |
| Returns | rows, total_count, totals, count, limit, offset, has_more |
| Input | Type | Required | Description |
|---|---|---|---|
start_date |
string | Only records issued on or after this day, yyyy-mm-dd. | |
end_date |
string | Only records issued on or before this day, yyyy-mm-dd. | |
project_id |
integer | Only records of this project. From search_records. | |
client_id |
integer | Only records of this client company. From search_records with kinds company. | |
status |
string | Only invoices with this status. One of draft, awaiting_approval, approved. |
|
overdue_only |
boolean | Only overdue invoices, with no credit notes. Default false. | |
response_format |
string | concise (default) or detailed. One of concise, detailed. |
|
limit |
integer | Maximum rows to return. Default 25, maximum 100 (25 for detailed). | |
offset |
integer | Number of rows to skip. Default 0. |