/v1/ endpoints of the Export API. If you call /v2/ endpoints, see 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
v1tov3. The host stayshttps://external.pleo.io. - The Export Item keeps the objects that v1 already had, such as
team,supplier,amountandadditionalInformation. v3 adds the objectsvendor,bookkeeping,servicePeriodandcontraAccount, and the fieldsubType. - v3 returns more data, and you can safely ignore the extra fields.
- The
teamCodefield is removed from the Export Item. Readteam.codeinstead. - Contra accounts are new in v3. You must map them before you create an Export Job. See Contra Accounts.
- The
statusfilter is removed fromGET /v3/export-jobs. Usestatuses. - Each Export Job has a
targetSystem, and you can filter jobs withtarget_systems. - Fields that listed fixed values in v1 are plain strings in v3. Do not fail on a value that you do not know.
Endpoint Mapping
The Export Job, Export Job Event and Export Job Items endpoints keep the same operations. The Export Item payload changes.Migration Steps
- Change
/v1/to/v3/in every Export API call. Do not stop at v2. - Replace the
statusquery parameter ofGET /v3/export-jobswithstatuses, if you use it. - Add parsing for the new objects and fields. See Payload Structure.
- Replace every read of
teamCodewithteam.code. - Check that your parser ignores fields that it does not know.
- Check that your code accepts values that it does not know for fields such as
type,statusandfailureReasonType. - Map contra accounts for the company before you create Export Jobs on v3. See Contra Accounts.
- Test the new calls in your staging environment, then switch your production integration.
Example Request
The example below lists the Export Jobs that are waiting to be processed.- OAuth 2.0
- API Key
targetSystem field.
Payload Structure
The v1 Export Item already has theteam, supplier, amount and additionalInformation objects, and you can keep your mappings for them. v3 adds the data below. Read it from the new fields.
The
user object is optional from v2 onwards. v1 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 v1. 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 acontraAccount 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:
Related How-Tos
These how-tos describe the Export API (v3) workflow that your migrated integration follows.- How to Detect and Start Export Jobs for Processing
- How to Retrieve Export Job Items for Processing
- How to Fetch Export Item Data for Processing
- How to Enable Vendor-Based Bookkeeping
- How to Update & Complete the Export Job
FAQs
Which Export API migration guide do I use?
Look at the path that your integration calls.
- If it starts with
/v2/, use Migrate from Export API v2 to v3. - If it starts with
/v1/, use Migrate from Export API v1 to v3. - If it starts with
/v0/, use Migrate from Export API v0 to v3.
What changes in every version of the migration?
Make these changes in every guide:
- Change the version in the path to
/v3/. - Replace the
statusquery parameter ofGET /v3/export-jobswithstatuses. - Replace
teamCodewithteam.code. - Ignore fields that you do not know, and accept values that you do not know for fields such as
type,statusandfailureReasonType. - 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-jobsandGET /v3/export-itemsfail with theMISSING_CONTRA_ACCOUNTSerror.
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,servicePeriodandcontraAccount. - From v0: Yes. v3 groups related data into named objects such as
team,additionalInformation,vendor,bookkeepingandservicePeriod. - From v0 only: The
metadataobject is removed and its data is inadditionalInformation.