Invoices

invoices

List

GET/v1/invoices

List invoices, newest first. A discarded draft is left out unless discarded=true.

Scope

invoices:read

Effect

Read only

MCP tool

list_invoices

Retries

Safe to repeat

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

invoices

Create draft

POST/v1/invoices

Create a DRAFT invoice. Never a send.

Scope

invoices:write

Effect

Writes a draft or record

MCP tool

create_draft_invoice

Retries

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

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

invoices

Get

GET/v1/invoices/{invoiceId}

One invoice with lines and totals.

Scope

invoices:read

Effect

Read only

MCP tool

get_invoice

Retries

Safe to repeat

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

invoices

Update draft

PATCH/v1/invoices/{invoiceId}

Update a DRAFT invoice’s lines, fields and notes.

Scope

invoices:write

Effect

Writes a draft or record

MCP tool

update_draft_invoice

Retries

No Idempotency-Key on this route

curl -X PATCH "https://api.billingmart.com/v1/invoices/{invoiceId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

invoices

Create from job

POST/v1/jobs/{jobId}/invoices

Create a DRAFT invoice from a work record: its client, business and currency, linked to the record, with the answers its type maps onto the invoice’s fields. Never a send.

Scope

invoices:write

Effect

Writes a draft or record

MCP tool

create_invoice_from_job

Retries

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

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

invoices

Set job

POST/v1/invoices/{invoiceId}/job

Link a DRAFT invoice to a work record of the same client, business and currency, move it to another, or unlink it with null. A deposit, progress or retainage invoice stays with its job.

Scope

invoices:write

Effect

Writes a draft or record

MCP tool

set_invoice_job

Retries

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

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

reminders

Draft

POST/v1/invoices/{invoiceId}/reminder-draft

Draft the subject and body of a payment reminder for an open invoice. Text only — nothing is sent; a person sends it or proposes it.

Scope

invoices:write

Effect

Read only

MCP tool

draft_reminder_text

Retries

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

curl -X POST "https://api.billingmart.com/v1/invoices/{invoiceId}/reminder-draft" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

invoices

Add line

POST/v1/invoices/{invoiceId}/lines

Append one line to a draft.

Scope

invoices:write

Effect

Writes a draft or record

MCP tool

add_line_item

Retries

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

curl -X POST "https://api.billingmart.com/v1/invoices/{invoiceId}/lines" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"line":{"unitPrice":{"minorUnits":0,"currency":"USD"}}}'

invoices

Remove line

DELETE/v1/invoices/{invoiceId}/lines/{lineId}

Remove one line from a draft.

Scope

invoices:write

Effect

Writes a draft or record

MCP tool

remove_line_item

Retries

No Idempotency-Key on this route

curl -X DELETE "https://api.billingmart.com/v1/invoices/{invoiceId}/lines/{lineId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

invoices

Add sources

POST/v1/invoices/{invoiceId}/sources

Add chosen unbilled time entries, expenses, mileage or an accepted estimate to a DRAFT: one line per record (an estimate brings all its lines), each record marked billed in the same write. Removing the line later releases the record.

Scope

invoices:write

Effect

Writes a draft or record

MCP tool

add_to_invoice

Retries

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

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

invoices

Pdf

GET/v1/invoices/{invoiceId}/pdf

Render (or reuse) the invoice PDF and return a short-lived signed URL. Needs contacts:read as well: the PDF prints the client’s address and email.

Scope

invoices:read

Effect

Read only

MCP tool

preview_invoice_pdf

Retries

Safe to repeat

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

invoices

Create deposit

POST/v1/invoices/deposit

Draft a deposit invoice for a job: depositBasisPoints of jobRef.total (default from the business’s terms). One per job.

Scope

invoices:write

Effect

Writes a draft or record

MCP tool

create_deposit_invoice

Retries

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

curl -X POST "https://api.billingmart.com/v1/invoices/deposit" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"businessId":"<businessId>","clientId":"<clientId>","jobRef":{"id":"<id>","label":"<label>","total":{"minorUnits":0,"currency":"USD"}}}'

invoices

Create progress

POST/v1/invoices/progress

Draft a progress invoice for a job: earned-to-date (percentCompleteBasisPoints, cumulative) minus what the job already billed, or explicit lines; retainage withheld per retainageBasisPoints.

Scope

invoices:write

Effect

Writes a draft or record

MCP tool

create_progress_invoice

Retries

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

curl -X POST "https://api.billingmart.com/v1/invoices/progress" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"businessId":"<businessId>","clientId":"<clientId>","jobRef":{"id":"<id>","label":"<label>","total":{"minorUnits":0,"currency":"USD"}}}'

invoices

Create retainage release

POST/v1/invoices/retainage-release

Draft the retainage release for a job: exactly what its progress invoices withheld. Once per job.

Scope

invoices:write

Effect

Writes a draft or record

MCP tool

create_retainage_release

Retries

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

curl -X POST "https://api.billingmart.com/v1/invoices/retainage-release" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"businessId":"<businessId>","clientId":"<clientId>","jobRef":{"id":"<id>","label":"<label>","total":{"minorUnits":0,"currency":"USD"}}}'

jobs

List

GET/v1/jobs

Jobs billed in this business, folded from the invoices that carry a jobRef: total, deposit, progress, retainage withheld and released. When work records are on for the workspace and the grant holds jobs:read, each row that has a record also carries a `record` summary (status, type, stage, assignee ids), and records with no invoice yet follow the folded rows. At most `limit` rows a page (default 500, up to 1000); `meta.cursor` is present only when more follow. Each row that has a record also carries `terms`, the word its business uses for records, inside the untrusted-data envelope.

Scope

invoices:read

Effect

Read only

MCP tool

list_jobs

Retries

Safe to repeat

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

jobs

Create

POST/v1/jobs

Create a work record as a draft: it saves with answers missing and writes no invoice. Activating it is a separate step that numbers it and counts one send.

Scope

jobs:write

Effect

Writes a draft or record

MCP tool

create_job

Retries

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

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

jobs

Get

GET/v1/jobs/{jobId}

One work record: its answers, stage, assignee and next action. Without contacts:read, phone and email answers are masked and address and sensitive answers are left out; internal notes are never returned. It also carries `terms`, the singular and plural the workspace calls its work records, inside the untrusted-data envelope, so an assistant can use the same word.

Scope

jobs:read

Effect

Read only

MCP tool

get_job

Retries

Safe to repeat

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

jobs

Update

PATCH/v1/jobs/{jobId}

Change a work record’s label, client, assignee, estimate or answers. `null` clears one. `expectedUpdatedAt` must match the record, or the change is refused with TARGET_CHANGED.

Scope

jobs:write

Effect

Writes a draft or record

MCP tool

update_job

Retries

No Idempotency-Key on this route

curl -X PATCH "https://api.billingmart.com/v1/jobs/{jobId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expectedUpdatedAt":"<expectedUpdatedAt>"}'

jobs

Validate intake

GET/v1/jobs/{jobId}/validate-intake

What a work record would be asked for at a step — draft, activate, complete or bill — with no side effects: `ok`, and one entry per missing or invalid answer (key, code, message). The same list the console and the step itself use. Messages name the type’s questions and come back inside the untrusted-data envelope.

Scope

jobs:read

Effect

Read only

MCP tool

validate_job_intake

Retries

Safe to repeat

curl -X GET "https://api.billingmart.com/v1/jobs/{jobId}/validate-intake" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

jobs

Get overview

GET/v1/jobs/{jobId}/overview

A work record at a glance: its label, number, status, client, estimate and contract total, and the figures folded from the documents that belong to it — what was invoiced, paid and is due, what its bills charge it, its expenses, and the progress-billing state. `linked` counts the documents behind each figure. With `includeSubJobs`, `subJobs` adds this record and its live sub-jobs summed per currency from each record’s own figures: a view, with no net, profit or margin, and the figures above stay this record’s alone. The label and the client name come back inside the untrusted-data envelope.

Scope

jobs:read

Effect

Read only

MCP tool

get_job_overview

Retries

Safe to repeat

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

jobs

Get payables

GET/v1/jobs/{jobId}/payables

What a work record owes its vendors: its share of each bill charged to it (split pro-rata to the allocations), what of that is paid and what is still open, the number of draft bills, and one row per bill. Draft bills are listed but never counted.

Scope

bills:read

Effect

Read only

MCP tool

get_job_payables

Retries

Safe to repeat

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

jobs

List billing

GET/v1/jobs/{jobId}/billing

The invoices and estimates that belong to a work record, as rows: id, number (a draft has none), status, dates and amounts, newest first, at most 200 of each. A discarded draft and a document of another business are left out; bills are `jobs.getPayables`.

Scope

jobs:read

Effect

Read only

MCP tool

list_job_billing

Retries

Safe to repeat

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

jobs

Preview delete

GET/v1/jobs/{jobId}/delete-preview

What deleting a work record made by mistake would do with its documents: each unpaid invoice and open bill that would be voided, each draft that would be discarded and each document that stays (paid or part-paid, written off, sent estimates, bills shared with other records), with a plan hash the delete request must carry. Read only: it changes nothing. Deleting itself is the action request `deleteJob`, which a person approves.

Scope

jobs:read

Effect

Read only

MCP tool

preview_delete_job

Retries

Safe to repeat

curl -X GET "https://api.billingmart.com/v1/jobs/{jobId}/delete-preview" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

jobs

Tree

GET/v1/jobs/{rootJobId}/tree

A work record and every sub-job under it, with the depth and parent of each record, parents before children. Titles come back inside the untrusted-data envelope; answers are not part of a tree row.

Scope

jobs:read

Effect

Read only

MCP tool

get_job_tree

Retries

Safe to repeat

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

jobs

Move

POST/v1/jobs/{jobId}/move

Move a work record, with its sub-jobs, under another record of the same customer and business, or to the top level with null. Numbers already given stay as they are.

Scope

jobs:write

Effect

Writes a draft or record

MCP tool

move_job

Retries

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

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

jobs

Set contract total

POST/v1/jobs/{jobId}/contract-total

Set a work record’s contract total, the basis its deposit and progress invoices are computed from: an amount in the record’s currency, or the total of an estimate linked to the record. Refused with CONTRACT_TOTAL_LOCKED once a live deposit or progress invoice exists.

Scope

jobs:write

Effect

Writes a draft or record

MCP tool

set_job_contract_total

Retries

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

curl -X POST "https://api.billingmart.com/v1/jobs/{jobId}/contract-total" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"contractTotal":{"minorUnits":0,"currency":"USD"}}'

jobs

Set stage

POST/v1/jobs/{jobId}/stage

Move an active work record to another stage of its type. `fromStageId` must be where it is now (TARGET_CHANGED otherwise). A finished stage needs its complete-time answers and required documents and completes the record (MISSING_ANSWER names what is missing; `completeAnyway: true` finishes anyway only where every missing document category allows it); a cancelled stage is refused here.

Scope

jobs:write

Effect

Writes a draft or record

MCP tool

set_job_stage

Retries

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

curl -X POST "https://api.billingmart.com/v1/jobs/{jobId}/stage" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"fromStageId":"<fromStageId>","toStageId":"<toStageId>"}'

jobs

Assign

POST/v1/jobs/{jobId}/assign

Assign a work record to an active member who can see its business, or clear the assignee with null.

Scope

jobs:write

Effect

Writes a draft or record

MCP tool

assign_job

Retries

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

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

jobs

Set next action

POST/v1/jobs/{jobId}/next-action

Set what happens next on a work record, with an optional due date (08:00 in the workspace timezone) or instant. Pass `done: true`, with no text, to mark the current next action finished instead.

Scope

jobs:write

Effect

Writes a draft or record

MCP tool

set_job_next_action

Retries

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

curl -X POST "https://api.billingmart.com/v1/jobs/{jobId}/next-action" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

jobs

Close

POST/v1/jobs/{jobId}/close

Complete a work record: it moves to the type’s finished stage once its complete-time answers and required documents are in. `completeAnyway: true` finishes it anyway only where every missing document category allows it. Open invoices do not block it.

Scope

jobs:write

Effect

Writes a draft or record

MCP tool

close_job

Retries

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

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

jobs

Reopen

POST/v1/jobs/{jobId}/reopen

Reopen a completed work record into the type’s first open stage.

Scope

jobs:write

Effect

Writes a draft or record

MCP tool

reopen_job

Retries

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

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

jobs

Discard

POST/v1/jobs/{jobId}/discard

Discard a draft work record that was never activated. It is hidden from lists, never counted, and an activated record is refused.

Scope

jobs:write

Effect

Writes a draft or record

MCP tool

discard_job

Retries

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

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

jobs

Activity

GET/v1/jobs/{jobId}/activity

The record’s timeline: what changed and who changed it, newest first. Keys and ids, never values.

Scope

jobs:read

Effect

Read only

MCP tool

get_job_activity

Retries

Safe to repeat

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

jobs

Notes

POST/v1/jobs/{jobId}/notes

Add an internal note to a work record. The author is the person behind the connection, never a field of the request. Notes are never returned to a customer or in a webhook.

Scope

jobs:write

Effect

Writes a draft or record

MCP tool

add_job_note

Retries

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

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

jobs

Messages

GET/v1/jobs/{jobId}/messages

The emails and texts kept on a work record, newest first: what was sent, blocked, delivered or failed, and the texts of a conversation linked to it. Subjects and bodies are returned as untrusted data, with any link token redacted.

Scope

jobs:read

Effect

Read only

MCP tool

list_job_messages

Retries

Safe to repeat

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

jobs

Messages

POST/v1/jobs/{jobId}/messages

Ask to email or text the work record’s client about it. Nothing is sent until a person approves the request; once sent, the message is kept on the record. Needs actions:deliver as well.

Scope

jobs:write

Effect

Writes a draft or record

MCP tool

send_job_message

Retries

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

curl -X POST "https://api.billingmart.com/v1/jobs/{jobId}/messages" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"channel":"email","body":"<body>"}'

jobs

Documents

POST/v1/jobs/{jobId}/documents

Start adding a file to a work record: a PNG, JPEG, WebP or PDF. Answers the pending document, a short-lived signed URL to PUT the file to, and the exact headers to send with it. Nothing is attached until jobs.documents.complete checks the file, and a document added this way is never shown to the client. The same createRequestId answers the same document. Refused with PLAN_LIMIT when the record is full.

Scope

jobs:write

Effect

Writes a draft or record

MCP tool

begin_job_document

Retries

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

curl -X POST "https://api.billingmart.com/v1/jobs/{jobId}/documents" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"<fileName>","contentType":"image/png","size":0,"createRequestId":"<createRequestId>"}'

jobs

Documents

GET/v1/jobs/{jobId}/documents

The files attached to a work record, newest first: name (as the person gave it), category, type, size, whether the client may see it, and when it was attached. Pending, failed, expired and removed documents are left out. A file is read through jobs.documents.url.

Scope

jobs:read

Effect

Read only

MCP tool

list_job_documents

Retries

Safe to repeat

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

jobs

Documents

POST/v1/jobs/{jobId}/documents/{docId}/complete

Finish adding a file: the server checks the uploaded object (it exists, it is within the declared and the allowed size, and its first bytes are the declared type) and attaches it, or marks it failed with a code (missing, tooLarge, sizeMismatch, typeMismatch, expired) and deletes it. A retry of an attached document answers it again.

Scope

jobs:write

Effect

Writes a draft or record

MCP tool

complete_job_document

Retries

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

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

jobs

Documents

GET/v1/jobs/{jobId}/documents/{docId}/url

A short-lived signed URL to read one attached file. It is a bearer link: whoever holds it reads the file until it expires. Answers urlUnavailable when no link could be signed. Any other state, or a removed document, is NOT_FOUND.

Scope

jobs:read

Effect

Read only

MCP tool

get_job_document_url

Retries

Safe to repeat

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

jobs

Documents

PATCH/v1/jobs/{jobId}/documents/{docId}

Change an attached file’s category, or hide it from the client. Showing a file to the client, and marking one sensitive, are done by a person in the product.

Scope

jobs:write

Effect

Writes a draft or record

MCP tool

update_job_document

Retries

No Idempotency-Key on this route

curl -X PATCH "https://api.billingmart.com/v1/jobs/{jobId}/documents/{docId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

jobs

Documents

DELETE/v1/jobs/{jobId}/documents/{docId}

Remove a file from a work record. It is hidden at once from every list and from the client; the file itself is deleted later, so a link already handed out can finish.

Scope

jobs:write

Effect

Writes a draft or record

MCP tool

remove_job_document

Retries

No Idempotency-Key on this route

curl -X DELETE "https://api.billingmart.com/v1/jobs/{jobId}/documents/{docId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

jobs

Adjustments

GET/v1/jobs/{jobId}/adjustments

The adjustments of a work record, oldest first: each change's kind, status (draft, issued or void), number (once issued), title, description, signed amount and effective date. The title, the description, the answers and a void reason come back inside the untrusted-data envelope; phone, email, address and sensitive answers are masked or withheld without contacts:read. At most 200.

Scope

jobs:read

Effect

Read only

MCP tool

list_job_adjustments

Retries

Safe to repeat

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

jobs

Adjustments

POST/v1/jobs/{jobId}/adjustments

Draft an adjustment to a work record: one of the kinds its type offers, a title, an optional description, the kind's own answers, a signed amount and an effective date. It is a DRAFT: it has no number, is not counted and changes no total until a person issues it (action issueJobAdjustment). A kind with no amount refuses one; a record that has not started is refused.

Scope

jobs:write

Effect

Writes a draft or record

MCP tool

create_job_adjustment

Retries

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

curl -X POST "https://api.billingmart.com/v1/jobs/{jobId}/adjustments" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"kindId":"<kindId>","title":"<title>","amountDelta":{"minorUnits":0,"currency":"USD"}}'

jobs

Adjustments

GET/v1/jobs/{jobId}/adjustments/{adjustmentId}

One adjustment of a work record, as jobs.adjustments.list returns it. An adjustment of another record, or one that does not exist, is NOT_FOUND.

Scope

jobs:read

Effect

Read only

MCP tool

get_job_adjustment

Retries

Safe to repeat

curl -X GET "https://api.billingmart.com/v1/jobs/{jobId}/adjustments/{adjustmentId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

jobs

Adjustments

PATCH/v1/jobs/{jobId}/adjustments/{adjustmentId}

Change a DRAFT adjustment: send only what changes; null clears the description, the amount, the date or an answer. `expectedUpdatedAt` must be the stamp you read (TARGET_CHANGED otherwise). An issued or void adjustment cannot be edited (NOT_A_DRAFT).

Scope

jobs:write

Effect

Writes a draft or record

MCP tool

update_job_adjustment

Retries

No Idempotency-Key on this route

curl -X PATCH "https://api.billingmart.com/v1/jobs/{jobId}/adjustments/{adjustmentId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expectedUpdatedAt":"<expectedUpdatedAt>"}'

jobs

Adjustments

DELETE/v1/jobs/{jobId}/adjustments/{adjustmentId}

Discard a DRAFT adjustment that was never issued: it is deleted, uses no number and was never counted, and answers as it was. An issued or void adjustment is refused (NOT_A_DRAFT); voiding one is an action a person approves.

Scope

jobs:write

Effect

Writes a draft or record

MCP tool

discard_job_adjustment

Retries

No Idempotency-Key on this route

curl -X DELETE "https://api.billingmart.com/v1/jobs/{jobId}/adjustments/{adjustmentId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

unbilled

Preview

GET/v1/clients/{clientId}/unbilled

The lines and totals a rebill would produce right now for a client: unbilled time, expenses and mileage in the business currency. Nothing is written.

Scope

invoices:read

Effect

Read only

MCP tool

preview_unbilled

Retries

Safe to repeat

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

invoices

Ledger

GET/v1/invoices/{invoiceId}/ledger

The ledger entries behind one invoice: payments, credits, write-offs, refunds and returns, oldest first.

Scope

payments:read

Effect

Read only

MCP tool

list_invoice_ledger

Retries

Safe to repeat

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

invoices

Pay link status

GET/v1/invoices/{invoiceId}/pay-link

The state of an invoice’s public pay link: whether one exists, its expiry, whether it was revoked, when it was first viewed and how often. Never the link itself.

Scope

payments:read

Effect

Read only

MCP tool

get_pay_link_status

Retries

Safe to repeat

curl -X GET "https://api.billingmart.com/v1/invoices/{invoiceId}/pay-link" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

invoices

Discard

POST/v1/invoices/{invoiceId}/discard

Discard a never-numbered DRAFT invoice: it leaves every default list and cannot be sent. Refused once numbered, or while an action on it is pending. The record stays (soft, function-written).

Scope

invoices:write

Effect

Writes a draft or record

MCP tool

discard_draft_invoice

Retries

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

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

invoices

Set dunning paused

POST/v1/invoices/{invoiceId}/dunning

Pause or resume automated reminders for ONE invoice. Reversible both ways; resuming may let a missed step catch up with one reminder at the next daily run.

Scope

invoices:write

Effect

Writes a draft or record

MCP tool

set_invoice_dunning_paused

Retries

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

curl -X POST "https://api.billingmart.com/v1/invoices/{invoiceId}/dunning" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"paused":false}'

reminders

Propose ladder

POST/v1/businesses/{businessId}/dunning-ladder-proposal

Propose a reminder schedule and its text for each group of customers by how they have paid before. Saved as a DRAFT: the reminders that go out do not change until a person publishes it in the console.

Scope

invoices:write

Effect

Writes a draft or record

MCP tool

suggest_dunning_ladders

Retries

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

curl -X POST "https://api.billingmart.com/v1/businesses/{businessId}/dunning-ladder-proposal" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Object

Invoice

An issued or draft invoice. It keeps its own denormalised client block PLUS clientId, so editing a client later cannot rewrite what an invoice was issued for. Money is written only by Cloud Functions; totals here are server-derived and a client-supplied total is never trusted.

Object

PdfPreview

PdfPreview is computed by the server for this request, not a stored document, so no contract describes it. Its fields are the TypeScript type of the same name that the handler returns.

Object

JobSummary

JobSummary is computed by the server for this request, not a stored document, so no contract describes it. Its fields are the TypeScript type of the same name that the handler returns.

Object

Job

A work record: one tow, matter, policy or project from intake to billing, the unit a business tracks work by. FUNCTION-WRITTEN ONLY — the record callables take every actor from the verified token, validate answers against the pinned type revision at each transition, and audit.

Object

JobIntakeValidation

JobIntakeValidation is computed by the server for this request, not a stored document, so no contract describes it. Its fields are the TypeScript type of the same name that the handler returns.

Object

JobOverview

JobOverview is computed by the server for this request, not a stored document, so no contract describes it. Its fields are the TypeScript type of the same name that the handler returns.

Object

JobPayables

JobPayables is computed by the server for this request, not a stored document, so no contract describes it. Its fields are the TypeScript type of the same name that the handler returns.

Object

JobBilling

JobBilling is computed by the server for this request, not a stored document, so no contract describes it. Its fields are the TypeScript type of the same name that the handler returns.

Object

JobDeletePlan

JobDeletePlan is computed by the server for this request, not a stored document, so no contract describes it. Its fields are the TypeScript type of the same name that the handler returns.

Object

JobLogEntry

One line of a work record's own timeline: created, stage moved, assigned, document added, message sent. Readable by the staff who can read the record — `listActivity` is owner and admin only, so the record keeps its own. FUNCTION-WRITTEN ONLY and append-only.

Object

Message

One outbound customer message and its outcome. FUNCTION-WRITTEN ONLY: the delivery function decides whether a message may go — a verified phone with explicit smsConsent, a tenant with SMS enabled — and records what happened, including a refusal.

Object

JobDocument

Metadata of one file attached to a work record: a photo, a signed form, a policy PDF. FUNCTION-WRITTEN ONLY: a function mints the signed upload, checks the file's first bytes against its declared type when the upload is finalised, and is the only reader of `storagePath`.

Object

JobDocumentUrl

JobDocumentUrl is computed by the server for this request, not a stored document, so no contract describes it. Its fields are the TypeScript type of the same name that the handler returns.

Object

JobAdjustment

A change to a work record after it started: a change order, an endorsement. Its kind comes from the record's job type; it is numbered per record when issued, carries a SIGNED amount that adjusts the record's total value basis (the contract total when set, else the estimated value), and may be drafted into an invoice.

Object

UnbilledPreview

UnbilledPreview is computed by the server for this request, not a stored document, so no contract describes it. Its fields are the TypeScript type of the same name that the handler returns.

Object

LedgerEntry

One append-only money movement. NEVER UPDATED, NEVER DELETED — a mistake is corrected by a compensating entry that names the entry it reverses. Written only by Cloud Functions. The ledger is what lets an ACH return arriving days later take an invoice out of `paid` without rewriting history.

Object

PayLinkStatus

PayLinkStatus is computed by the server for this request, not a stored document, so no contract describes it. Its fields are the TypeScript type of the same name that the handler returns.