Search manual taxable documents

Operation ID: searchManualTaxableDocument

Group: Accounting › Tax Documents › Manual Taxable Documents

Open in the interactive reference

POST /tax-documents/manual-taxable-documents/search

Read-only: A read that takes its filters in the body. Changes nothing, and ignores Idempotency-Key.

Searches manual taxable documents, also called ad hoc documents. Each match is the full record, including its lines. Use it to match on customer name, document number, or the text of the title or description.

Parameters

Name In Type Required Description
Api-Version header string · v1 yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.

Request body

Required, application/json: searchManualTaxableDocumentInput.

Field Type Required Description
filters object no Search filters, nested as one object so they map onto the POST body. All are optional and are ANDed; omitting every one of them matches all documents. Omit the whole object to do exactly that.
filters.id string no Exact match on a document's id (a UUID). This is how a single known document is fetched.
filters.taxDocumentNumber string no Exact match on the system-generated tax document number. In the body because a document number must not travel in a URL.
filters.documentNumber string no Exact match on the source document number — the counterparty's own number, or one carried over from an external system. In the body on the same grounds as taxDocumentNumber.
filters.type array<string> no Restrict to documents of any of these kinds. Allowed values: 'outgoingInvoice', 'outgoingCredit', 'incomingInvoice', 'incomingCredit'; an unrecognised value simply matches nothing. An empty array does not constrain.
filters.paymentStatus array<string> no Restrict to documents in any of these settlement statuses. Allowed values: 'paid', 'partiallyPaid', 'unpaid', 'noPaymentNeeded', 'voided', 'applied', 'unapplied', 'partiallyApplied', 'noApplicationNeeded'; an unrecognised value simply matches nothing. An empty array does not constrain.
filters.currency array<string> no Restrict to documents in any of these currencies, as 3-letter ISO 4217 codes. An empty array does not constrain.
filters.title string no Case-insensitive SUBSTRING match on the document title. In the body because free text must never travel in a URL.
filters.description string no Case-insensitive SUBSTRING match on the free-text document description. In the body because free text must never travel in a URL.
filters.paymentTerms string no Case-insensitive SUBSTRING match on the payment terms recorded on the document. In the body because free text must never travel in a URL.
filters.customerId string no Restrict to documents issued to this customer, given as the customer id (a UUID). An id that matches no customer yields an empty page, not an error.
filters.customerName string no Case-insensitive SUBSTRING match on the customer's name. In the body precisely because a counterparty name must never travel in a URL.
filters.customerNumber string no Exact match on the customer's system-generated customer number. In the body on the same grounds as customerName.
filters.entityId string no Restrict to documents belonging to this legal entity, given as the entity id (a UUID). An id that matches no entity yields an empty page, not an error.
filters.entityName string no Case-insensitive SUBSTRING match on the legal entity's name. In the body because it names internal organisational structure.
filters.invoiceDate object no Restrict to documents issued in this date window. Both bounds are calendar dates (YYYY-MM-DD) and are INCLUSIVE; omit either side to leave it open-ended.
filters.invoiceDate.start string no Earliest issue date to include, as a calendar date (YYYY-MM-DD). Inclusive. Omit for no lower bound.
filters.invoiceDate.end string no Latest issue date to include, as a calendar date (YYYY-MM-DD). Inclusive. Omit for no upper bound.
filters.serviceDate object no Restrict to documents whose service date falls in this window. Both bounds are calendar dates (YYYY-MM-DD) and are INCLUSIVE; omit either side to leave it open-ended.
filters.serviceDate.start string no Earliest service date to include, as a calendar date (YYYY-MM-DD). Inclusive. Omit for no lower bound.
filters.serviceDate.end string no Latest service date to include, as a calendar date (YYYY-MM-DD). Inclusive. Omit for no upper bound.
filters.dueDate object no Restrict to documents falling due in this window. Both bounds are calendar dates (YYYY-MM-DD) and are INCLUSIVE; omit either side to leave it open-ended.
filters.dueDate.start string no Earliest due date to include, as a calendar date (YYYY-MM-DD). Inclusive. Omit for no lower bound.
filters.dueDate.end string no Latest due date to include, as a calendar date (YYYY-MM-DD). Inclusive. Omit for no upper bound.
filters.lastModifiedDate object no Restrict to documents changed in this window — the incremental-sync filter. Both bounds are ISO 8601 UTC timestamps (YYYY-MM-DDTHH:mm:ss.sssZ) and are INCLUSIVE; omit either side to leave it open-ended.
filters.lastModifiedDate.start string no Earliest change instant to include, as ISO 8601 UTC (YYYY-MM-DDTHH:mm:ss.sssZ). Inclusive. Omit for no lower bound.
filters.lastModifiedDate.end string no Latest change instant to include, as ISO 8601 UTC (YYYY-MM-DDTHH:mm:ss.sssZ). Inclusive. Omit for no upper bound.
filters.totalAmount object no Restrict by gross document total, in each document's own currency (see the currency filter to pin one). Both bounds are INCLUSIVE; omit either side to leave it open-ended.
filters.totalAmount.min decimal no Smallest gross total to include. Inclusive. Omit for no lower bound.
filters.totalAmount.max decimal no Largest gross total to include. Inclusive. Omit for no upper bound.
filters.totalOpenAmount object no Restrict by remaining open balance, in each document's own currency. Set min to a value just above zero to select the documents still outstanding. Both bounds are INCLUSIVE; omit either side to leave it open-ended.
filters.totalOpenAmount.min decimal no Smallest open balance to include. Inclusive. Omit for no lower bound.
filters.totalOpenAmount.max decimal no Largest open balance to include. Inclusive. Omit for no upper bound.
page object no Pagination controls. Omit for the first page.
page.cursor string no Opaque forward cursor from a previous response's pagination.nextCursor; omit for the first page. Do not construct manually.
page.size number no Maximum number of documents to return. Defaults to 50, capped at 200; the server may return fewer, but never more. 
{
  "filters": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "taxDocumentNumber": "<taxDocumentNumber>",
    "documentNumber": "<documentNumber>",
    "type": [
      "<type>"
    ],
    "paymentStatus": [
      "<paymentStatus>"
    ],
    "currency": [
      "<currency>"
    ],
    "title": "<title>",
    "description": "<description>",
    "paymentTerms": "<paymentTerms>",
    "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "customerName": "<customerName>",
    "customerNumber": "<customerNumber>",
    "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "entityName": "<entityName>",
    "invoiceDate": {
      "start": "<start>",
      "end": "<end>"
    },
    "serviceDate": {
      "start": "<start>",
      "end": "<end>"
    },
    "dueDate": {
      "start": "<start>",
      "end": "<end>"
    },
    "lastModifiedDate": {
      "start": "<start>",
      "end": "<end>"
    },
    "totalAmount": {
      "min": "19.99",
      "max": "19.99"
    },
    "totalOpenAmount": {
      "min": "19.99",
      "max": "19.99"
    }
  },
  "page": {
    "cursor": "<cursor>",
    "size": 0
  }
}

Response

200 Success

Under data (searchManualTaxableDocumentOutput):

Field Type Required Description
items array<object> yes Matching manual taxable documents for this page, newest first. Empty when nothing matches.
items[].id string yes Id of the manual taxable document (a UUID) — the public identifier of this record.
items[].type string no Kind of document. One of 'outgoingInvoice', 'outgoingCredit', 'incomingInvoice', 'incomingCredit'. An outgoingInvoice is a customer-facing invoice whose incoming payment can be matched to a bank deposit.
items[].taxDocumentNumber string no System-generated tax document number, unique per tenant and human-readable. Absent until one has been assigned.
items[].documentNumber string no Document number as it appears on the source document — the counterparty's own number for an incoming document, or the number carried over from an external system. Distinct from taxDocumentNumber, which Everest assigns.
items[].title string no Title of the document, as shown on the record.
items[].description string no Free-text description of the document.
items[].invoiceDate date no Date the document was issued, as a calendar date (YYYY-MM-DD).
items[].serviceDate date no Date the underlying service was provided, as a calendar date (YYYY-MM-DD). Drives the tax point where it differs from the invoice date.
items[].dueDate date no Date payment falls due, as a calendar date (YYYY-MM-DD). Absent when no due date has been set.
items[].currency string no Currency of this document as a 3-letter ISO 4217 code (e.g. USD, EUR, GBP). It governs every amount on the record, on the header and on every line alike.
items[].paymentStatus string no Settlement status of the document. One of 'paid', 'partiallyPaid', 'unpaid', 'noPaymentNeeded', 'voided', 'applied', 'unapplied', 'partiallyApplied', 'noApplicationNeeded'.
items[].paymentTerms string no Payment terms recorded on the document, as free text (e.g. 'Net 30').
items[].totalTaxAmount decimal no Sum of the tax amounts of every line, in the document currency (see currency).
items[].totalAmount decimal no Sum of the total amounts of every line — the gross document total, in the document currency (see currency).
items[].totalAllocatedAmount decimal no Amount already allocated to this document by payments or credits, in the document currency (see currency).
items[].totalOpenAmount decimal no Remaining unallocated balance on this document, in the document currency (see currency). Greater than zero means the document is still open.
items[].hasAttachment boolean no True when the document has at least one attachment. The attachments themselves are not published by this API; document delivery is a separate concern with its own permission.
items[].customerId string no Id of the customer the document is issued to (a UUID). Set on customer-facing documents; absent on vendor or employee ones.
items[].customerName string no Display name of the customer. Personal and counterparty data.
items[].customerNumber string no System-generated customer number of the customer, unique per tenant.
items[].entityId string no Id of the legal entity the document belongs to (a UUID).
items[].entityName string no Name of the legal entity the document belongs to.
items[].lastModifiedDate date-time yes Instant the document record last changed, as ISO 8601 UTC (YYYY-MM-DDTHH:mm:ss.sssZ). Poll on this to sync incrementally rather than re-reading the whole collection.
items[].lines array<object> no Lines of the document, each carrying one taxable position. Empty on a document with no lines. All line amounts are in the document currency (see currency).
items[].lines[].id string yes Id of the document line (a UUID).
items[].lines[].lineNumber string no System-generated line number within the document. Absent until one has been assigned.
items[].lines[].description string no Free-text description of the line item.
items[].lines[].taxableBasis decimal no Basis amount the tax is calculated on, in the document currency (see currency).
items[].lines[].taxAmount decimal no Tax charged on the line, in the document currency (see currency).
items[].lines[].totalAmount decimal no Line total including tax, in the document currency (see currency).
pagination object yes Pagination cursor for this page.
pagination.nextCursor string no Opaque cursor to pass as page.cursor for the next page; absent on the last page (mirrors the list/v1 data-set pagination.nextCursor).
pagination.hasMore boolean yes True when more matches remain beyond this page (mirrors the list/v1 data-set pagination.hasMore). 
{
  "data": {
    "items": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "type": "<type>",
        "taxDocumentNumber": "<taxDocumentNumber>",
        "documentNumber": "<documentNumber>",
        "title": "<title>",
        "description": "<description>",
        "invoiceDate": "2026-01-15",
        "serviceDate": "2026-01-15",
        "dueDate": "2026-01-15",
        "currency": "<currency>",
        "paymentStatus": "<paymentStatus>",
        "paymentTerms": "<paymentTerms>",
        "totalTaxAmount": "19.99",
        "totalAmount": "19.99",
        "totalAllocatedAmount": "19.99",
        "totalOpenAmount": "19.99",
        "hasAttachment": true,
        "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "customerName": "<customerName>",
        "customerNumber": "<customerNumber>",
        "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "entityName": "<entityName>",
        "lastModifiedDate": "2026-01-15T09:30:00.000Z",
        "lines": [
          {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "lineNumber": "<lineNumber>",
            "description": "<description>",
            "taxableBasis": "19.99",
            "taxAmount": "19.99",
            "totalAmount": "19.99"
          }
        ]
      }
    ],
    "pagination": {
      "nextCursor": "<nextCursor>",
      "hasMore": true
    }
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Errors

Code Status
INVALID_DATE 400
INVALID_TIMESTAMP 400

Statuses