Emburse Enterprise will be discontinuing the Legacy SOAP-based Expense and Invoice Image APIs. This transition guide will help customers migrate to the new REST-based Image API. It explains authentication changes, lists the updated endpoints, and provides working examples to fetch PDFs and image files using the modern REST interface.
For complete details on REST API security, see the REST Image API Migration Security FAQ.
Prerequisites
Before transitioning to the REST Image API, ensure the following setup steps have been completed by Emburse's Support team and your organization.
1. Required Setup by Emburse
- Enable REST API Access: Emburse must activate the REST endpoint for your organization.
- Enable API Key Management: In Access Permissions, Emburse must grant permission to use the API Key Management screen.
2. Generate API Keys
If your organization does not yet use REST APIs, an admin may follow the steps below to generate API Keys.
1. In the Admin Settings menu, select Security > API Key Management.
2. Click Generate API Key. The generated API key will be copied to the clipboard automatically. Once you click Copied, the window will close and the key will no longer be available.
See API Key Management Admin Screen for complete details.
3. Invoice API Only: Assign an Invoice Routing Safety Net Person
Customers who are moving to the Invoice REST API should verify that they have an Invoice Routing Safety Net Person assigned.
In the Admin Settings menu, click Configuration > Customer Preferences > Approval Routing.
If no one is assigned next to "Invoice Routing Safety Net Person," click Edit and use the drop-down to select the appropriate user. Then click Save.
Key Differences at a Glance
The chart below uses the Invoice API as an example of the differences between the legacy Image API and the new REST API.
| Feature | Legacy Invoice Image API | New REST Invoice Image API |
| Authentication | User ID & Password (form fields: un, pw) | API Key + Customer Code + Chain ID (HTTP headers) |
| Communication Style | Multipart form POST | RESTful GET with query parameters |
| Base URL | https://pt.ca1.chromeriver.com/receipts/doit | https://service.chromeriver.com/v1/invoice-api |
| Image/PDF Retrieval | method=getInvoiceImages | GET /invoices/images/pdf |
| Content Type | multipart/form-data | application/json |
| Security | Cookie-based session + form credentials | Header-based stateless API authentication |
Authentication in the New REST API
Required Headers
Replace the placeholders below with the credentials provided to your organization by Emburse Enterprise.
x-api-key: [your-api-key]
customerCode: [your-customer-code]
chain-id: [your-chain-id]
Content-Type: application/json
Expense Example: Retreiving Receipts
Legacy SOAP Example for Expense
curl --location 'https://api.ca1.chromeriver.com/receipts/doit' \
--form 'un="APIDemo"' \
--form 'pw="xxxxx"' \
--form 'method="getReceipts"' \
--form 'invoiceID="050018911471"'
New REST API Example for Expense
curl --location 'https://service.chromeriver.com//v1/expense-image-api/getReceipts?reportID=050018911471' \
--header 'x-api-key: 1a234b56-7c89-1234-5678-d9e1fghijk23' \
--header 'customerCode: 0XX0' \
--header 'chain-id: APIDemo' \
--header 'Content-Type: application/json'
Expense Query Parameter Options
| Parameter | Description |
| voucherInvoice | Voucher invoice number. |
| reportID | The Report ID is a 12-digit number generated by Emburse Enterprise that begins with 0100. Be sure to omit the dashes. |
| getMileageDetails | If true, PDF will include mileage details, including map and distance, if expense was created using Maps. |
| getImage | If true, PDF will include receipt images attached to the report. |
| getPDFReport | If true, the original PDF is retrieved first, if available. |
|
getPDFReportWithNotes |
If true, the original PDF will include approval notes. |
| imageFirst | If true, images will be retrieved before any PDFs. |
Invoice Example: Retrieving Images (PDFs)
Legacy SOAP Example for Invoice
curl --location 'https://api.ca1.chromeriver.com/receipts/doit' \
--form 'un="APIDemo"' \
--form 'pw="xxxxx"' \
--form 'method="getInvoiceImages"' \
--form 'invoiceID="050018911471"'
New REST API Example for Invoice
curl --location 'https://service.chromeriver.com/v1/invoice-api/invoices/images/pdf?imageFirst=true&invoiceId=050018911471&getPDFReport=true&getImage=true' \
--header 'x-api-key: 1a234b56-7c89-1234-5678-d9e1fghijk23' \
--header 'customerCode: 0XX0' \
--header 'chain-id: APIDemo' \
--header 'Content-Type: application/json'
Invoice Image Query Parameter Options
| Parameter | Description |
| invoiceId | The invoice ID to retrieve |
| getPDFReport | If true, includes a PDF report of the invoice |
| getImage | If true, includes attached images |
| imageFirst | If true, prioritizes returning image before report |
Mapping Legacy Methods to REST Endpoints
| Legacy SOAP Method | REST API Endpoint |
| getInvoiceImages | GET /v1/invoice-api/invoices/images/pdf |
| getInvoices | /v1/invoice-api/invoices |
| getLineItemReceipts | /v1/expense-image-api/getLineItemReceipts |
| getLineItemReceiptsWithMileageDetails | /v1/expense-image-api/getLineItemReceiptsWithMileageDetails |
| getLineItemVoucherInvoices | /v1/expense-image-api/getLineItemVoucherInvoices |
| getReceipts | /v1/expense-image-api/getReceipts |
| getReceiptsForXML | /v1/expense-image-api/getReceiptsForXML |
| getReceiptsWithCoverPage | /v1/expense-image-api/getReceiptsWithCoverPage |
| getVoucherInvoices | /v1/expense-image-api/getVoucherInvoices |
| getVoucherInvoicesForXML | /v1/expense-image-api/getVoucherInvoicesForXML |
Testing and Validation
To test the REST API:
- Use tools like Postman, curl, or Insomnia.
- Provide all required headers, especially x-api-key and customerCode.
- Verify expense or invoice access using known reportId or invoiceId values.
If authenticated correctly, the API will return:
- PDF stream of the expense or invoice report
- Associated images (if available)
Reference Documentation
For complete endpoint details, input parameters, and response structure, refer to the official Swagger pages:
Comments
0 comments
Article is closed for comments.