/api/p/v{version}/invoices/search

The Search Invoices endpoint allows you to search and retrieve a list of invoices based on various criteria such as invoiced date range, paid date range, status, and associated load numbers. To ensure compatibility and stability, it is essential to include the correct version number in the URL path when making a request. For more information on versioning, refer to the Versioning page.

Request Parameters

The following parameters are required in the URL path:

Parameter	Type	Required	Description
version	String	Yes	The API version to interact with.

Request Body

The following fields are required in the request body:

Parameter	Type	Required	Description
page	Integer	No	The page number for pagination.
pageSize	Integer	Yes	The number of records per page for pagination.
invoicedDateRange	Object	Conditionally	The range of invoiced dates to filter the results. This field is required if the other conditionally required fields are left empty.
invoicedDateRange.start	String (Date-Time)	Conditionally	The start date for the invoiced date range. This field is required if the other conditionally required fields are left empty.
invoicedDateRange.end	String (Date-Time)	Conditionally	The end date for the invoiced date range. This field is required if the other conditionally required fields are left empty.
paidDateRange	Object	Conditionally	The range of paid dates to filter the results. This field is required if the other conditionally required fields are left empty.
paidDateRange.start	String (Date-Time)	Conditionally	The start date for the paid date range. This field is required if the other conditionally required fields are left empty.
paidDateRange.end	String (Date-Time)	Conditionally	The end date for the paid date range. This field is required if the other conditionally required fields are left empty.
status	Array of Strings	Conditionally	A list of invoice statuses to filter the results. This field is required if the other conditionally required fields are left empty.
loadNumbers	Array of Strings	Conditionally	A list of load numbers associated with the invoices. This field is required if the other conditionally required fields are left empty.
poNumbers	Array of Strings	Conditionally	A list of purchase order numbers associated with the invoices. This field is required if the other conditionally required fields are left empty.
orderNumbers	Array of Strings	Conditionally	A list of order numbers associated with the invoices. This field is required if the other conditionally required fields are left empty.
customerId	String	Conditionally	The customer ID to filter the results. This field is required if the other conditionally required fields are left empty.

Example CURL request

Use the Current API version number and make sure to replace the Authorization header value with your actual Bearer token for the request:

curl --location 'https://integrations.alvys.com/api/p/v1/invoices/search' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaWQiOiJBT...' \
--header 'Content-Type: application/json' \
--data '{
  "page": 0,
  "pageSize": 100,
  "invoicedDateRange": {
     "start": "2023-08-02T09:53:34.251Z",
     "end": "2024-08-02T09:53:34.251Z"
  },
  "paidDateRange": {
     "start": "2023-08-02T09:53:34.251Z",
     "end": "2024-08-02T09:53:34.251Z"
  },
  "status": [
     "Paid"
  ],
  "loadNumbers": [
     "123456789"
  ],
  "customerId": ""
}'

Response Parameters

The following table lists the parameters included in the response for invoice-related requests.

Parameter	Type	Description
page	Integer	The current page number of the result set.
pageSize	Integer	The number of records per page.
total	Integer	The total number of records matching the search criteria.
items	Array of Objects	The list of invoices that match the search criteria.
items.id	String	The unique identifier of the invoice.
items.number	String	The invoice number.
items.type	String	The type of the invoice (e.g., Standard, Credit Memo).
items.status	String	The current status of the invoice (e.g., Open, Paid, Overdue).
items.createdDate	String (Date-Time)	The date and time when the invoice was created.
items.invoicedDate	String (Date-Time)	The date and time when the invoice was issued.
items.dueDate	String (Date-Time)	The due date for the invoice payment.
items.paidDate	String (Date-Time)	The date when the invoice was fully paid.
items.total	Object	The total amount of the invoice.
items.total.amount	Number	The monetary value of the total amount.
items.total.currency	String	The currency in which the invoice is issued.
items.amountPaid	Object	The amount that has been paid towards the invoice.
items.amountPaid.amount	Number	The monetary value of the amount paid.
items.amountPaid.currency	String	The currency in which the payment was made.
items.remainingBalance	Object	The remaining balance due on the invoice.
items.remainingBalance.amount	Number	The monetary value of the remaining balance.
items.remainingBalance. currency	String	The currency in which the balance is due.
items.overPaymentAmount	Object	The overpayment amount if any.
items.overPaymentAmount.amount	Number	The monetary value of the overpayment.
items.overPaymentAmount.currency	String	The currency in which the overpayment was made.
items.isSubmitted	Boolean	Indicates if the invoice has been submitted.
items.lastSendDate	String (Date-Time)	The last date and time when the invoice was sent.
items.supplementalInvoiceType	String	The type of supplemental invoice if applicable.
items.vendor	Object	Vendor details associated with the invoice.
items.vendor.id	String	The unique identifier of the vendor.
items.vendor.name	String	The name of the vendor.
items.vendor.remitAddress	Object	The remit address of the vendor.
items.vendor.remitAddress.street	String	The street address of the vendor.
items.vendor.remitAddress.city	String	The city of the vendor's address.
items.vendor.remitAddress.state	String	The state of the vendor's address.
items.vendor.remitAddress.zipCode	String	The zip code of the vendor's address.
items.vendor.remitEmail	String	The email address for remittances to the vendor.
items.vendor. remitPhone	String	The phone number for remittances to the vendor.
items.customer	Object	Customer details associated with the invoice.
items.customer.id	String	The unique identifier of the customer.
items.customer.name	String	The name of the customer.
items.customer.emailAddresses	Array of Strings	The list of email addresses for the customer.
items.customer.phoneNumbers	Array of Strings	The list of phone numbers for the customer.
items.customer.billingAddress	Object	The billing address of the customer.
items.customer.billingAddress.street	String	The street address of the customer.
items.customer.billingAddress.city	String	The city of the customer's billing address.
items.customer.billingAddress.state	String	The state of the customer's billing address.
items.customer.billingAddress.zipCode	String	The zip code of the customer's billing address.
items.customer.shippingAddress	Object	The shipping address of the customer.
items.customer.shippingAddress.street	String	The street address of the customer.
items.customer.shippingAddress.city	String	The city of the customer's shipping address.
items.customer.shippingAddress.state	String	The state of the customer's shipping address.
items.customer.shippingAddress.zipCode	String	The zip code of the customer's shipping address.
items.lineItems	Array of Objects	The line items included in the invoice.
items.lineItems.id	String	The unique identifier of the line item.
items.lineItems.name	String	The name of the line item.
items.lineItems.amount	Object	The amount associated with the line item.
items.lineItems.amount.amount	Number	The monetary value of the line item.
items.lineItems.amount.currency	String	The currency in which the line item is priced.
items.lineItems.rate	Object	The rate details for the line item.
items.lineItems.rate.unitOfMeasurement	String	The unit of measurement for the rate (e.g., hours, miles).
items.lineItems.rate.units	Number	The number of units billed.
items.lineItems.rate.rate	Number	The rate per unit.
items.lineItems.loadNumber	String	The load number associated with the line item.
items.lineItems.customerId	String	The customer ID associated with the line item.
items.lineItems.category	String	The category of the line item.
items.loads	Array of Objects	The loads associated with the invoice.
items.loads.id	String	The unique identifier of the load.
items.loads.loadNumber	String	The load number associated with the invoice.
items.loads.subsidiaryName	String	The name of the subsidiary associated with the load.
items.loads.source	String	The source of the load.
items.loads.orderNumber	String	The order number associated with the load.
items.loads.poNumber	String	The purchase order number associated with the load.
items.payments	Array of Objects	The payments made against the invoice.
items.payments.id	String	The unique identifier of the payment.
items.payments.paymentDate	String (Date-Time)	The date and time when the payment was made.
items.payments.amount	Object	The amount paid in the payment.
items.payments.amount.amount	Number	The monetary value of the payment.
items.payments.amount.currency	String	The currency in which the payment was made.
items.payments.checkNumber	String	The check number associated with the payment.
items.payments.paymentReference	String	The payment reference number.

Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

Rate Limits

This endpoint is subject to standard rate limiting. The default rate limit is 10 requests per minute. For more information, refer to the Rate Limits page.

This page is interactive, allowing you to try a request by specifying the API version in the URL path and providing the necessary request body. As you fill out the parameters, the Curl command on the right side of the page will be automatically updated. Alternatively, you can directly edit the Curl command. Make sure to authorize yourself before trying a request.