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.

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

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