Migrate to the Export API

This guide is for partners who used the Expenses API to build custom export integrations to accounting systems. If you were fetching expense data for other workflows, see Migrate to the Accounting Entries API instead.

New to the Export API?

Export Workflow Guide

End-to-end walkthrough of the Export API integration model.

Integration Design

Rules and requirements for each part of an export integration.

Connect Pleo to a Custom API Integration

How to connect Pleo to route exports to your custom integration.

API Scopes

Required scopes: export-jobs:write, export-jobs:read, export-items:read.

OAuth Guide

End-to-end OAuth 2.0 workflow guide for Pleo integrations.

OAuth with Postman

How to configure Postman to authenticate using OAuth and call the Pleo API.

Standalone API Key Guide

End-to-end guide for authenticating with standalone API keys.

Standalone API Keys with Postman

How to make API calls using standalone API keys in Postman.

What Changes in Your Integration

The table below gives a quick overview of how each step maps from the Expenses API to the Export API.

Step	Before (Expenses API)	After (Export API)
Detect new exports	Poll `GET /v1/expenses?status=QUEUED`	Listen for `v1.export.job-created` webhook
Start a job	Not applicable	`POST /v3/export-job-events` with `"event": "started"`
Fetch items	`GET /v1/expenses?status=QUEUED`	`GET /v3/export-jobs/{jobId}/items`
Process export items	At integration’s discretion	Integration design guidelines and workflow guide
Update item status	`PUT /v1/expenses` with `{"status": "EXPORTING"}`	`PUT /v3/export-jobs/{jobId}/items` with granular statuses
Complete the export	`PUT /v1/expenses` with `{"status": "EXPORTED"}`	Update item statuses + `POST /v3/export-job-events` with `"event": "completed"`

The following sections cover each change in detail.

Detecting New Exports

Before:

GET /v1/expenses?status=QUEUED

After: Listen for the v1.export.job-created webhook event.

Starting a Job

Before: Not applicable. After: Create a started event to claim the job before processing.

POST https://external.pleo.io/v3/export-job-events
Content-Type: application/json

{
    "event": "started",
    "jobId": "[JOB_ID]"
}

Fetching Export Items

Before:

GET https://openapi.pleo.io/v1/expenses?status=QUEUED

After:

GET https://external.pleo.io/v3/export-jobs/[JOB_ID]/items

Processing Export Items

Before: At integration’s discretion. After: Pleo provides integration design guidelines and a dedicated workflow guide covering bookkeeping methods, accounts mapping, data mapping, attachments, and posting behaviour.

Updating Item Status

Before:

PUT https://openapi.pleo.io/v1/expenses
Content-Type: application/json

{"status": "EXPORTING"}

After: Update individual items with granular statuses (in_progress, successful, failed, or abandoned).

PUT https://external.pleo.io/v3/export-jobs/[JOB_ID]/items
Content-Type: application/json

[
    {"accountingEntryId": "[ITEM_ID]", "status": "in_progress"}
]

Completing the Export

Before:

PUT https://openapi.pleo.io/v1/expenses
Content-Type: application/json

{"status": "EXPORTED"}

After: Update item statuses to their final state, then create a completed event.

PUT https://external.pleo.io/v3/export-jobs/[JOB_ID]/items
Content-Type: application/json

[
    {
        "accountingEntryId": "[ITEM_ID]",
        "status": "successful",
        "exportedAt": "2025-07-31T12:48:52.236Z",
        "externalId": "[ENTRY_ID_IN_YOUR_ACCOUNTING_SYSTEM]",
        "externalUrl": "[ENTRY_URL_IN_YOUR_ACCOUNTING_SYSTEM]"
    }
]

POST https://external.pleo.io/v3/export-job-events
Content-Type: application/json

{
    "event": "completed",
    "jobId": "[JOB_ID]"
}

Data Model Changes

The table below maps fields from the Expense model to their equivalents in the Export Item model.

— : field is not available in the Export Item model
* : data is the same but represented differently. See the Export Item API reference for details.
** : resolved entity relationship: the associated data is included directly, removing the need for additional API calls

`Expense` field	`Export Item` equivalent
id	accountingEntryId
employeeId	user.id
employeeCode	user.code
departmentId	team.id
performedAt	date
amountOriginal	—
amountSettled	amount *
note	note
type	type *
accountId	accountingEntryLines[].account.id
taxCodeId	accountingEntryLines[].tax.id
createdAt	date **
updatedAt	date **
deletedAt	—
tagIds[].id	accountingEntryLines[].tags[].id
tagIds[].tagGroupId	accountingEntryLines[].tags[].groupCode **
receiptIds[]	files[] **
settledExpenseIds[]	additionalInformation.reconciledEntries[]
status	—
supplier.CIF	supplier.taxIdentifier
supplier.documentNumber	—
cardTransaction.state	—
cardTransaction.authorizedAt	—
cardTransaction.settledAt	date
cardTransaction.reversedAt	—
cardTransaction.merchant.id	vendor.id
cardTransaction.merchant.name	vendor.name
lines[].amountSettled	accountingEntryLines[].lineAmount
lines[].accountId	accountingEntryLines[].account.id
lines[].taxCodeId	accountingEntryLines[].tax.id
lines[].tagIds[]	accountingEntryLines[].tags[].id

Overview

Migration Guides

Migrate to the Export API

New to the Export API?

Export Workflow Guide

Integration Design

Connect Pleo to a Custom API Integration

API Scopes

OAuth Guide

OAuth with Postman

Standalone API Key Guide

Standalone API Keys with Postman

What Changes in Your Integration

Detecting New Exports

Starting a Job

Fetching Export Items

Processing Export Items

Updating Item Status

Completing the Export

Data Model Changes

​New to the Export API?

Export Workflow Guide

Integration Design

Connect Pleo to a Custom API Integration

API Scopes

OAuth Guide

OAuth with Postman

Standalone API Key Guide

Standalone API Keys with Postman

​What Changes in Your Integration

​Detecting New Exports

​Starting a Job

​Fetching Export Items

​Processing Export Items

​Updating Item Status

​Completing the Export

​Data Model Changes

New to the Export API?

What Changes in Your Integration

Detecting New Exports

Starting a Job

Fetching Export Items

Processing Export Items

Updating Item Status

Completing the Export

Data Model Changes