Quickstart Guide
Using Census Embedded features like Census Connect requires your Census account be configured as an embedded usecase. If you’d like us to set this us please contact support.
This guide assumes you have a solid understanding of reverse ETL and Census’ core concepts. If you’re still new to all of this feel free to learn more by browsing our product docs or feel free to schedule a demo with a member of the Census team and we’ll gladly get you up to speed.
Use this guide to learn how to set up your Census Embedded solution for success, whether you’re just starting out or looking to ensure you are following best practices before going to production.
All Census Embedded solutions will require understanding and implementing some solution for each of the four following steps. It’s often possible to achieve these steps either manually via the Census management UI or programatically via the management API. In these cases, both approaches are documented. Feel free to start manual to get started and then automate away that step of the process as you scale your solution.
1. Creating a Workspace
In order to keep your customers’ data separate and organized, you’ll want to create a separate workspace for each customer. This can either be achieved via the Census UI or via our workspace management API. Once your customer-specific workspace is created, you’ll need to extract the API Key from
From the UI
From the API
Getting started by creating new workspaces for your customers manually is very reasonable and easy. We recommend playing around with this approach for your first few customers to quickly prove out the more complex parts of your Census Embedded solution.
Initiate Workspace Creation
Start by going to the Organization Dashboard and then click on the ‘New Workspace’ button. Org Dashboard
Name and Create Workspace
Give your workspace a name, preferably one that identifies the customer you’ll be using it for, and then press the ‘Create’ button.
Fetch the Workspace API Key
You may want to fetch the new Workspace’s API Key to plug into your system for further automation. To do so, navigate to the new workspace’s settings page and copy the API Key. Make sure you store it somewhere secure alongside the customer details to which it applies.
2. Connecting a Source
To sync your data to your customers’ apps, you’ll need to create a source connection so that you can then create models or segments to power your syncs. Since the nature of the data will be very specific to your Embedded usecase, this guide will not be prescriptive about what kind of source object (model, table, segment) you should use. Please work closely with our success team in desiging your solution or if you have any questions. You can create a new source connection either via the UI or via API.
We recommended creating unique users or roles to access your data source for each unique customer to eliminate the risk that you’ll send one customer’s data to another customer’s destination since source connections are not accessible across workspaces.
From the UI
From the API
Getting started by creating new source connections manually from the Census UI is a common approach as you are proving out & exploring your Census Embedded solution. If you have a low number of total customers, it might even be the right fit long term.
Start Source Creation
From the sources page in the Census UI, select “Add a Source”, search for your source type, and select “Next”.
Configure Source
To create a new source connection via the Census management UI, refer to our product documentation on the matter. Make sure you understand the implications of the different Sync Engines offered and then look into the specific nuances of your data warehouse such as Snowflake, Google BigQuery, or Amazon Redshift.
Complete Source
Once configured, Census will test the connection to make sure it’s configured properly. Once complete, select “Finish” and your source is connected!
3. Connecting a Destination
For any Census Embedded solution, you will need to gather your customers’ credentials securely for the apps where you want to sync your data. Like all the steps in this guide, you can do this manually via the Census UI or via the API. In both cases, you’ll likely want to leverage Census Connect, a client-side component that your customers will interact with in order to authorize your their destination so that you can sync data into it.
The Census Connect experience is only enabled via the UI & API if your account is enabled for Census Embedded. To have us enable this in your account, please reach out.
From the UI
From the API
Generating Census Connect authorization links for destinations via the UI is not commonly used as a long term approach for true Census Embedded customers but it can be useful when starting out to get a feel for the user experience your customers will experience or to get started with your first few customers manually.
Generate Census Connect URL
From the destinations page in the Census UI, select “Add a Destination”, search for the destination type your customer is hoping to connect, and select “Next”. Generate the Census Connect URL with the “Create link” button.
Navigate to the Census Connect URL
You can now copy the Census Connect URL and either send it to your customer via Slack or in an email. Feel free to check it out yourself too.
Complete Authorization of Destination
Your customer (or you) should then go through the Census Connect authorization flow with the destination. The Census Connect UI will handle gathering all the required credentials for the destination whether it requires an OAuth flow or specific credentials like an API key and will then perform a series of automated tests against the destination. Once complete, the new destination connection will be available for use on the destinations page or via the destination management APIs.
4. Configuring and Running a Sync
Now that you have created a workspace for your customer’s data, connected a source, and authorized their destination, you are ready to start syncing your data to your customer! Please take the time to familiarize yourself with the core Sync concepts before proceeding.
From the UI
From the API
Creating syncs for a Census Embedded solution from the Census UI alongside your first few customers can be valuable to understand what types of field mappings your customers will want in your product solution. To create a sync from the Census UI, follow the following steps:
You can also invite your customers directly to your Census organization and make use of our role-based access controls (RBAC) to ensure they only have access to their designated workspace so that they can self-serve this process. The Editor or Operator role typically works well here. This kind of multi-tenant setup can work long-term as well, removing the need for you to handle all possible cases in your Census Embedded setup. Role-based access controls are available on our Enteprise plan.
Start Sync Creation
From the Syncs page, select “New Sync”. Then on the new sync creation screen, select the source object, destination object, and sync behaviour you want. Here is an example of a sync that will upsert records into Hubspot Contacts directly from a users table in a Redshift database.
Configure Sync
Next, configure the sync key and the appropriate field mappings for your sync. Feel free to run a test at this time to ensure the sync can run successfully.
Save and Run
Finally, save your sync. You can now run your sync for the first time and, assuming everything looks good upon completion, you may want to set up a schedule for the sync to run. You can also trigger syncs via the API and can return to this screen to edit the sync’s settings at any time.
