> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pleo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate from Export API v0 to v3

> Migration guide from Export API v0 directly to Export API (v3). Use it if your integration calls paths that start with /v0/. The payload structure changes, so check your parsing. For /v1/ or /v2/ paths, use the matching guide.

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](https://developers.pleo.io/deprecation/legacy-export-api/migrate-from-v1-to-v3.md) or [Migrate from Export API v2 to v3](https://developers.pleo.io/deprecation/legacy-export-api/migrate-from-v2-to-v3.md) instead.

> **Use this page to answer:**

### 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](https://developers.pleo.io/deprecation/legacy-export-api/migrate-from-v2-to-v3.md).
* If it starts with `/v1/`, use [Migrate from Export API v1 to v3](https://developers.pleo.io/deprecation/legacy-export-api/migrate-from-v1-to-v3.md).
* If it starts with `/v0/`, use [Migrate from Export API v0 to v3](https://developers.pleo.io/deprecation/legacy-export-api/migrate-from-v0-to-v3.md).

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](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-resolve-missing-contra-accounts.md).

### 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](https://developers.pleo.io/reference/export-api/export-items-v3/get-export-items.md) for the full list.

Check your parsing before you switch.

> **Sources for the Export API:**
>
> * OpenAPI reference: the endpoint pages under the [Export API Overview](https://developers.pleo.io/reference/export-api/export-api-overview.md). Use the v3 pages for new work. The [Export API Workflow](https://developers.pleo.io/reference/export-api/export-api-workflow.md) explains the order of the calls.
> * Attachments: [Attachments](https://developers.pleo.io/docs/current/platform/exports/attachments.md) explains the receipt file limits.
> * How-tos, all under `/docs/current/how-tos/accounting-integrations/`: [How to Detect and Start Export Jobs for Processing](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-detect-and-start-export-jobs-for-as-erp-processing.md), [How to Retrieve Export Job Items for Processing](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-retrieve-export-job-items-for-as-erp-processing.md), [How to Fetch Export Item Data for Processing](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-fetch-export-item-data-for-as-erp-processing.md), [How to Transfer Attachments](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-transfer-attachments-for-as-erp-processing.md), [How to Update Export Items](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-update-export-items-for-as-erp-processing.md) and [How to Update & Complete the Export Job](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-update-and-complete-export-job-for-as-erp-processing.md).
> * If a how-to and the reference disagree, trust the how-to. How-tos record tested behaviour.

> This page is the canonical source for migrating from Export API v0 to v3. Related pages cover different concerns:
>
> * [Migrate from Export API v1 to v3](https://developers.pleo.io/deprecation/legacy-export-api/migrate-from-v1-to-v3.md): for v1 integrations.
> * [Migrate from Export API v2 to v3](https://developers.pleo.io/deprecation/legacy-export-api/migrate-from-v2-to-v3.md): for v2 integrations.
> * [Legacy Export API Overview](https://developers.pleo.io/deprecation/legacy-export-api/overview.md): helps you pick the right guide.

Terminology: Legacy and New

This guide calls Export API v0 the **legacy Export API** and its replacement the **new Export API (v3)**.

All versions are under `https://external.pleo.io`. The version is the first part of the path, for example `/v0/export-jobs` or `/v3/export-jobs`.

Note

Skip v1 and v2 and migrate directly from v0 to v3. You do not need to change your integration more than once.

## New to the Export API (v3)?

> [card] [Export Workflow Guide](https://developers.pleo.io/docs/current/guides/export-integration-workflow-guide.md)
>
> End-to-end walkthrough of the Export API (v3) integration model.

> [card] [API Scopes](https://developers.pleo.io/reference/export-api/export-api-scopes.md)
>
> Required scopes: `export-jobs:write`, `export-jobs:read`, `export-items:read`.

> [card] [Get Export Items](https://developers.pleo.io/reference/export-api/export-items-v3/get-export-items.md)
>
> The v3 reference page for the Export Item payload.

> [card] [OAuth Guide](https://developers.pleo.io/docs/current/guides/oauth-workflow-guide.md)
>
> End-to-end OAuth 2.0 workflow guide for Pleo integrations.

> [card] [Standalone API Key Guide](https://developers.pleo.io/docs/current/guides/standalone-api-keys-workflow-guide.md)
>
> 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](#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

| Operation | v0 | v3 |
| :- | :- | :- |
| Get a list of Export Jobs | `GET /v0/export-jobs` | `GET /v3/export-jobs` |
| Create a new Export Job | `POST /v0/export-jobs` | `POST /v3/export-jobs` |
| Get an Export Job | `GET /v0/export-jobs/{jobId}` | `GET /v3/export-jobs/{jobId}` |
| Create an Export Job Event | `POST /v0/export-job-events` | `POST /v3/export-job-events` |
| Get Export Items | `GET /v0/export-items` | `GET /v3/export-items` |
| Get Export Job Items | `GET /v0/export-jobs/{jobId}/items` | `GET /v3/export-jobs/{jobId}/items` |
| Update Export Job Items | `PUT /v0/export-jobs/{jobId}/items` | `PUT /v3/export-jobs/{jobId}/items` |

## 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](#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](#contra-accounts).
8. Test the new calls in your staging environment, then switch your production integration.

The [Export API scopes](https://developers.pleo.io/reference/export-api/export-api-scopes.md) page lists the same scopes for every version.

### Example Request

The example below lists the Export Jobs that are waiting to be processed.

```http theme={null}
GET https://external.pleo.io/v0/export-jobs?company_id=12abc3d4-e567-890e-1234-abc56e78fabc&status=pending
```

becomes

```http theme={null}
GET https://external.pleo.io/v3/export-jobs?company_id=12abc3d4-e567-890e-1234-abc56e78fabc&statuses=pending
```

> [tab] OAuth 2.0
>
> ```bash theme={null}
> curl -X GET "https://external.pleo.io/v3/export-jobs?company_id=12abc3d4-e567-890e-1234-abc56e78fabc&statuses=pending" \
>   -H "Authorization: Bearer <access_token>"
> ```

> [tab] API Key
>
> ```bash theme={null}
> curl --request GET \
>   -u "pls_1ab2cd3e4f5g6h7a89b012c34de56f78_gabc90:" \
>   -H "Accept: application/json;charset=UTF-8" \
>   "https://external.pleo.io/v3/export-jobs?company_id=12abc3d4-e567-890e-1234-abc56e78fabc&statuses=pending" \
>   | jq
> ```

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.

| Data | v0 | v3 |
| :- | :- | :- |
| Reconciliation ID, attendees and invoice details | `metadata` | `additionalInformation` |
| Team | `teamCode` | `team` object with `id`, `name` and `code` |
| Vendor of the expense | Not available | `vendor` object with `id`, `name`, `code`, `externalId`, `country`, `defaultCurrency`, `registrationNumber` and `taxRegistrationNumber` |
| How the expense is booked | Not available | `bookkeeping` object with `method` |
| Service period | Not available | `servicePeriod` object with `from` and `to` |
| Sub-type of the expense | Not available | `subType` |
| Contra account | Not available | `contraAccount` object. See [Contra Accounts](#contra-accounts). |

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](https://developers.pleo.io/reference/export-api/export-items-v3/get-export-items.md).

```diff theme={null}
 {
-  "metadata": {
-    "reconciliationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
-  },
-  "teamCode": "SALES-DK"
+  "additionalInformation": {
+    "reconciliationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
+  },
+  "team": {
+    "id": "b6f2b2e0-1a3a-4e2f-9c0e-7a4b8f2c1d3e",
+    "name": "Sales",
+    "code": "SALES-DK"
+  },
+  "bookkeeping": {
+    "method": "journal"
+  }
 }
```

## 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](https://developers.pleo.io/reference/export-api/export-items-v3/get-export-items.md) reference for the full list.

| Object | New field in v3 | Description |
| :- | :- | :- |
| Export Job | `targetSystem` | The target system that the Export Job is recorded against. |
| Export Item | `contraAccount` | The contra account of the Export Item. See [Contra Accounts](#contra-accounts). |
| Export Item | `accountingEntryLines[].account.id` and `name` | The ID and name of the account of the line. |
| Export Item | `accountingEntryLines[].tags[].id` | The ID of each tag of the line. |
| Export Item | `accountingEntryLines[].tax.id` | The ID of the tax of the line. |
| Export Item | `accountingEntryLines[].tax.ingoingTaxAccount` | The account for the ingoing tax of the line. |
| Export Item | `accountingEntryLines[].tax.outgoingTaxAccount` | The account for the outgoing tax of the line. |
| Export Item | `user.id` | The ID of the user. |
| Export Item | `additionalInformation.reconciledEntries` | The entries that the Export Item is reconciled with. |
| Export Item | `additionalInformation.attendeesData` | The `employees` and `contacts` who attended. |
| Export Item | `additionalInformation.creditNoteInformation` | Credit note details, including the allocation. |
| Export Item | `additionalInformation.invoiceInformation.discountAmount` | The discount amount of an invoice. |
| Export Item | `additionalInformation.invoiceInformation.discountPercentage` | The discount percentage of an invoice. |

## 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:

```json theme={null}
{
  "type": "MISSING_CONTRA_ACCOUNTS",
  "message": "Make sure you don't export GBP expenses before you set your contra accounts."
}
```

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](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-resolve-missing-contra-accounts.md).

## 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](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-detect-and-start-export-jobs-for-as-erp-processing.md)
* [How to Retrieve Export Job Items for Processing](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-retrieve-export-job-items-for-as-erp-processing.md)
* [How to Fetch Export Item Data for Processing](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-fetch-export-item-data-for-as-erp-processing.md)
* [How to Enable Vendor-Based Bookkeeping](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-enable-vendor-based-bookkeeping.md)
* [How to Update & Complete the Export Job](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-update-and-complete-export-job-for-as-erp-processing.md)

[Export Workflow Guide →](https://developers.pleo.io/docs/current/guides/export-integration-workflow-guide.md)
