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

# Sync Overview

The syncing endpoints are designed to treat your business and customer data as
the source of truth. If you have a unique identifier for business or customer
within your vertical software, you can provide that as the `external_id` on
every request and Pocketflows will create or update the record to match and
return the Pocketflows ID as well.

All of these new endpoints adopt a "create or replace" strategy. When
`external_id` is provided in the API payload, if no existing record is found
with the `external_id`, a new record is created. When an existing record is
found, then its properties are wholly replaced by the new ones.

<Note>
  This also blanks out properties that are not provided in the request, so it is
  important to pass all properties in every sync request.
</Note>

The new sync endpoints allow either `external_id` or `id` (the Pocketflows ID)
to be passed. `id` takes precedence over `external_id` and will be used to find
the record. When both `id` and `external_id` are passed, the record is first
found via the `id` then the `external_id` is updated to whatever is passed
(along with all other fields)

Batch endpoints allow for partial success: when a business / customer record is
invalid for whatever reason, the rest of the request will process and create /
replace the other records synced.

## Migrating from previous business and customer creation and updating

If you are using any of the following endpoints to create or update businesses
and customer, you can migrate to the new syncing endpoints.

* `POST /businesses`
* `POST /businesses/:id`
* `POST /businesses/:id/customers`
* `POST /businesses/:id/customers/batch`
* `POST /businesses/:id/customers/batch_update`
* `POST /customers/:id`

Migration will generally look like the following:

1. Move business creation and updating to `POST /sync/businesses` (for single
   updates / creates) and `POST /sync/businesses/batch` (to update multiple
   businesses at once, previously not possible!). Crucially, pass both `id` and
   `external_id` so that Pocketflows can associate the existing `id` with the
   new `external_id`
2. Move customer creation and updating to `POST /sync/businesses/:id/customers`
   (for updating or creating a single customer) or
   `POST /sync/businesses/:id/customers/batch` (for updating all the customers
   of a business). Again, be sure to pass both `id` and `external_id` so that we
   can associate the IDs together.
3. At some point in the future when all Pocketflows businesses and customers
   have the correct `external_id` associated, you can stop sending `id` as part
   of the payload.

If you have any uncertainty, please reach out to the team at
[team@pocketflows.com](mailto:team@pocketflows.com)