DocumentationAPI Reference
Documentation

Recipients

Understanding Recipients

Recipients represent a unique entity you are exporting data to with Prequel. Recipients most often represent a customer, but there may be use cases to represent a recipient as a unique tenant within a customer account, such as a project. For more on tenanting strategy with Recipients, continue reading below.

Every Prequel Destination is required to have a Recipient, which defines what data models and product(s) a customer should receive.

What is id_in_provider_system

id_in_provider_system refers to the recipient's identifier by which data will be filtered per organization. In other words, it is the link between a Prequel Recipient and the corresponding identifier in the data source. The value assigned to this key will be matched against the values under the organization_id column provided for every table.

Resolving Multiple Recipients and Destinations

Prequel enforces a key rules on uniqueness of Recipients and Destinations:

  • Multiple Recipients cannot point to the same Destination. Prequel's change detection logic relies on guarantees of a destination's state on any given transfer, such that writing data multiple recipients' data to the same table can cause non-deterministic transfer behavior.
    • To write data from multiple recipients to the same database or warehouse, it is required that one Prequel Destination is defined for each Recipient, where each Destination must have a unique schema to avoid collisions.
  • Each id_in_provider_system must be unique.

Using schema-based tenanting

Prequel supports schema-based tenanting. To add a destination using schema-based tenanting, a recipient object with the correct schema identifier needs to be configured before the destination is created. Read more about multi-tenancy in Prequel here: Multi-tenancy.

Updating Products for a given Destination

When adding a Destination for a given Recipient for the first time, Prequel provides a helpful shortcut to abstract away the need to create the Recipient beforehand (that is, if a Destination is created with a id_in_provider_system that has not been used, the Recipient with that id_in_provider_system is created behind the scenes).

However, when Products need to be updated for a Recipient, that update must happen on the Recipient object, using the PATCH /recipients/{recipient_id} endpoint.

Using Role-Based Access Control on a Source

Prequel supports using specific source users for a given recipient's data. To add a specific set of credentials that should be used to access source data for a given recipient, you can use the POST /recipient-source-credentials endpoint.