This tutorial explains how Pigello integrations are structured, and how activation and permissions work.
An integration in Pigello is built in three layers:
| Layer | Description |
|---|---|
| Application | The top-level container (e.g. your product or internal tool). |
| Service | A capability offered under that application (e.g. "Verification Syncing", "Supplier Invoice Syncing"). |
| Service version | A specific version of that service, with its own permissions and configuration. |
When a customer activates an integration, they activate a specific service version of a service. The activation level (tenant, real estate, company, etc.) defines the scope of data the integration can access.
For each service, it is predefined at which level in the system the integration is activated. The possible levels are:
- Tenant — Per tenant.
- Organization user — Per organization user.
- Real estate — Per real estate (e.g. objects.realestate).
- Company — Per company (e.g. organization.company).
- Organization — Per organization (e.g. sales.organization).
This is often referred to as activation level. It corresponds to the scope of data your integration can access and to how the customer must activate it (e.g. per company, per real estate).
Example: If the service is activated at company level:
- The integration only has access to data that belongs to the company it is activated on.
- The customer must activate the integration separately for each company (e.g. Company A and Company B each have their own activation).
- List calls and other API access are scoped to that company (e.g. when querying all bookkeeping verifications, only those belonging to the given company would be returned).
Service versions follow these rules:
- New versions do not replace old ones. When you change attributes of a version (e.g. permissions, description), you must create a new version. The previous version remains as-is.
- Customers are not upgraded automatically. If a customer has activated version 1, they continue on version 1 until they deactivate it and activate the new version themselves.
- Deprecating a version: You can mark a version as deprecated. Deprecated versions remain active for existing activations, but users can no longer choose them for new activations.
- Limit on active versions: A service can have at most 3 non-deprecated (active) versions at a time.
- One version per activation scope: For a given activation object (e.g. a specific company or real estate), only one version of that service can be activated at a time.
Each service defines which entity types it needs and what operations it may perform:
- Read — The integration can read and list the entity.
- Create — The integration can create instances of the entity.
- Update — The integration can update instances of the entity.
- Delete — The integration can delete instances of the entity.
This is configured per entity type. The information is shown to the user who activates the integration. The activating user must have at least the same permissions that the integration is requesting (e.g. if the integration needs "read + create" on invoices, the user must have that level of access).
Each service declares whether it requires personal information or not. This is shown to the user who activates the integration.
If the service does not require personal information:
- It can still access entities that contain personal data (e.g. tenants, contacts).
- Attributes considered to contain personal information are omitted from all API responses for that integration.
If the service does require personal information:
- The activating customer chooses how individuals consent to sharing their data with the integration. The options are:
- Require accept for all users — Each user must explicitly accept before their personal data is shared.
- Auto accept for pre-existing users, require accept for new users — Existing users are treated as consented; new users must accept.
- Auto accept — Consent is assumed (e.g. when it is covered by lease or contract).
If consent is required and the user has denied or not yet responded, the user and related entities can still be retrieved via the API, but all attributes that contain personal information are omitted from the response.
An integration can be marked as private at the application level. Typical cases:
- Your own integration — You are the customer and the integration is only for your own use.
- In development — You are building the integration and do not want it publicly listed yet.
How it works:
- The private flag can be changed over time (e.g. you can make a private integration public when it is ready).
- The accounts the integration is shared with can be changed over time.
- A private integration is shared with:
- The maintaining party (e.g. your development account in Pigello).
- An agreed set of accounts (e.g. your sandbox or test accounts in Pigello).
If the integration is private:
- It is only visible in the integration gallery when you are logged in with an account that the integration is shared with.
- It can only be activated by accounts that the integration is shared with.
An integration can be configured to allow for specifying values for variables, during activation of the integration, that can then be read by you:
How it works:
- When you register your application service, you configure potential activation variables, their names, description, types, choices, and some validation.
- When the user activates the integration, they get prompted to fill out values for these activation variables, and for the ones marked as required they are forced to enter values.
- When authenticated with credentials corresponding to the activation of your integration, you can find the entered values for these activation variables eg. through the profile endpoint.
To use the Pigello API as an integration, you must register it with Pigello. There are two registration paths, depending on what you already have.
For more details on how this process works, see the tutorial Setting up an application
| Topic | Key point |
|---|---|
| Structure | Application → Service → Service version. Customers activate a specific service version. |
| Activation level | Defines scope (tenant, real estate, company, organization, etc.) and how the customer activates. |
| Versions | New versions are additive; max 3 active versions; one version per activation scope; deprecation available. |
| Permissions | Per-entity read and optionally create/update/delete; personal-information requirement and consent options. |
| Activation variables | Configurable variables that the user can (or must) enter values for during activation. |
| Private | Application-level flag; visibility and activation limited to shared accounts. |
For concrete API usage and endpoints, see the API Reference and the case guides (e.g. bookkeeping data, debt collection, My Pages).