Reference

Finance API.

Create and read invoices, subscriptions, and payments, and link them to a company, deal, or contact.

Finance records track money: invoices, subscriptions, and payments. Records that come from Stripe keep their original currency and status and cannot be created through this API. Use these endpoints for records you add by hand. Every path below starts with /rest. Send the x-api-key header on each request. See the API overview for sign-in.

Endpoints

Method	Path	Purpose
`POST`	`/rest/finance/search`	List and filter finance records.
`GET`	`/rest/finance/{id}`	Read one finance record.
`GET`	`/rest/finance/company/{companyId}/income`	Read a company’s income summary.
`POST`	`/rest/finance`	Create a finance record.
`PATCH`	`/rest/finance/{id}`	Update a finance record.
`PATCH`	`/rest/finance/{id}/deal`	Link a finance record to a deal.
`POST`	`/rest/finance/archive`	Archive or restore finance records.

Create a finance record

A manual finance record needs kind, name, companyId, amountCents, currency, and status. companyId is required for records you create by hand.

Field	Meaning
`kind`	`INVOICE`, `SUBSCRIPTION`, or `PAYMENT`.
`status`	Must match `kind`. See the status values below.
`amountCents`	An integer amount in the smallest currency unit, zero or more.
`currency`	A three-letter currency code that Mosaik supports.
`billingInterval`	Required for `SUBSCRIPTION`, and only for `SUBSCRIPTION`: `MONTHLY`, `QUARTERLY`, or `ANNUAL`.
`dealId`, `contactId`	Optional links to an existing deal or contact.
`reference`	An optional free-text reference, such as an invoice number.
`dueDate`	Optional, `YYYY-MM-DD`.
`notes`	Optional free text.

Status values by kind:

INVOICE: DRAFT, OPEN, PAID, VOID, UNCOLLECTIBLE.
SUBSCRIPTION: ACTIVE, TRIALING, PAST_DUE, CANCELED, INCOMPLETE, INCOMPLETE_EXPIRED, UNPAID, PAUSED.
PAYMENT: PAID, PROCESSING, REQUIRES_PAYMENT_METHOD, REQUIRES_CONFIRMATION, REQUIRES_ACTION, REQUIRES_CAPTURE, CANCELED.

Shell

curl https://<your-portal>.example.com/rest/finance \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "INVOICE",
    "name": "March services",
    "companyId": "<company-id>",
    "amountCents": 450000,
    "currency": "USD",
    "status": "OPEN",
    "dueDate": "2027-03-31"
  }'

TypeScript

const response = await fetch("https://<your-portal>.example.com/rest/finance", {
  method: "POST",
  headers: {
    "x-api-key": "<your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    kind: "INVOICE",
    name: "March services",
    companyId: "<company-id>",
    amountCents: 450000,
    currency: "USD",
    status: "OPEN",
    dueDate: "2027-03-31",
  }),
});

const record = await response.json();

Read a company’s income

GET /rest/finance/company/{companyId}/income returns the income summary Mosaik shows on a company record.

Shell

curl https://<your-portal>.example.com/rest/finance/company/<company-id>/income \
  -H "x-api-key: <your-api-key>"

Archive and restore

POST /rest/finance/archive archives or restores one or more finance records. The API reference shows the exact body shape.