All API resources
API reference

Invoices

Finalised invoices: create, read and list them.

Base URL https://app.prosaic.works/api/public/v1. Every request needs an API key or access token; see the overview.

List invoices

GET/api/public/v1/invoices

SDK: prosaic.invoices.list(params)

Returns invoices in the active workspace that the authenticated user can access. Results are paginated and can be narrowed by client or entity. When both filters are supplied, an invoice must match both.

Query parameters

  • entityIdstring

    Return invoices for one entity.

  • clientIdstring

    Return invoices whose entity is associated with this client user.

  • statusstring

    Filter by persisted invoice lifecycle status.

    One of: DRAFT, FINALISED, PAID, VOIDED

  • updatedSincestring

    Return invoices updated on or after this ISO 8601 timestamp.

  • pageinteger

    Default: 1

  • pageSizeinteger

    Default: 20

Responses

200 Successful response

  • dataarray of objectsrequired
    Show 23 child attributes
    • idstringrequired
    • entityIdstringrequired
    • workspaceIdstringrequired
    • fileIdstringrequirednullable
    • invoiceNumberstringrequirednullable
    • statusstringrequired
    • taxModestringrequired
    • issueDatestring (date-time)required
    • dueDatestring (date-time)requirednullable
    • sentAtstring (date-time)requirednullable
    • recipientNamestringrequired
    • recipientEmailstringrequirednullable
    • recipientAddressstringrequirednullable
    • bankAccountIdstringrequirednullable
    • bankAccountNamestringrequirednullable
    • subtotalnumberrequired
    • taxTotalnumberrequired
    • totalnumberrequired
    • amountDuenumberrequirednullable
    • notesstringrequirednullable
    • createdAtstring (date-time)required
    • updatedAtstring (date-time)required
    • linesarray of objectsrequired
      Show 10 child attributes
      • idstringrequired
      • descriptionstringrequired
      • quantitynumberrequired
      • unitPricenumberrequired
      • taxRatenumberrequired
      • taxRateCodestringrequirednullable
      • entityAccountIdstringrequirednullable
      • amountnumberrequired
      • taxAmountnumberrequired
      • positionnumberrequired
  • paginationobjectrequired
    Show 6 child attributes
    • currentPagenumberrequired
    • pageSizenumberrequired
    • totalCountnumberrequired
    • totalPagesnumberrequired
    • hasNextPagebooleanrequired
    • hasPreviousPagebooleanrequired
  • 400 Invalid query parameters.
  • 401 Unauthorized.
  • 403 Insufficient role.
  • 404 Workspace not found.
  • 500 Internal server error.
Node SDK
const page = await prosaic.invoices.list();
curl
curl https://app.prosaic.works/api/public/v1/invoices \
  -H "Authorization: Bearer $PROSAIC_API_KEY"

Get an invoice by ID for an entity

GET/api/public/v1/entities/{entityId}/invoices/{invoiceId}

SDK: prosaic.invoices.retrieve(entityId, invoiceId)

Path parameters

  • entityIdstringrequired
  • invoiceIdstringrequired

Responses

200 Successful response

  • dataobjectrequired
    Show 23 child attributes
    • idstringrequired
    • entityIdstringrequired
    • workspaceIdstringrequired
    • fileIdstringrequirednullable
    • invoiceNumberstringrequirednullable
    • statusstringrequired
    • taxModestringrequired
    • issueDatestring (date-time)required
    • dueDatestring (date-time)requirednullable
    • sentAtstring (date-time)requirednullable
    • recipientNamestringrequired
    • recipientEmailstringrequirednullable
    • recipientAddressstringrequirednullable
    • bankAccountIdstringrequirednullable
    • bankAccountNamestringrequirednullable
    • subtotalnumberrequired
    • taxTotalnumberrequired
    • totalnumberrequired
    • amountDuenumberrequirednullable
    • notesstringrequirednullable
    • createdAtstring (date-time)required
    • updatedAtstring (date-time)required
    • linesarray of objectsrequired
      Show 10 child attributes
      • idstringrequired
      • descriptionstringrequired
      • quantitynumberrequired
      • unitPricenumberrequired
      • taxRatenumberrequired
      • taxRateCodestringrequirednullable
      • entityAccountIdstringrequirednullable
      • amountnumberrequired
      • taxAmountnumberrequired
      • positionnumberrequired
  • 400 Invalid invoice ID.
  • 401 Unauthorized.
  • 404 Invoice, entity, or workspace not found.
  • 500 Internal server error.
Node SDK
const { data } = await prosaic.invoices.retrieve(entityId, invoiceId);
curl
curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/invoices/$INVOICE_ID \
  -H "Authorization: Bearer $PROSAIC_API_KEY"

Create a finalised invoice

POST/api/public/v1/entities/{entityId}/invoices

SDK: prosaic.invoices.create(entityId, params)

Creates a complete, finalised invoice for the specified entity. The entity is taken from the URL; status cannot be supplied. Finalised invoices are not automatically delivered to the recipient.

Where the workspace records invoices as receivables (accrual accounting), finalising posts the invoice to the ledger, which needs a contactId. Without one the request is refused with 409 INVOICE_NOT_EDITABLE and nothing is created.

Path parameters

  • entityIdstringrequired

Request body

application/json

  • taxModestringrequired

    One of: NO_TAX, TAX_INCLUSIVE, TAX_EXCLUSIVE

  • issueDatestringrequired
  • recipientNamestringrequired
  • linesarray of objectsrequired
    Show 6 child attributes
    • descriptionstringrequired
    • quantitystringrequired
    • unitPricestringrequired
    • taxRateCodestringrequired
    • entityAccountIdstringrequired
    • taxRatestring
  • bankAccountIdstringnullable
  • notesstringnullable
  • contactIdstringnullable
  • dueDatestringnullable
  • bankAccountNamestringnullable
  • invoiceNumberstring
  • recipientEmailstringnullable
  • recipientAddressstringnullable
  • recipientEmailsarray of strings

Responses

201 Successful response

  • dataobjectrequired
    Show 23 child attributes
    • idstringrequired
    • entityIdstringrequired
    • workspaceIdstringrequired
    • fileIdstringrequirednullable
    • invoiceNumberstringrequirednullable
    • statusstringrequired
    • taxModestringrequired
    • issueDatestring (date-time)required
    • dueDatestring (date-time)requirednullable
    • sentAtstring (date-time)requirednullable
    • recipientNamestringrequired
    • recipientEmailstringrequirednullable
    • recipientAddressstringrequirednullable
    • bankAccountIdstringrequirednullable
    • bankAccountNamestringrequirednullable
    • subtotalnumberrequired
    • taxTotalnumberrequired
    • totalnumberrequired
    • amountDuenumberrequirednullable
    • notesstringrequirednullable
    • createdAtstring (date-time)required
    • updatedAtstring (date-time)required
    • linesarray of objectsrequired
      Show 10 child attributes
      • idstringrequired
      • descriptionstringrequired
      • quantitynumberrequired
      • unitPricenumberrequired
      • taxRatenumberrequired
      • taxRateCodestringrequirednullable
      • entityAccountIdstringrequirednullable
      • amountnumberrequired
      • taxAmountnumberrequired
      • positionnumberrequired
  • 400 Invalid request or invoice input, or system account setup is missing or invalid (SYSTEM_ACCOUNT_VALIDATION).
  • 401 Unauthorized.
  • 404 Entity or workspace not found.
  • 409 The invoice can't be finalised, for example it has no contact where the workspace uses accrual accounting.
  • 500 Invoice creation failed.
Node SDK
const { data } = await prosaic.invoices.create(entityId, {
  taxMode: 'NO_TAX',
  issueDate: '2026-04-01',
  recipientName: 'Example Ltd',
  lines: [
    {
      description: 'Office supplies',
      quantity: '1',
      unitPrice: '100.00',
      taxRateCode: 'TAX_RATE_CODE',
      entityAccountId: 'ENTITY_ACCOUNT_ID',
    },
  ],
});
curl
curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/invoices \
  -H "Authorization: Bearer $PROSAIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taxMode": "NO_TAX",
    "issueDate": "2026-04-01",
    "recipientName": "Example Ltd",
    "lines": [
      {
        "description": "Office supplies",
        "quantity": "1",
        "unitPrice": "100.00",
        "taxRateCode": "TAX_RATE_CODE",
        "entityAccountId": "ENTITY_ACCOUNT_ID"
      }
    ]
  }'