Search purchase orders

Operation ID: searchPurchaseOrder

Group: Accounting › Purchase Orders

Open in the interactive reference

POST /accounting/purchase-orders/search

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

Searches purchase orders. Each match is the full order with its lines. The vendorId, vendorName, entityId, and entityName filters are available here and not on GET accounting/purchase-orders.

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: searchPurchaseOrderInput.

Field Type Required Description
filters object no The filters to apply. A purchase order must match every filter you send. Omit to return all purchase orders. Example: {"approvalStatus":"pendingApproval"}.
filters.id string no Limits results to the purchase order with this identifier. GET accounting/purchase-orders/:id does the same more cheaply.
filters.poNumber string no Limits results to the purchase order with this number, for example 'PO-3'. The match is exact.
filters.externalPONumber string no Limits results to purchase orders with this external reference. The match is exact. It is not unique, so it can match several orders.
filters.approvalStatus string no Limits results to orders in this approval status. Accepted values: 'approved', 'pendingApproval', 'rejected'. Any other value matches no purchase order.
filters.budgetStatus string no Limits results to orders in this budget-check status. Accepted values: 'approved', 'rejected', 'pendingApproval'. Any other value matches no purchase order.
filters.currency string no Limits results to orders denominated in this currency. Format ISO 4217, for example 'USD'.
filters.paymentTerms string no Limits results to orders with this payment-terms code, for example 'net30'. The match is exact.
filters.vendorId string no Limits results to orders placed with this vendor. See id on GET accounting/vendors/:id. An id that matches no vendor returns an empty page, not an error.
filters.entityId string no Limits results to orders placed by this legal entity. See id on GET base/entities. An id that matches no entity returns an empty page, not an error.
filters.vendorName string no Limits results to orders whose vendor name is exactly this. The match is case-sensitive. Use vendorId when you already have the id.
filters.entityName string no Limits results to orders whose legal entity name is exactly this. The match is case-sensitive. Use entityId when you already have the id.
page object no Pagination controls. Omit for the first page. Example: {"size":50}.
page.cursor string no The cursor from the previous response's pagination.nextCursor. Omit on the first request.
page.size number no The number of purchase orders per page, between 1 and 200. Defaults to 50. A value above 200 is treated as 200, not rejected. 
{
  "filters": {
    "approvalStatus": "pendingApproval"
  },
  "page": {
    "size": 50
  }
}

Response

200 Success

Under data (searchPurchaseOrderOutput):

Field Type Required Description
items array<object> yes The purchase orders on this page, most recently created first. An empty array when nothing matches.
items[].id string yes The unique identifier for the purchase order.
items[].poNumber string no The purchase order number, for example 'PO-3'. Absent while none has been assigned.
items[].description string no The description of the order, shown to the vendor.
items[].internalDescription string no Internal notes on the order, not shown to the vendor.
items[].externalMemo string no A memo intended for the vendor.
items[].externalPONumber string no The order reference in the vendor's or an upstream system. It is not unique.
items[].approvalStatus string no The approval status of the order. Possible values: 'approved', 'pendingApproval', 'rejected'.
items[].budgetStatus string no The budget-check status of the order. Possible values: 'approved', 'rejected', 'pendingApproval'. Independent of approvalStatus.
items[].status string no The order lifecycle status. Possible values: 'open', 'inprogress', 'closed', 'overMatched'. This is not the vendor-bill matching status, which is per line in each line's matchStatus.
items[].currency string no The currency the order is denominated in. Format ISO 4217, for example 'USD'. Governs every amount on the order and its lines.
items[].totalAmount decimal no The total ordered amount, the sum of the line totals, in the order currency.
items[].invoicedTotalAmount decimal no The portion of the order already invoiced by vendor bills, in the order currency.
items[].receivedTotalAmount decimal no The portion of the order already received as goods, in the order currency.
items[].startDate date no The first day of the period the order covers. Format YYYY-MM-DD.
items[].endDate date no The last day of the period the order covers. Format YYYY-MM-DD.
items[].needByDate date no The date the goods or services are needed by. Format YYYY-MM-DD.
items[].paymentTerms string no The payment-terms code applied to this order, for example 'net30', 'net60', 'dueOnReceipt' or 'custom'. Inherited from the vendor unless overridden.
items[].hasInventoryItems boolean no Whether any line references an inventory item.
items[].vendorId string no The vendor this order is placed with. See id on GET accounting/vendors/:id.
items[].vendorName string no The name of the vendor this order is placed with.
items[].vendorContactEmail string no The main contact email at the vendor.
items[].entityId string no The legal entity this order is placed by. See id on GET base/entities.
items[].entityName string no The name of the legal entity this order is placed by.
items[].lastModifiedDate date-time yes The date and time the purchase order last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
items[].lines array<object> no The order line items, in their order on the order. An empty array when the order has none.
items[].lines[].id string yes The unique identifier for the line item.
items[].lines[].lineNumber string no The line number, for example 'POL-3'.
items[].lines[].description string no A description of the line item.
items[].lines[].isItem boolean no Whether the line is an item line. True when the line references an item, false when it is an expense line.
items[].lines[].quantity decimal no The quantity ordered, as a decimal.
items[].lines[].price decimal no The unit price, in the order currency. Set on item lines. On an expense line the amount is in editableAmount instead.
items[].lines[].editableAmount decimal no The directly entered line amount, in the order currency. Used on expense lines, where there is no unit price to multiply.
items[].lines[].total decimal no The line total, in the order currency: price times quantity on an item line, editableAmount on an expense line.
items[].lines[].discountPercentage decimal no The discount applied to the line, as a percentage. 10 means 10%, not 0.10.
items[].lines[].currency string no The currency of the line. Format ISO 4217, for example 'USD'. It always matches the order currency.
items[].lines[].status string no The delivery status of the line. Possible values: 'undelivered', 'delivering', 'delivered'.
items[].lines[].matchStatus string no The vendor-bill matching status of the line. Possible values: 'unmatched', 'partiallyMatched', 'matched', 'overMatched'.
items[].lines[].invoicedStatus string no The invoicing status of the line. Possible values: 'uninvoiced', 'partiallyInvoiced', 'invoiced', 'overInvoiced'.
items[].lines[].receivedStatus string no The goods-receipt status of the line. Possible values: 'unreceived', 'partiallyReceived', 'received', 'overReceived'.
items[].lines[].invoicedQuantity decimal no The quantity invoiced against this line so far, as a decimal.
items[].lines[].invoicedAmount decimal no The amount invoiced against this line so far, in the order currency.
items[].lines[].receivedQuantity decimal no The quantity received against this line so far, as a decimal.
items[].lines[].receivedAmount decimal no The amount received against this line so far, in the order currency.
items[].lines[].remainingAmount decimal no The amount still open on this line, in the order currency: the line total less what has been invoiced.
items[].lines[].startDate date no The first day of the period this line covers. Format YYYY-MM-DD.
items[].lines[].endDate date no The last day of the period this line covers. Format YYYY-MM-DD.
items[].lines[].deliveryDate date no The date this line was delivered. Format YYYY-MM-DD.
items[].lines[].estimatedDeliveryDate date no The expected delivery date for this line. Format YYYY-MM-DD.
items[].lines[].unitOfMeasure string no The name of the unit of measure for the quantity.
items[].lines[].unitOfMeasureId string no The unit of measure for the quantity.
items[].lines[].itemId string no The item this line orders. Present on item lines.
items[].lines[].departmentId string no The department this line is charged to. See id on GET people/departments/:id.
pagination object yes The pagination details for this page.
pagination.nextCursor string no The cursor for the next page. Pass it as page.cursor. Absent on the last page.
pagination.hasMore boolean yes Whether more matches remain beyond this page. 
{
  "data": {
    "items": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "poNumber": "<poNumber>",
        "description": "<description>",
        "internalDescription": "<internalDescription>",
        "externalMemo": "<externalMemo>",
        "externalPONumber": "<externalPONumber>",
        "approvalStatus": "<approvalStatus>",
        "budgetStatus": "<budgetStatus>",
        "status": "<status>",
        "currency": "<currency>",
        "totalAmount": "19.99",
        "invoicedTotalAmount": "19.99",
        "receivedTotalAmount": "19.99",
        "startDate": "2026-01-15",
        "endDate": "2026-01-15",
        "needByDate": "2026-01-15",
        "paymentTerms": "<paymentTerms>",
        "hasInventoryItems": true,
        "vendorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "vendorName": "<vendorName>",
        "vendorContactEmail": "<vendorContactEmail>",
        "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>",
            "isItem": true,
            "quantity": "19.99",
            "price": "19.99",
            "editableAmount": "19.99",
            "total": "19.99",
            "discountPercentage": "19.99",
            "currency": "<currency>",
            "status": "<status>",
            "matchStatus": "<matchStatus>",
            "invoicedStatus": "<invoicedStatus>",
            "receivedStatus": "<receivedStatus>",
            "invoicedQuantity": "19.99",
            "invoicedAmount": "19.99",
            "receivedQuantity": "19.99",
            "receivedAmount": "19.99",
            "remainingAmount": "19.99",
            "startDate": "2026-01-15",
            "endDate": "2026-01-15",
            "deliveryDate": "2026-01-15",
            "estimatedDeliveryDate": "2026-01-15",
            "unitOfMeasure": "<unitOfMeasure>",
            "unitOfMeasureId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "itemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "departmentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
          }
        ]
      }
    ],
    "pagination": {
      "nextCursor": "<nextCursor>",
      "hasMore": true
    }
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Statuses