REST Image API Migration Guide

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.

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/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

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

Mapping Legacy Methods to REST Endpoints

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)

REST Image API Migration Security FAQ

Why is Emburse retiring the SOAP-based Expense Image API?

The SOAP API is built on outdated infrastructure, including:

• Servers running an operating system that is past End of Life
• A codebase tied to the now-deprecated Flash UI
• A protocol no longer aligned with Emburse’s REST-first strategy

These limitations pose increased security and compliance risks, prompting the transition to a more modern and secure REST-based solution.

Is REST API as secure as SOAP?

Yes, REST APIs are as secure as SOAP APIs.

How is data protected in transit with REST?

All REST APIs use HTTPS with TLS 1.2+ for secure communication and encrypt data in transit to prevent interception or tampering.

How does authentication work in the REST API?

The REST API uses API keys for authentication.

Where is customer data stored and how is it protected?

All customer data is stored in encrypted databases (AES-256). We maintain geo-redundant backups, automated disaster recovery, and real-time monitoring. Access to data is restricted, logged, and audited regularly.

Is the REST API compliant with industry regulations?

Yes. Our compliance aligns with major compliance frameworks, including:

• GDPR (General Data Protection Regulation)
• SOC 2 Type II
• PCI-DSS (for payment data, where applicable)

Additionally, security audits and penetration testing are conducted regularly by third parties.

How do you protect against common vulnerabilities?

• Secure API Practices
• TLS Encryption
• Authentication and Authorization
• Logging and Monitoring
• SQL Injection
• Cross-Site Scripting (XSS)

How does Emburse protect my data during the migration?

Data continues to be protected by the same enterprise-grade controls already in place:

• All REST API traffic is secured.
• No change to existing data-retention or privacy protocols.
• The migration does not expose or transfer customer data automatically; integrations must be manually updated and validated.

Who can I contact with security questions or reports?

Please contact your Emburse Enterprise Customer Success Manager.

You may also refer to the security and compliance documentation within the Emburse Trust Center. 

Reference Documentation

For complete endpoint details, input parameters, and response structure, refer to the official Swagger pages:

• Invoice API Swagger Documentation
• Expense API Swagger Documentation