Time, expenses, mileage and documents

time

List

GET/v1/time-entries

List time entries, newest first.

Scope

time:read

Effect

Read only

MCP tool

list_time_entries

Retries

Safe to repeat

curl -X GET "https://api.billingmart.com/v1/time-entries" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

time

Create

POST/v1/time-entries

Record time. Minutes are integers — never a decimal of hours.

Scope

time:write

Effect

Writes a draft or record

MCP tool

record_time

Retries

Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

curl -X POST "https://api.billingmart.com/v1/time-entries" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"date":"<date>","minutes":0,"billable":false,"hourlyRate":{"minorUnits":0,"currency":"USD"}}'

expenses

List

GET/v1/expenses

List expenses, newest first.

Scope

expenses:read

Effect

Read only

MCP tool

list_expenses

Retries

Safe to repeat

curl -X GET "https://api.billingmart.com/v1/expenses" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

expenses

Create

POST/v1/expenses

Record an expense.

Scope

expenses:write

Effect

Writes a draft or record

MCP tool

record_expense

Retries

Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

curl -X POST "https://api.billingmart.com/v1/expenses" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"date":"<date>","amount":{"minorUnits":0,"currency":"USD"},"rebillable":false}'

mileage

List

GET/v1/mileage

List mileage entries, newest first.

Scope

mileage:read

Effect

Read only

MCP tool

list_mileage

Retries

Safe to repeat

curl -X GET "https://api.billingmart.com/v1/mileage" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

mileage

Create

POST/v1/mileage

Record a journey. Distance is in thousandths of the unit, as an integer.

Scope

mileage:write

Effect

Writes a draft or record

MCP tool

record_mileage

Retries

Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

curl -X POST "https://api.billingmart.com/v1/mileage" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"date":"<date>","distanceMilli":0,"distanceUnit":"mile","rebillable":false,"ratePerUnit":{"minorUnits":0,"currency":"USD"}}'

time

Update

PATCH/v1/time-entries/{entryId}

Correct an UNBILLED time entry. A billed one is refused; billed and billedInvoiceId are never accepted.

Scope

time:write

Effect

Writes a draft or record

MCP tool

update_time_entry

Retries

No Idempotency-Key on this route

curl -X PATCH "https://api.billingmart.com/v1/time-entries/{entryId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hourlyRate":{"minorUnits":0,"currency":"USD"}}'

time

Start session

POST/v1/time-sessions

Start a timer for the signed-in person (one running at a time). Stopping it records a time entry. A repeated startRequestId answers the same timer.

Scope

time:write

Effect

Writes a draft or record

MCP tool

start_timer

Retries

Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

curl -X POST "https://api.billingmart.com/v1/time-sessions" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"startRequestId":"<startRequestId>"}'

time

List sessions

GET/v1/time-sessions

The signed-in person’s timers and trips: the open ones by default, or stopped ones. Filter by kind to list only timers or only trips.

Scope

time:read

Effect

Read only

MCP tool

list_timers

Retries

Safe to repeat

curl -X GET "https://api.billingmart.com/v1/time-sessions" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

time

Get session

GET/v1/time-sessions/{sessionId}

One of the signed-in person’s timers or trips by id: status, minutes, miles, client and job. Another person’s answers NOT_FOUND.

Scope

time:read

Effect

Read only

MCP tool

get_timer

Retries

Safe to repeat

curl -X GET "https://api.billingmart.com/v1/time-sessions/{sessionId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

time

Pause session

POST/v1/time-sessions/{sessionId}/pause

Pause one of the signed-in person’s timers: the clock stops counting until it is resumed. A second pause answers the first. A trip cannot be paused.

Scope

time:write

Effect

Writes a draft or record

MCP tool

pause_timer

Retries

Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

curl -X POST "https://api.billingmart.com/v1/time-sessions/{sessionId}/pause" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

time

Resume session

POST/v1/time-sessions/{sessionId}/resume

Resume one of the signed-in person’s paused timers. A second resume answers the first.

Scope

time:write

Effect

Writes a draft or record

MCP tool

resume_timer

Retries

Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

curl -X POST "https://api.billingmart.com/v1/time-sessions/{sessionId}/resume" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

time

Stop session

POST/v1/time-sessions/{sessionId}/stop

Stop one of the signed-in person’s timers, including one started on the phone; a minute or more records an unbilled time entry. A second stop answers the first. A mileage trip is refused (INVALID_KIND): it is stopped on the phone.

Scope

time:write

Effect

Writes a draft or record

MCP tool

stop_timer

Retries

Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

curl -X POST "https://api.billingmart.com/v1/time-sessions/{sessionId}/stop" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

time

Stop all sessions

POST/v1/time-sessions/stop-all

Stop every open timer of the signed-in person, one after another; each of a minute or more records its own unbilled time entry. A timer that cannot stop stays open. A trip is not stopped.

Scope

time:write

Effect

Writes a draft or record

MCP tool

stop_all_timers

Retries

Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

curl -X POST "https://api.billingmart.com/v1/time-sessions/stop-all" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

expenses

Update

PATCH/v1/expenses/{expenseId}

Correct an UNBILLED expense. A billed one is refused; billed and billedInvoiceId are never accepted.

Scope

expenses:write

Effect

Writes a draft or record

MCP tool

update_expense

Retries

No Idempotency-Key on this route

curl -X PATCH "https://api.billingmart.com/v1/expenses/{expenseId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":{"minorUnits":0,"currency":"USD"}}'

mileage

Update

PATCH/v1/mileage/{mileageId}

Correct an UNBILLED mileage entry. A billed one is refused; billed and billedInvoiceId are never accepted.

Scope

mileage:write

Effect

Writes a draft or record

MCP tool

update_mileage

Retries

No Idempotency-Key on this route

curl -X PATCH "https://api.billingmart.com/v1/mileage/{mileageId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ratePerUnit":{"minorUnits":0,"currency":"USD"}}'

organizer

Create

POST/v1/organizer

Add a document to the organizer: answers it and a short-lived signed URL to PUT its one file to (a PNG, JPEG, WebP or PDF, at most 5 MiB and 4 pages), with the headers to send. Nothing is read until organize is called. Refused with AI_CONSENT_REQUIRED until the person behind the credential (a connected app user, or the API key creator) has allowed Capture to send documents to Google Gemini in the product; an assistant cannot allow it for them.

Scope

organizer:write

Effect

Writes a draft or record

MCP tool

add_to_organizer

Retries

Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

curl -X POST "https://api.billingmart.com/v1/organizer" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"contentType":"image/png"}'

organizer

List

GET/v1/organizer

Organizer documents, newest first, optionally by status.

Scope

organizer:read

Effect

Read only

MCP tool

list_organizer_documents

Retries

Safe to repeat

curl -X GET "https://api.billingmart.com/v1/organizer" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

organizer

Organize

POST/v1/organizer/{docId}/organize

Ask the model to read an uploaded document. Answers at once with status queued; the result lands on the document. The server refuses a missing file, another type than declared, more than 5 MiB or a PDF of more than 4 pages. Uses AI credits. Refused with AI_CONSENT_REQUIRED if that consent was withdrawn since the document was added.

Scope

organizer:write

Effect

Writes a draft or record

MCP tool

organize_document

Retries

Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

curl -X POST "https://api.billingmart.com/v1/organizer/{docId}/organize" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

organizer

Get

GET/v1/organizer/{docId}

One organizer document: its status, what the model read (a proposal, never a stored value) and the server's candidates. Candidates of a kind appear only with that kind's read scope.

Scope

organizer:read

Effect

Read only

MCP tool

get_organizer_document

Retries

Safe to repeat

curl -X GET "https://api.billingmart.com/v1/organizer/{docId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

organizer

Confirm

POST/v1/organizer/{docId}/confirm

File a document as a DRAFT invoice, estimate, job invoice, expense or bill, through the same cores as the console. The kind, every id and the amount are the caller's: candidates are never applied by themselves, the stored amount is the one submitted, and lines that do not add up to it are refused. Needs the kind's own write scope and plan feature. Never sends.

Scope

organizer:write

Effect

Writes a draft or record

MCP tool

file_organizer_document

Retries

Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

curl -X POST "https://api.billingmart.com/v1/organizer/{docId}/confirm" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"kind":"invoice","amount":{"minorUnits":0,"currency":"USD"}}'

organizer

Discard

POST/v1/organizer/{docId}/discard

Remove an organizer document that was not filed, and its file. A filed one is kept.

Scope

organizer:write

Effect

Writes a draft or record

MCP tool

discard_organizer_document

Retries

Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

curl -X POST "https://api.billingmart.com/v1/organizer/{docId}/discard" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

imports

Create

POST/v1/imports

Read a CSV (at most 256 KB, sent as text) of clients, items, open invoices or bills — a QuickBooks or FreshBooks export is recognised — and dry-run it with a mapping: yours, or the one a recognised layout fixes. Answers the import with counts and the first problems by line. Nothing is written to clients, items or invoices; a person runs the write in the console. Without a mapping and in an unknown layout it answers a SUGGESTED mapping (status mapping) for you to confirm by sending it back. Items and invoices also need invoices:write; bills need bills:write and land as drafts.

Scope

clients:write

Effect

Writes a draft or record

MCP tool

import_csv_dry_run

Retries

Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

curl -X POST "https://api.billingmart.com/v1/imports" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"entity":"client","csv":"<csv>"}'

imports

Get

GET/v1/imports/{importId}

One import: its status, the mapping, the dry-run counts, the first problems by line and, once a person has run it, its progress. The file name, headers and column names are untrusted.

Scope

clients:read

Effect

Read only

MCP tool

get_import

Retries

Safe to repeat

curl -X GET "https://api.billingmart.com/v1/imports/{importId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

imports

Discard

DELETE/v1/imports/{importId}

Discard an import that is not being written, and its uploaded file. What a finished import already created stays. A connection can discard only an import it created itself.

Scope

clients:write

Effect

Writes a draft or record

MCP tool

discard_import

Retries

No Idempotency-Key on this route

curl -X DELETE "https://api.billingmart.com/v1/imports/{importId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

Object

TimeEntry

Billable time. Minutes are an integer count, never a decimal of hours: 1.5 hours entered as a float and multiplied by a minor-unit rate is the same rounding bug as a float amount, one step removed.

Object

Expense

A cost incurred, optionally rebilled to a client with a markup. Markup is basis points, not a float multiplier.

Object

Mileage

A trip, optionally rebilled. Distance is an integer count of thousandths of the declared unit — 12.4 miles is 12400 — for the same reason quantities and amounts are integers. A float distance times a minor-unit rate is a rounding bug with a delivery date.

Object

FieldSession

One stretch of field work tracked from a phone — a running timer or a GPS trip — from Start to Stop. The phone sends points and photos; every number here is derived by the SERVER: the minutes from its own clock, the distance from the filtered points.

Object

OrganizerDoc

One document the organizer is reading or has read: a photo or file a person added, what the model read on it, and the server's candidates for where it belongs.

Object

Import

One file a person (or an API client) is bringing clients, items or open invoices in from: which file, how its columns are mapped, what a dry run found, and how far the write has got. FUNCTION-WRITTEN ONLY: create, update and delete are `if false` for clients, and staff read is the only client access.