# PK Mapping

This tutorial explains the **concept of mapping primary keys (PKs)** between Pigello and other systems, and how to use **Integration Service ID connections** in Pigello to store and use those mappings.

## Why map PKs?

When you integrate Pigello with another system (e.g. your own ERP system, Bookkeeping system, or tenant portal), you often need to **correlate entities** between the two:

- A **tenant** in Pigello might correspond to one or many **user(s)** or **account(s)** in your portal.
- Multiple **verifications** in Pigello might correspond to one **invoice** in your portal.


Each system has its own **primary keys**. To avoid duplicate syncs, to look up the right record on each side during update/delete, or to support other workflows that span both systems, you oftan want a **mapping** between Pigello Pks and external PKs.

## Integration Service ID connection

Pigello offers a generic way to store these mappings: **Integration Service ID connections** ([integrations.integrationserviceidconnection](/apis/integrations)).

For each mapping you create a **connection** that links:

- **Pigello side:** `content_type` (e.g. `accounting.verification`) and `object_id` (the UUID `pk` of the entity in Pigello).
- **External side:** `external_id` (the `pk` of the entity in your other system—stored as a string, so it can be a UUID, numeric ID, or any type of identifier that the external system uses).


So: *this Pigello entity (content_type + object_id) corresponds to this external entity (external_id).*

## Many-to-many support

The model supports **M:N (many-to-many) mappings**:

- **One Pigello entity → many external IDs:** One item in Pigello can be linked to multiple items in other systems (e.g. one tenant in pigello corresponding to multiple tenants in another system).
- **Many Pigello entities → one external ID:** Multiple Pigello items can point to the same external ID if your use case requires it.


You create one connection row per (Pigello entity, external entity) pair you want to track.

## Unique constraint and use as a lock

There is a **unique constraint** on (`external_id`, `content_type`, `object_id`) **per application service**. So for a given application's service:

- You cannot create two connections with the same `external_id`, `content_type`, and `object_id`.
- This prevents duplicate mappings and allows you to use the connection as a **lock**: for example, "this external ID is already linked to this Pigello object," so you can avoid creating a second link or double-syncing.


## Visibility across services

**All services under the same application** can **view each other's** Integration Service ID connections. So if your application has multiple services (e.g. "Bookkeeping sync" and "Reporting"), they can all read (and, where allowed, create) the same set of connections. That way you can share PK mappings across services within one application.

## How to use it

1. **Create connections** when you sync or link an entity: after creating or identifying the entity in the other system, POST a new [integrations.integrationserviceidconnection](/apis/integrations) with the right `content_type`, `object_id`, and `external_id`.
2. **List connections** to resolve "what Pigello ID goes with this external ID?" or "what external ID goes with this Pigello ID?" Use the list endpoint with filters (e.g. by `content_type`, `object_id`, or `external_id`) as needed. See the API Reference for the list endpoint and filters.
3. **Respect the unique constraint** when creating: if a connection already exists for the triple (external_id, content_type, object_id), you will get an error; use that to avoid duplicates and to implement locking if needed.


For a concrete example of creating connections (e.g. "mark verifications as synced"), see the [Bookkeeping Data](/guides/cases/bookkeeping-data/) implementation example, which uses Integration Service ID connections to record synced verifications.

## Summary

- **PK mapping** links Pigello entities to entities in other systems.
- **Integration Service ID connection** stores: `content_type` + `object_id` (Pigello) and `external_id` (your system).
- **M:N** is supported: one Pigello item can map to many external IDs, and vice versa.
- **Unique** per application service on (`external_id`, `content_type`, `object_id`)—no duplicates, usable as a lock.
- **All services under one application** can see each other's connections.
- Create connections when you sync or link; list and filter them to resolve IDs on either side.