Skip to main content
This guide is for integrations that call /v0/ endpoints of the Export API. If you call /v1/ or /v2/ endpoints, see Migrate from Export API v1 to v3 or Migrate from Export API v2 to v3 instead.

New to the Export API (v3)?

Export Workflow Guide

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

API Scopes

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

Get Export Items

The v3 reference page for the Export Item payload.

OAuth Guide

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

Standalone API Key Guide

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

Key Differences

  • The version number in the endpoint changes from v0 to v3. The host stays https://external.pleo.io.
  • The list of endpoints and what they do stays the same.
  • The structure of the Export Item payload changes. v0 returned a flat payload with a loose metadata section. v3 groups related data into named objects such as team, additionalInformation, bookkeeping, vendor and servicePeriod.
  • The metadata object is removed. Its data is in additionalInformation.
  • The teamCode field is removed from the Export Item. Read team.code instead.
  • v3 returns more data, and you can safely ignore the extra fields.
  • Contra accounts are new in v3. You must map them before you create an Export Job. See Contra Accounts.
  • The status filter is removed from GET /v3/export-jobs. Use statuses.
  • Each Export Job has a targetSystem, and you can filter jobs with target_systems.
  • Fields that listed fixed values in v0 are plain strings in v3. Do not fail on a value that you do not know.

Endpoint Mapping

Migration Steps

  1. Change /v0/ to /v3/ in every Export API call. Do not stop at v1 or v2.
  2. Replace the status query parameter of GET /v3/export-jobs with statuses, if you use it.
  3. Update your Export Item parsing for the grouped structure. See Payload Structure.
  4. Replace every read of teamCode with team.code.
  5. Check that your parser ignores fields that it does not know.
  6. Check that your code accepts values that it does not know for fields such as type, status and failureReasonType.
  7. Map contra accounts for the company before you create Export Jobs on v3. See Contra Accounts.
  8. Test the new calls in your staging environment, then switch your production integration.
The Export API scopes page lists the same scopes for every version.

Example Request

The example below lists the Export Jobs that are waiting to be processed.
becomes
Each Export Job in the response now has a targetSystem field.

Payload Structure

v0 returned the Export Item as a flat payload, with the invoice details, the attendees and the reconciliation ID in a loose metadata section. v3 groups related data into named objects. Read each group from its object in v3. The supplier.identifier field is not in v3. The supplier object has a code instead. The user object is optional from v2 onwards. v0 always returned it, so do not assume that it is present. Optional fields can come back as null or not be in the response at all. Treat both as “not set”. For every field, see Get Export Items.

What v3 Adds

You can safely ignore any of these fields that your integration does not need. This list shows what changed from v0. v3 may add more fields over time, so use the Get Export Items reference for the full list.

Contra Accounts

Contra accounts are new in v3. The Export Item has a contraAccount object with a code, an identifier, an id and a name. v3 needs contra accounts to be set up before you can create an Export Job. Map a contra account for the default currency of each entity. Go to Settings, then Accounting, then the Contra accounts tab. If you do not see the tab, contact Pleo support to enable it. If the contra accounts are not configured, POST /v3/export-jobs and GET /v3/export-items return a 400 error:
Before you switch a company to v3, check that every entity has a contra account for its default currency. v0 has no such requirement. For the full steps, see How to Resolve MISSING_CONTRA_ACCOUNTS. These how-tos describe the Export API (v3) workflow that your migrated integration follows.

FAQs

Which Export API migration guide do I use?

Look at the path that your integration calls.Each guide goes directly to Export API (v3). Do not migrate through an intermediate version. The export workflow does not change.

What changes in every version of the migration?

Make these changes in every guide:
  • Change the version in the path to /v3/.
  • Replace the status query parameter of GET /v3/export-jobs with statuses.
  • Replace teamCode with team.code.
  • Ignore fields that you do not know, and accept values that you do not know for fields such as type, status and failureReasonType.
  • Map contra accounts before you create an Export Job.

What are contra accounts, and why does v3 fail without them?

  • Contra accounts are new in v3. Map them for the company before you create an Export Job.
  • If they are missing, POST /v3/export-jobs and GET /v3/export-items fail with the MISSING_CONTRA_ACCOUNTS error.
See How to Resolve MISSING_CONTRA_ACCOUNTS.

Does the Export Item payload change in v3?

It depends on your current version.
  • From v2: No. The structure is the same and v3 adds fields.
  • From v1: The objects that v1 already had stay the same. v3 adds the objects vendor, bookkeeping, servicePeriod and contraAccount.
  • From v0: Yes. v3 groups related data into named objects such as team, additionalInformation, vendor, bookkeeping and servicePeriod.
  • From v0 only: The metadata object is removed and its data is in additionalInformation.
v3 may add more fields over time. See Get Export Items for the full list.Check your parsing before you switch.