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

# Synchronize partners

> How to link your customers and suppliers to the clients and suppliers of your end-users' accounting software.

Invoices, journal entries and payments reference their client or supplier in the accounting software with `partner_id`. This guide explains how to link each customer and supplier of your software to a [partner](https://docs.chift.eu/unified-apis/accounting/concepts/partner.md) of the accounting software, and how to keep this link up to date. The same logic applies to clients and to suppliers.

## 1. Load the partners

When the end-user connects their accounting software, fetch all the partners:

* [Get clients](https://docs.chift.eu/api-reference/endpoints/accounting/get-clients.md) for your customers.
* [Get suppliers](https://docs.chift.eu/api-reference/endpoints/accounting/get-suppliers.md) for your suppliers.

Fetch every page of the result. See [Pagination](https://docs.chift.eu/unified-apis/guides/pagination.md). Store the partners on your side.

## 2. Match your partners

For each customer or supplier of your software, look for its partner in the accounting software. Chift advises the criteria below, in this order. Compare each criterion with all the partners before you try the next one: the most specific criterion wins.

1. **Existing link.** You already stored the `id` of the partner for this customer or supplier. Reuse it.
2. **Partner code.** Compare the code of your customer or supplier (for example, its account number in your software) with `third_party_account` and with `external_reference`. Compare your own reference with `external_reference`.
3. **Company number.** Compare it with `company_number`.
4. **VAT number.** Compare it with `vat`. Compare the company number first: the members of a VAT group share one VAT number.
5. **Name.** Compare it with `third_party_account` and with `external_reference`. For an individual, compare the full name (first name and last name) with the full name of the partner.

Follow these rules:

* Compare only the active partners (`active` is `true`).
* For the company number and the VAT number, remove the dots and the spaces, and ignore the case. For example, `BE 0123.456.789` matches `BE0123456789`.
* For the partner code, remove the spaces and ignore the case. Some accounting software pads the code with trailing zeros: compare the codes without them.
* An empty value never matches.
* Do not match on the `account_number` of the partner. It can be a shared control account, used by many partners.

When a partner matches, store its `id` with your customer or supplier. Send this `id` as `partner_id` on every invoice or entry for this customer or supplier.

## 3. Create the missing partners

When no partner matches, create it before you book its first invoice:

* [Create client](https://docs.chift.eu/api-reference/endpoints/accounting/create-client.md) for a customer.
* [Create supplier](https://docs.chift.eu/api-reference/endpoints/accounting/create-supplier.md) for a supplier.

Send at least:

* `name`: the name shown in the accounting software. For an individual, set `is_company` to `false` and send `first_name` and `last_name`.
* `addresses`: the list of addresses. Each address needs `address_type`, `street`, `city`, `postal_code` and `country`.

Also send the data that helps the next match: `vat`, `company_number` and `external_reference` (your own identifier of the customer or supplier).

Store the `id` of the created partner, as for a match.

Some accounting software keeps clients and suppliers in one list. When your customer is also a supplier there, send the `id` of the existing supplier in the `force_merge` parameter of Create client (or the `id` of the existing client in Create supplier). The accounting software then merges the two.

> [!NOTE]
>
> Some accounting software cannot create partners through the API. For these connectors, send the partner with `partner_info` on the invoice. See [Create invoices](https://docs.chift.eu/unified-apis/accounting/concepts/invoice/create-invoices.md#2-link-your-customers-and-suppliers).

## 4. Keep the partners up to date

Partners change in the accounting software: the accountant creates, edits or deactivates them. Refresh your stored partners at regular intervals:

* Pass the date of your last refresh as `updated_after`. The API returns only the partners created or updated after this date. See [Incremental synchronization](https://docs.chift.eu/unified-apis/guides/incremental-synchronization.md).
* To look up one partner, use the `search` parameter. It filters on `name`, `email`, `first_name`, `last_name`, `external_reference`, `vat` and `company_number`.

Not every connector supports `updated_after`. Without it, fetch all the partners again and compare them with the partners you stored. Check the [coverage matrix](https://docs.chift.eu/connectors/accounting/coverage.md).

## 5. Handle a deleted partner

If someone deletes a partner from the accounting software, the creation of its invoices fails. Remove the stored link, then match the customer or supplier again ([step 2](#2-match-your-partners)), or create the partner again ([step 3](#3-create-the-missing-partners)).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.