Installations of applications. An installation is a representation of an application being installed for a resource. Currently we support companies and organizations, future support might include users or teams. Installations are created automatically after a successful OAuth flow. The main use case for these APIs is to enable third party apps to manage their own installations and to get information about the installations that exist for a specific resource.
openapi: 3.0.1
info:
title: App Marketplace accounting-entries Installations API
description: API for Pleo App Marketplace
termsOfService: https://pleo.io/terms/
contact:
email: partner-ecosystem-team@pleo.io
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 39.4.0
servers:
- url: https://external.pleo.io
description: Production server
- url: https://external.staging.pleo.io
description: Staging server
security:
- bearerAuth: []
- basicAuth: []
tags:
- name: Installations
description: Installations of applications. An installation is a representation of an application being installed for a resource. Currently we support companies and organizations, future support might include users or teams. <br> Installations are created automatically after a successful OAuth flow. <br> The main use case for these APIs is to enable third party apps to manage their own installations and to get information about the installations that exist for a specific resource.
externalDocs:
description: Read more about installations
url: https://www.notion.so/pleo/Installation-dbf7ce32f2e84848b8a36a5ebeaeb8f0?pvs=4
paths:
/v1/installations/completions:
put:
tags:
- Installations
summary: Complete the installation of a client
description: '**Deprecated**: Please use /installations/me:activate instead. Marks the installation as complete'
operationId: completeInstallationExternalClientOnlyIdempotently
responses:
'200':
description: Installation completed.
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/InstallationResponse'
'400':
description: Bad request
'500':
description: Cannot complete installation due to infrastructure issue
deprecated: true
/v1/installations/me:
get:
tags:
- Installations
summary: Get client installation
description: Retrieve the list of installations that you have done
operationId: getClientInstallation
parameters:
- name: company_id
in: query
description: Optional company ID to filter installations within the authenticated organisation.
required: false
style: form
explode: true
schema:
type: string
format: uuid
responses:
'200':
description: Installation exists.
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/InstallationResponse'
'400':
description: Bad request
'500':
description: Cannot retrieve installation due to infrastructure issue
put:
tags:
- Installations
summary: Update a client installation
description: Send a request to this endpoint if you want to modify the installation status or the metadata.
operationId: updateClientInstallation
requestBody:
description: Installation request
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/UpdateInstallationRequest'
required: true
responses:
'200':
description: Installation updated.
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/InstallationResponse'
'400':
description: Bad request
'500':
description: Cannot update installation due to infrastructure issue
post:
tags:
- Installations
summary: Create a client installation
description: The integration sends a request to this endpoint to create an installation. This is required, especially when API keys are used for authorisation.
operationId: createClientInstallation
requestBody:
description: Installation request
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/CreateClientInstallationRequest'
required: true
responses:
'200':
description: Installation created.
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/InstallationResponse'
'400':
description: Bad request
'500':
description: Cannot create installation due to infrastructure issue
delete:
tags:
- Installations
summary: Delete client's installation
description: Deletes the installation for the client and will revoke all access and refresh tokens for the client.
operationId: deleteClientInstallation
responses:
'204':
description: Installation deleted successfully
'404':
description: Installation does not exist
'502':
description: Installation could not be deleted due to infrastructure issue
/v1/installations/me:activate:
post:
tags:
- Installations
summary: Activate the installation for a client
description: The integration sends a request to this endpoint to activate the installation, post authorisation. The request is sent after the integration has synchronised tags, tax codes, and vendors between the Pleo account and the client. Note that this is applicable when OAuth is used for authorisation.
operationId: activateMyInstallation
responses:
'200':
description: Installation is successfully activated.
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/InstallationResponse'
'400':
description: Bad request
'500':
description: Cannot activate the installation due to infrastructure issue
components:
schemas:
UpdateInstallationRequest:
required:
- status
type: object
properties:
errorCode:
$ref: '#/components/schemas/InstallationErrorCode'
metadata:
type: object
additionalProperties:
type: object
description: A means to store any metadata about the installation. Could for example be settings for the application
example:
externalApplicationId: '123456789'
description: A means to store any metadata about the installation. Could for example be settings for the application
example:
externalApplicationId: '123456789'
status:
$ref: '#/components/schemas/InstallationStatus'
InstallationErrorCode:
type: string
description: '
| Value | Description |
| ------ | ----------- |
| NOT_ENTITLED | The installation is not entitled to use the application. |
| AUTH_ERROR | There was an authentication error during installation. |'
enum:
- NOT_ENTITLED
- AUTH_ERROR
InstallationResponse:
required:
- applicationId
- createdAt
- id
- metadata
- resource
- status
- updatedAt
type: object
properties:
applicationId:
type: string
description: The unique identifier of the application this installation is for.
format: uuid
readOnly: true
example: 123e4567-e89b-12d3-a456-426614174000
createdAt:
type: string
description: The date and time when the installation was created.
format: date-time
readOnly: true
example: '2021-01-01T00:00:00Z'
errorCode:
type: string
description: Explains the error that inactivated the installation. This appear if the installation status is inactive.
readOnly: true
example: NOT_ENTITLED
id:
type: string
description: The unique identifier of the installation.
format: uuid
readOnly: true
example: 123e4567-e89b-12d3-a456-426614174000
metadata:
type: object
additionalProperties:
type: object
description: Additional information about the installation.
example:
key: value
description: Additional information about the installation.
example:
key: value
resource:
type: string
description: The resource that the installation is for.
readOnly: true
example: urn:pleo:company:123e4567-e89b-12d3-a456-426614174000
status:
type: string
description: This can be one of InstallationStatus values
example: ACTIVATED
updatedAt:
type: string
description: The date and time when the installation was last updated.
format: date-time
readOnly: true
example: '2021-01-01T00:00:00Z'
InstallationStatus:
type: string
description: '
| Value | Description |
| ------ | ----------- |
| ACTIVATED | The installation is active and operational. |
| INACTIVE | The installation is inactive and not currently in use. |
| AUTHORIZED | The Pleo authorisation server has authorised the user, but the installation is not yet active or ready for use. |
| PENDING_INTEGRATION | The integration is synchronising or performing other background tasks. When an installation is in progress, the integration synchronises the user''s Pleo account with the target application, so that tax codes, tags, and vendors are all similar in both Pleo and the third-party application. |
| ERROR | The installation has encountered an error and is not operational. An error code will be provided to explain the reason for the error. |'
enum:
- ACTIVATED
- INACTIVE
- AUTHORIZED
- PENDING_INTEGRATION
- ERROR
CreateClientInstallationRequest:
type: object
properties:
metadata:
type: object
additionalProperties:
type: object
description: Metadata associated with the installation. This can be used to store additional information about the installation, for example external references, but it is not used by any Pleo system.
example:
externalConfigurationId: '123456789'
description: Metadata associated with the installation. This can be used to store additional information about the installation, for example external references, but it is not used by any Pleo system.
example:
externalConfigurationId: '123456789'
status:
$ref: '#/components/schemas/InstallationStatus'
securitySchemes:
bearerAuth:
type: http
description: 'JWT Bearer token authentication. Include the token in the Authorization header as: `Bearer <token>`'
scheme: bearer
bearerFormat: JWT
basicAuth:
type: http
description: Basic HTTP authentication using API key. Use your API key as the username and leave the password empty. The credentials will be Base64 encoded automatically.
scheme: basic