Hoursmith

Get an expense by ID. Requires a Manager+ token — Member tokens get forbidden_scope.

get_expense

Get an internal bill's frozen lines, dates, grouped display choices, settlement balances, recorded payment references and latest 50 email delivery summaries plus emailDeliveryCount. Previews, bank details and message content are excluded. Attachment links require an Owner/Admin browser session. Sending email does not mean payment. This tool does not generate, send or pay a bill. Read-only. Owner/Admin token with read scope required; Manager/Member tokens cannot access any Payouts data. Studio+ can read finalized history; drafts require Agency. Money values are exact decimal strings. App links require an authenticated Owner/Admin session.

get_team_bill

Get a single invoice by ID. Returns the frozen snapshot — bill-to, line items, totals. Manager+ tokens only.

get_invoice

Get a member by ID. Member tokens may only fetch their own row (anyone else's id returns 404).

get_member

Get details for the organization this token belongs to: name, plan, default currency, invoice prefix, legal name, business contact info. Member tokens receive the identity subset only — invoicePrefix, legalName, taxId, businessEmail, and businessWebsite are omitted for them.

get_organization

Get one payout recipient's private dated rates, credits, and up to 100 active receiving-method labels plus receivingMethodCount by payee ID. No bank details or encrypted data are returned. Use returned userId to correlate general member data. Read-only. Owner/Admin token with read scope required; Manager/Member tokens cannot access any Payouts data. Agency plan required. Money values are exact decimal strings. App links require an authenticated Owner/Admin session.

get_team_payee

Get currency-separated compensation awaiting review, outstanding/overdue balances and recorded payments. Dates filter estimates and payments; outstanding/overdue are current balances. Client/project filters select whole matching bills and payments, not prorated amounts. Read-only. Owner/Admin token with read scope required; Manager/Member tokens cannot access any Payouts data. Agency plan required. Money values are exact decimal strings. App links require an authenticated Owner/Admin session.

get_team_payout_summary

Get a project by ID. Applicable money fields come back as decimal strings; hourlyRate is null unless rateType is HOURLY, so a dormant compatibility rate on FIXED/NON_BILLABLE is never presented as live pricing. For Member tokens money and fixed-fee reconciliation fields are omitted entirely — budgetHours stays.

get_project

Read the currently-running timer for this user (if any). Returns the first running entry or an empty list. This integration cannot start or stop a timer, even with write consent; offer the Hoursmith workspace link instead of requesting broader permission or creating a completed time entry.

get_running_timer

Get a task by ID. Includes its assignee list (`assigneeIds`).

get_task

Read one recorded payment, actual transfer and bill settlement amounts/currencies, bill references and reversal evidence. The tool never sends money or email. Read-only. Owner/Admin token with read scope required; Manager/Member tokens cannot access any Payouts data. Studio+ can read finalized history; drafts require Agency. Money values are exact decimal strings. App links require an authenticated Owner/Admin session.

get_team_payment

Compare configured recipients' compensation with attributed client service revenue, or inspect cash movement. Returns member totals and project details, original-currency amounts, report estimates and missing FX. Page/perPage paginate members; complete filtered totals remain separate. Cash difference is not profit. Read-only. Owner/Admin token with read scope required; Manager/Member tokens cannot access any Payouts data. Agency plan required. Money values are exact decimal strings. App links require an authenticated Owner/Admin session.

get_team_profitability

Get a single time entry by ID.

get_time_entry

List clients in the organization. Returns paginated results — pass `cursor` from a previous response's `pagination.nextCursor` to get the next page. Use `search` for partial-name lookup (e.g. search="Coffee" finds Coffee Coders). Exact country/currency filters accept both a singular value and plural arrays; they merge with duplicates removed. Allowed sort fields: relevance, id, name, createdAt, updatedAt. Prefix with '-' for descending. Default is newest first (-createdAt). Requires a read-scoped Manager+ token — Member tokens get forbidden_scope (Members have no client access in Hoursmith).

list_clients

List expenses. Requires a Manager+ token — Member tokens get forbidden_scope. Filter by client, project, category, date range, amount range, or billable flag. Singular and plural exact filters merge and deduplicate before forwarding. Allowed category values: TRAVEL, MEALS, SOFTWARE, EQUIPMENT, CONTRACTORS, OTHER. Allowed sort fields: relevance, id, expenseDate, amount, createdAt, updatedAt. Default -createdAt.

list_expenses

List internal compensation bills and balances. Use outstandingOnly=true for unpaid and partially paid approved bills, or overdueOnly=true for overdue balances. Dates select overlapping service periods. Deleted drafts/void bills are omitted; direct get preserves historical references. Allowed sort fields: id, number, status, issueDate, dueDate, total, amountPaid, createdAt, updatedAt. Read-only. Owner/Admin token with read scope required; Manager/Member tokens cannot access any Payouts data. Studio+ can read finalized history; drafts require Agency. Money values are exact decimal strings. App links require an authenticated Owner/Admin session.

list_team_bills

List invoices. Read-only in v1 — invoice POST/PATCH/DELETE land in v1.1. Manager+ tokens only (Member tokens get forbidden_scope). **Recipe — find the latest paid invoice for a client by name in one call:** set `clientName` (partial-match on the client's name), `status: "PAID"`, `sort: "-paidAt"`, `limit: 1`. Date ranges accept YYYY-MM-DD or full ISO timestamps; numeric ranges accept decimal-strings to preserve precision. Singular and plural exact filters merge and deduplicate before forwarding. Allowed sort fields: relevance, id, number, status, paymentStatus, issueDate, dueDate, sentAt, paidAt, total, amountPaid, createdAt, updatedAt.

list_invoices

List members of the organization (Owner/Admin/Manager/Member). Member tokens see only their own row. Allowed sort fields: relevance, id, role, createdAt.

list_members

List recipients with a configured hourly compensation rate, including retained removed-member profiles. Returns private dated rate history and available credits. Search matches name/email. Allowed sort fields: id, name, createdAt, updatedAt. Read-only. Owner/Admin token with read scope required; Manager/Member tokens cannot access any Payouts data. Agency plan required. Money values are exact decimal strings. App links require an authenticated Owner/Admin session.

list_team_payees

List projects in the organization. Optionally filter by client (id or name) or status. Member tokens see only projects they've been added to, Singular and plural exact filters merge and deduplicate before forwarding. and money/reconciliation fields (hourlyRate, fixedFeeAmount, fixedFeePriorInvoicedAmount, fixedFeeBillingInitializedAt, budgetAmount) are omitted from their results. Allowed sort fields: relevance, id, name, status, startDate, dueDate, createdAt, updatedAt. Default -createdAt.

list_projects

List tasks. Optionally filter by project, status, priority, assignee, due date, billable, etc. Member tokens see only their assigned projects' tasks. Singular and plural exact filters merge and deduplicate before forwarding. Billability follows the current project model: only HOURLY project tasks can be billable; billable=false also finds legacy rows on FIXED/NON_BILLABLE projects. Allowed sort fields: relevance, id, name, status, priority, startDate, dueDate, endDate, createdAt, updatedAt. Default -createdAt.

list_tasks

Read prior externally recorded team payments and reversals. Dates filter payment dates. Includes actual cash amount/currency and bill-currency settlement allocations, preserving agreed exchange rates. Filter by billId or status RECORDED/REVERSED. Allowed sort fields: id, paidDate, amount, createdAt. Read-only. Owner/Admin token with read scope required; Manager/Member tokens cannot access any Payouts data. Studio+ can read finalized history; drafts require Agency. Money values are exact decimal strings. App links require an authenticated Owner/Admin session.

list_team_payments

List time entries. Filter by project, task, user, date range, billable flag, or set running=true to get the currently-running timer. Singular and plural exact filters merge and deduplicate before forwarding. Billability follows the current project model: only HOURLY project time can be billable; billable=false also finds immutable legacy rows on FIXED/NON_BILLABLE projects. Two different date ranges are available: `entryDate*` is the calendar day an entry is filed under, `startedAt*` is when the work actually began. Member tokens are pinned to their own user. Allowed sort fields: relevance, id, entryDate, startedAt, durationSeconds, createdAt, updatedAt. Default is -createdAt (newest first).

list_time_entries

Find priced, unclaimed time awaiting a compensation bill. Running, deleted, pre-start, unpriced and already-approved time is omitted. Defaults to payable work; nonbillable work remains optional and requires explicit bill selection. Dates filter work dates. For already-approved but unpaid work, use list_team_bills with outstandingOnly=true. Allowed sort fields: id, entryDate, durationSeconds, createdAt. Read-only. Owner/Admin token with read scope required; Manager/Member tokens cannot access any Payouts data. Agency plan required. Money values are exact decimal strings. App links require an authenticated Owner/Admin session.

list_team_unpaid_time

Create a new manual time entry in the selected workspace. Updates project budget totals and may add in-app budget alerts; does not create or send invoices, initiate payments, or start a timer. **Send `durationSeconds` (integer) — that's the canonical shape.** For 8 hours pass `durationSeconds: 28800`; for 90 minutes pass `5400`. (Legacy alternative: `duration` as a string like "1h30m", "1:30", "90m", or "1.5h" — the form path. If you pass both, durationSeconds wins.) To record WHEN the work happened, send `startTime` + `endTime` as "HH:mm" instead of a duration — the duration is then derived from them. Both or neither. `billable` is a real boolean (true/false); FIXED and NON_BILLABLE projects always store false, even when true is requested. Owner/Admin can pass `userId` to log on behalf of a teammate; Manager/Member tokens may only log for themselves. Refuses entries longer than 24 hours.

create_time_entry

Record a new expense against a client (and optionally a project under that client). Requires a write-scoped Manager+ token. `category` is one of: TRAVEL, MEALS, SOFTWARE, EQUIPMENT, CONTRACTORS, OTHER (defaults to OTHER). `description` is REQUIRED. `amount` accepts a number or decimal-string (> 0, up to 2 dp). Currency is NOT accepted — the server snapshots the client's currency.

create_expense

Overwrite the supplied fields of an existing client; omitted fields are left untouched. Requires a write-scoped Manager+ token. Returns the updated client.

update_client

Overwrite the supplied fields of an expense; omitted fields are preserved. Requires a write-scoped Manager+ token. Refuses (409 conflict) if the expense has already been billed on an invoice (billed expenses are locked).

update_expense

Overwrite the supplied fields of a project; omitted fields are preserved. Requires a write-scoped Manager+ token. Use `status` to mark a project COMPLETED or re-ACTIVATE it. Project Decimal fields accept at most 2 decimal places. Omit a field to preserve it; send null for a nullable field to clear it. Converting away from FIXED requires fixedFeeAmount: null. The same coherence rules as create_project apply when you touch the relevant fields.

update_project

Overwrite the supplied fields of a task; omitted fields are preserved. Requires a write-scoped token; Members may only edit tasks assigned to them. Adding another current workspace member as an assignee can send the task name and link through external email or linked Telegram providers, according to that recipient's saved notification preferences. Destinations come from the member's existing profile, not a caller-supplied address. Sent notifications cannot be recalled; unchanged assignees, self-assignment and removals do not send assignment notifications. Same field types as create_task — `billable` is a real boolean and is forced false for FIXED/NON_BILLABLE projects; `estimatedHours` is a number or decimal-string.

update_task

Overwrite the supplied fields of a time entry; omitted fields are preserved. Refuses (409 conflict) if the entry is already on an invoiced bill — invoiced entries are immutable. Same dual-input duration rule as create_time_entry: prefer `durationSeconds`. `startTime`/`endTime` behave as they do on create; omit them to leave the entry's bookends alone, or send null for BOTH to clear them. If the target project is FIXED or NON_BILLABLE, `billable` is always stored as false.

update_time_entry

Resolve the calling token's identity. Use this first to learn what the token can do. Returns `{ orgId, orgName, plan, role, tokenName, scopes[] }` where role is OWNER/ADMIN/MANAGER/MEMBER and scopes is a subset of ["read","write"]. Member tokens additionally return `projectIds` — the projects they can see — so you can avoid trial-and-error 404s.

get_me