Image Integration API for EXPENSE

Expense Image REST API

The SOAP Expense Image API detailed below has been replaced with the Expense Image REST API

The benefits of the REST version of the API include improved performance and standardized access controls. Additionally, the format of the PDF documents available via the API is now consistent with the layout of the PDF documents available within Chrome River EXPENSE.

Administrators may enable access to the Expense Image REST API via the API Key Management admin screen. Further details are available in the Implementation Toolkit.

Click here to access the new Expense Image REST API.

Legacy SOAP Expense Image API

Chrome River offers an API that enables you to download images after exporting expenses. 

  • Note: The Chrome River Image API requires the client application to specify a security protocol of TLS 1.2 or higher in order to connect.

How to Access the Service

<environment_url>/receipts/doitenvironment_url (depending on querying PROD or QA/UAT server)
  • Use the QA/UAT or Production URL provided by your organization's Chrome River administrator.

Required POST Arguments 

(Always required for every method call below)
un Username (FTP User)
pw Password (FTP Password)
method method to run

method=getVoucherInvoices

This method returns a list of all exported expense reports for a given date range that have images attached to the report or to line items within the report, based on the Chrome River export dates. Most choose to run the service after midnight for the previous day. Your company develops a program that iterates over the list of report numbers and calls the getReceipts method for each one. Please note, non-ASCII characters such as currency symbols and soft hyphens are not fully supported at this time and may cause issues with this method.

Required POST Arguments

fromDate MM/DD/YYYY format
toDate MM/DD/YYYY format
  • Note: To optimize the query, the date range is limited to 32 days.
  • Note: Records returned are limited to export dates within the past 90 calendar days. If the expense items were exported more than 90 days ago, their XML data will not be returned.

Success XML

<list><com.chromeriver.servlet.VoucherInvoiceTO><reportID>0001234567891234</reportID><voucherInvoice>0003698602242029</voucherInvoice><invoiceDate>1236293857500</invoiceDate><invoiceDateString>2016-03-05 22:57:37</invoiceDateString><vendorNumber>1234</vendorNumber><isReceiptUpdatedAfterExport>false</isReceiptUpdatedAfterExport></com.chromeriver.servlet.VoucherInvoiceTO><list/> 

Error XML

<?xml version="1.0" encoding="utf-8"?><com.chromeriver.ws.CrRestHeaderOutput><errorMessage> </errorMessage></com.chromeriver.ws.CrRestHeaderOutput>

Data Element Notes

  • voucherInvoice: Voucher Invoice number that is created in the financial system
  • invoiceDate: Formatted in seconds since 1970
  • invoiceDateString: Formatted human readable date
  • vendorNumber: Vendor1 or Vendor2 value in Chrome River

method=getReceipts

This method returns a PDF file of all the images associated with an expense report or with the line items within the report. Each call generates a single PDF file that is named with the report number. You may also choose to return the PDF report associated with an expense report, which will be appended to the receipt PDF.

Required POST Arguments

You may use either the Voucher Invoice number OR the Report ID.
voucherInvoice Voucher invoice number that was returned from the getVoucherInvoices method.
reportID
The Report ID is a 12-digit number generated by Chrome River that begins with 0100. Be sure to omit the dashes.
Example: 010012345678

Optional POST Arguments

Argument Action Possible Values Default Value
getImage Returns the expense image true/false true
getMileageDetails Returns the Mileage Details cover page true/false false
getPDFReport Returns the Full PDF Report true/false false
getPDFReportWithNotes Returns the Full PDF Report with Notes true/false false
imageFirst Returns the image before the Full PDF Report true/false true

Returns

  • If successful, the API will return the consolidated image and/or PDF file.
  • If an error occurs, the API will return XML with error information.
Note: There is no date limit as to when this call can be made.

Decision-Making and Returned Messages in Detail

  • If no data exists for the given voucher invoice ID, the message will be: “Invalid voucherInvoice.”
  • If both the image PDFs and JPGs are available, the JPGs will be retrieved first. If no JPGs are available, the PDF will be retrieved.
  • If “getPDFReport” is selected, the original PDF will be retrieved first, if available.
  • If no JPG or PDF can be found for that invoice, the message will be: “Receipts could not be retrieved. Please resubmit receipts for this voucher.”
  • If this expense report does not have any attached images, the message will be: “There are no receipts associated with this expense report.”

method=getReceiptsWithCoverPage()

This method returns a PDF file of the Cover Page and all the images associated with an expense report or with the line items within the report. Each call generates a single PDF file that is named with the voucher invoice number. You may also choose to return the PDF report associated with an expense report, which will be appended to the receipt PDF.

Required POST Argument

voucherInvoiceFor Pdf Voucher invoice number that was returned from the getVoucherInvoices method.
reportIDForPdf
The Report ID is a 12-digit number generated by Chrome River that begins with 0100. Be sure to omit the dashes.
Example: 010012345678

Returns

  • If successful, the API will return the consolidated image and/or PDF file.
  • If an error occurs, the API will return XML with error information.
Note: There is no date limit as to when this call can be made.

Decision-Making and Returned Messages in Detail

  • If no data exists for the given voucher invoice ID, the message will be: “Invalid voucherInvoice.”
  • If both the image PDFs and JPGs are available, the JPGs will be retrieved first. If no JPGs are available, the PDF will be retrieved.
  • If no JPG or PDF can be found for that invoice, the message will be: “Receipts could not be retrieved. Please resubmit receipts for this voucher.”
  • If this expense report does not have any attached images, the message will be: “There are no receipts associated with this expense report.”

method=getLineItemVoucherInvoices

This method returns a listing of line-item voucher invoices based on given Voucher Invoice.
  • IF particular line item has Image linked to it, THEN include its Line Item Voucher Invoice in the returned list, ELSE do not include it
  • IF any Images on the Header are not linked to any Line Item and only sit on the Header, THEN include the 00000000 entry in the returned listing (which should include all nonlinked images

Line Item Voucher Invoice Format: 

<VoucherInvoice> + "_" + <LineNumber> + <HotelNumber>

Required POST Argument

lineItemVoucherInvoice Voucher invoice number that was returned from the getVoucherInvoices method.

Success XML:

<list><lineItemVoucherInvoice>0860631509020301_00020000</lineItemVoucherInvoice><lineItemVoucherInvoice>0860631509020301_00010000</lineItemVoucherInvoice><lineItemVoucherInvoice>0860631509020301_00000000</lineItemVoucherInvoice></list>

method=getLineItemReceipts

This method returns a Line Item Receipts PDF based on the given Line Item Voucher Invoice. This will also work for returning all remaining images that are not linked to any Line Item (00000000).

Line Item Voucher Invoice Format: 

<VoucherInvoice> + "_" + <LineNumber> + <HotelNumber>

Required POST Argument

voucherInvoiceForReceipt Line Item-specific Voucher invoice number that was returned from the getLineItemVoucherInvoices method.

Returns

  • If successful, the API will return the consolidated image and/or PDF file. This will either consist of the images related to that particular line item or of the remaining images of the expense report not associated with any line item (00000000).
  • If an error occurs, the API will return XML with error information.
Note: There is no date limit as to when this call can be made.

method=getLineItemReceiptsWithMileageDetails

If a Google maps image is attached to a line item for which the images are requested, you may opt to return a cover page listing all the associated expense details, including Report ID, Report Name, Expense Owner, Allocation, Rate, Distance and deduction amounts. Only the method differs from getLineItemReceipts—all other parameters are the same as shown above for method=getLineItemReceipts.
Note: If there are no receipt images associated with the requested line item, an error message will be returned—even if there are mileage details associated with the line item.

method=getVoucherInvoicesForXML()

This method returns a list of all exported expense reports for a given date range that have XML files attached to line items within the report, based on the Chrome River export dates. Most choose to run the service after midnight for the previous day. Your company develops a program that iterates over the list of report numbers and calls the getReceiptsForXML method for each one.

Required POST Arguments

fromDateforXml MM/DD/YYYY format
toDateforXml MM/DD/YYYY format
  • Note: To optimize the query, the date range is limited to 32 days.
  • Note: Records returned are limited to export dates within the past 90 calendar days. If the expense items were exported more than 90 days ago, their XML data will not be returned.

Success XML

<list><com.chromeriver.servlet.VoucherInvoiceTO><reportID>0001234567891234</reportID><voucherInvoice>0003698602242029</voucherInvoice><invoiceDate>1236293857500</invoiceDate><invoiceDateString>2016-03-05 22:57:37</invoiceDateString><vendorNumber>1234</vendorNumber><isReceiptUpdatedAfterExport>false</isReceiptUpdatedAfterExport></com.chromeriver.servlet.VoucherInvoiceTO><list/> 

Error XML

<?xml version="1.0" encoding="utf-8"?><com.chromeriver.ws.CrRestHeaderOutput><errorMessage> </errorMessage></com.chromeriver.ws.CrRestHeaderOutput>

Data Element Notes

  • voucherInvoice: Voucher Invoice number that is created in the financial system
  • invoiceDate: Formatted in seconds since 1970
  • invoiceDateString: Formatted human readable date
  • vendorNumber: Vendor1 or Vendor2 value in Chrome River

method=getReceiptsForXML()

This method returns a ZIP file containing all the XML files associated with an expense report or with the line items within the report. Each call generates a single ZIP file that is named with the report number.
All XML files within the ZIP file are named based on the following: 
<ReportID>_<UUID>.xml

Required POST Argument

voucherInvoiceForXml Voucher invoice number that was returned from the getVoucherInvoicesForXML method.

Returns

  • If successful, the API will return the ZIP file containing all XML files.
  • If an error occurs, the API will return XML with error information.
Note: There is no date limit as to when this call can be made.

Decision-Making and Returned Messages in Detail

  • If no voucher invoice is entered: “VoucherInvoice is required.”
  • If no data exists for the given voucher invoice ID, the message will be: “Invalid voucherInvoice.”
  • If this expense report does not have any attached images, the message will be: “There are no XMLs associated with this expense report.”

Was this article helpful?