API Reference

Overview

Overview of App Marketplace

The App Marketplace is where Pleo users can find all the apps that are available to install on their accounts. The apps are used to extend the functionality of Pleo, and can be installed by the account owner or an admin user.

Applications

An application is an app listed in the App Marketplace that can be installed by Pleo users. Applications are used to extend the functionality of Pleo, and can be used to automate tasks, integrate with other systems, or provide additional features.

Installations

An installation is a connection between an application and a Pleo subject. When an application is installed for a Pleo subject, an installation is created.

As a developer, you can manage the installations of your application using the Installations API. The API allows you to create, update, and delete installations, as well as retrieve information about them.

The installation has a metadata field, which can be used by the application to store additional information about the installation. This can be useful for storing configuration settings, or other data that is specific to the installation. This data is in no way used or processed by Pleo, and is only stored for the application to use.

Creating Installations

OAuth

If you're using OAuth as your authentication method, the installation will automatically be created upon completion of the OAuth flow. Depending on if your app requires configuration or not, you may need to call the POST /installations/me:activate endpoint to set the status to ACTIVATED. Otherwise, the installation will be created with the status ACTIVATED by default.

Installation statuses and lifecycle

There are 4 possible statuses for an installation:

  • AUTHORIZED: The user has completed the auth flow, but the installation is not yet active or ready for use.
  • ACTIVATED: The installation is active and ready for use.
  • INACTIVE: The installation is inactive and cannot be used. This could be used after multiple failed attempts to connect to the target system. It will also be used if the authentication method towards Pleo is no longer valid, for example having expired.
  • PENDING_INTEGRATION: The installation is pending action or processing on the application side. This status could be used when the application is performing a sync or other background task. While an installation is in this status, the user is not able to disconnect the application, to avoid data loss.