Search, delete and restore tools
These three tools are shared. search_records is in every toolset. delete_record and restore_record are in each toolset that has a kind of record you may delete or restore, and they take only the kinds of your selected toolsets.
The other tools take ids, never names. Find an id with search_records, or read it from a get_ tool, and never guess one.
Record kinds
delete_record and restore_record take a kind and an id. The kind list a client sees is cut down to the kinds of the selected toolsets that the user’s role may use. A kind it cannot use answers invalid with field: "kind", and the message names the toolset that has it.
| Kind | Toolset | Delete | Restore |
|---|---|---|---|
tracked_time |
My work | For good | No |
note |
My work, Clients | Soft delete | Yes |
beat |
My work, when Beats are on | Soft delete | Yes |
deliverable, task (opportunity rows) |
Sales | For good | No |
budget_phase, budget_deliverable, budget_item, budget_item_resource, budget_item_cost |
Sales (live proposal budgets) and Proposal templates (template budgets) | For good | No |
contact |
Clients | Soft delete. The contact’s links stay | Yes |
contact_link |
Clients | Removes one link for good. The contact stays | No |
proposal_section |
Proposals | For good | No |
custom_field, resource_type, cost_type, rate_card, project_role, booking_type, milestone_type |
Setup | Soft delete | Yes |
rate_card_entry |
Setup, Proposal templates | For good | No |
deliverable_template, project_template, project_template_deliverable, project_status, lead_score, project_template_custom_field |
Templates | Soft delete | Yes |
deliverable_template_task |
Templates | Soft delete, or for good when it was never used | When soft deleted |
deliverable_template_task_resource, deliverable_template_task_cost, project_template_phase |
Templates | For good | No |
proposal_template, proposal_template_rate_card |
Proposal templates | Soft delete | Yes |
quote_section, quote_line |
Proposal templates | For good | No |
quote_note |
Proposal templates | Soft delete | No |
Each call checks the kind, then your API permission (api_delete to delete, api_update to restore), then the role permission for that kind of record, then the record itself. A record you cannot read answers not_found.
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.
search_records
Find records by name, number or address, and get the ids that the other tools need. It also lists reference data, for example members, project statuses, lead scores, cost types, finance accounts, tax rates, the setup records (templates, rate cards, custom fields, roles) and the Beat tags: send kinds with no query. Send query for a text search, kinds (a list) to limit the record types, and the filters project_id, status, date_from, date_to and mine. Example: query “21 Drum St surveying” with kinds [“task”] gives the surveying task, with its deliverable and project as parents. A row with match approximate is only similar to the query, so confirm the record with the user before you use its id in a change. It gives no totals and no reports, and details gives the extra fields of some kinds.
| Title | Search records |
| Toolsets | My work, Sales, Clients, Proposals, Insights, Setup, Templates, Proposal templates |
| Kind | Read only, Idempotent |
| Needs | api_read. Each kind of record also needs the role permission to read it |
| Returns | rows, count, limit, offset, has_more, next |
| Input | Type | Required | Description |
|---|---|---|---|
query |
string | Words of the name, number or address. 200 characters or fewer. | |
kinds |
array of strings | A list of record types, for example [“task”, “project”]. Default: all. member is a staff member (its id is a member_id). proposal is a quote. deliverable and task are parts of a project or an opportunity. beat is a dated email, document, meeting or note on a record. beat_tag is a Beat tag. One of project, opportunity, company, contact, location, invoice, credit_note, cost, purchase_order, proposal, task, deliverable, member, progress_claim, variation, expense_claim, beat, team, project_status, company_status, lead_score, cost_type, finance_account, tax_rate, line_item_code, leave_type, business_overhead, time_credit_type, resource_type, deliverable_template, project_template, proposal_template, custom_field, rate_card, milestone_type, booking_type, project_role, account_role, beat_tag. |
|
project_id |
integer | Only the rows of this project or opportunity: tasks, deliverables, costs, invoices, credit notes, purchase orders, proposals, progress claims, variations, and the Beats of the project and its records. Other kinds give no rows. | |
status |
string | Only rows with this status, as the rows show it. member: active (default) or deleted. project_status, project_template and project_role: opportunity or project. beat: the Beat kind. beat_tag: the facet. Kinds with no status give no rows. | |
date_from |
string | Only rows whose date is on or after this day, yyyy-mm-dd. The date is the start of a project or opportunity, the due date of a task, the end of a deliverable, the issue date of a document, the effective date of a variation, or the day of a beat. Kinds with no date give no rows. | |
date_to |
string | Only rows whose date is on or before this day, yyyy-mm-dd. | |
mine |
boolean | true for the rows of the caller: the tasks assigned to the caller, the projects and opportunities that the caller has a role on, the costs, purchase orders and expense claims of the caller, and the member row of the caller. Other kinds give no rows. Default false. | |
limit |
integer | Maximum rows to return. Default 25, maximum 100. | |
offset |
integer | Number of rows to skip. Default 0, maximum 500. |
delete_record
Delete one record by kind and id, as Drum does: a time entry, a Beat, or an account setup record (a catalog record, a template, or a row of a template), or a row of an opportunity or of a proposal budget, or a section of a proposal document, or a contact or its link to a record, or a note on a record. These kinds are deleted for good, and the result has permanent true: tracked_time, contact_link, deliverable, task, proposal_section, rate_card_entry, deliverable_template_task_resource, deliverable_template_task_cost, project_template_phase, budget_phase, budget_deliverable, budget_item, budget_item_resource, budget_item_cost, quote_section, quote_line. A deliverable_template_task is deleted for good only when no delivery task came from it. restore_record brings back the other kinds, except quote_note. Drum refuses the owner’s billed time and time in a locked week, as the Drum timesheet does, and a deleted entry answers tracked_time_not_found. Ask the user before you delete.
| Title | Delete record |
| Toolsets | My work, Sales, Clients, Proposals, Setup, Templates, Proposal templates |
| Kind | Writes data, Destructive, Idempotent |
| Needs | api_delete, and the permission of the kind (see Record kinds) |
| Returns | kind, id, deleted, permanent, warnings, tracked_time |
| Input | Type | Required | Description |
|---|---|---|---|
kind |
string | Yes | The record type. A document row gives it as record_kind. One of tracked_time, beat, contact, contact_link, note, deliverable, task, proposal_section, custom_field, resource_type, cost_type, rate_card, rate_card_entry, project_role, booking_type, milestone_type, deliverable_template, deliverable_template_task, deliverable_template_task_resource, deliverable_template_task_cost, project_template, project_template_phase, project_template_deliverable, project_status, lead_score, project_template_custom_field, proposal_template, budget_phase, budget_deliverable, budget_item, budget_item_resource, budget_item_cost, quote_section, quote_line, quote_note, proposal_template_rate_card. |
id |
integer | Yes | From search_records, a list_ tool, or the get_ tool of the document. |
restore_record
Restore one deleted account setup record by kind and id, as the View Deleted page of its Drum settings screen does. It does not restore projects, time entries, costs or other work records. A record that was deleted for good cannot come back. A list_ or get_ tool with include_deleted gives the ids of deleted records.
| Title | Restore record |
| Toolsets | My work, Clients, Setup, Templates, Proposal templates |
| Kind | Writes data, Idempotent |
| Needs | api_update, and the permission of the kind (see Record kinds) |
| Returns | kind, id, restored, warnings |
| Input | Type | Required | Description |
|---|---|---|---|
kind |
string | Yes | The kinds that can come back. One of beat, contact, note, custom_field, resource_type, cost_type, rate_card, project_role, booking_type, milestone_type, deliverable_template, deliverable_template_task, project_template, project_template_deliverable, project_status, lead_score, project_template_custom_field, proposal_template, proposal_template_rate_card. |
id |
integer | Yes | From a list_ or get_ tool with include_deleted. |