Integrating Census with Candu: Setup Guide

Prerequisites

Before you begin, you'll need:

A Census account with access to your data source
A Candu account with API access
Your Candu API key (found under Settings > Workspaces)

This Census to Candu guide uses the Census' HTTP request docs.
To follow this guide, see this google doc with sample data.

Step 1: Add Your Data Source to Census

Before setting up the integration, you'll need to add a data source to Census:

Log into your Census account and navigate to the Sources page
Click "New Source" and select your data source from the list
- For this example, we'll use Google Sheets
Follow the connection steps for your selected source
Share your Google Sheet with the service account email provided by Census

Step 2: Create an HTTP Request Destination in Census

Log into your Census account and navigate to the Destinations page
Click "New Destination" and select "HTTP Request" from the menu
Name your destination (e.g., "Candu Integration")
Enter the Base URL for the Candu API: https://api.candu.ai/api/

Step 3: Add Your Candu API Key

Retrieve your Candu API key from Settings > Workspaces in your Candu account
In the Census destination setup, click "Add Header"
Name the header Authorization
For the value, enter YOUR_API_KEY with your actual Candu API key)
Check the box indicating it's a secret
Click "Connect" to continue

Step 4: Create a New Sync

Navigate to the Syncs page in Census and click "New Sync"
Select your data source (e.g., Redshift, Snowflake, BigQuery, etc.)
- You can use our sample Google Sheet as a reference for the required fields
Select the HTTP Request destination you just created
For the endpoint, enter eventWebhook
Choose your trigger method (typically "rows_added/rows_updated")
Specify the number of records in each request: One record per request

Step 5: Create your Payload Template

Configure your payload template:

Select a sync key (typically your unique user identifier)
Choose "POST" as the HTTP method
Select "JSON" as the payload type
Choose "Template" for the JSON subtype

Define the JSON payload:

Use the following template for the payload, adjusting field names as needed to match your source data:

{
      "type": "identify",
      "userId": "{{ record['UserID'] }}",
      "traits": {
        "email": "{{ record['Email'] }}",
        "role": "{{ record['Role'] }}",
        "OrgID": "{{ record['OrgID'] }}",
        "HRIS Integration": "{{ record['HRIS Integration'] }}",
        "isEditor": {{ record['Editor'] }}
      }
    }

The payload by data type

Different data types require specific syntax in Census's liquid templating to ensure proper formatting when sent to Candu's API. Below are examples for common data types:

Strings

"account_name": "{{ record['ACCOUNT_NAME'] }}",

Numbers:

"current_seat_count": "{{ record['CURRENT_SEAT_COUNT'] }}",

Dates:

"test_date": "{{ record['Test Date'] | date: "%Y-%m-%dT%H:%M:%SZ" }}",

Step 6: Set your Rate Limit

Candu supports 2,000 requests per 10 seconds.

Set batch size to 1.
Set the Rate Limit to 200 per second

Step 7: Save and Run Your Sync

Click "Save" to create your sync
Run the sync to test the connection

Verification

You can verify that user data is being sent correctly by:

Log into your Candu account
Navigate to Users
Find a user that should have been synced
Drill down to see whether the traits (role, OrgID, etc.) match what you sent

Troubleshooting

If your sync isn't working as expected:

Check the API Inspector tab in Census to see the request and response details
Verify your API key is correct and hasn't expired
Ensure your payload template matches the expected format
Check that field names in your template match the column names in your source data

Rate Limits and Best Practices

Consider scheduling syncs during off-peak hours for large data sets

(Optional) Sync Group Traits to Candu

Groups can be synced to Candu, typically two types of call are used

Sync Group Traits

Set up a new Sync following steps 4-7 above.

Use eventWebhook as the target once again but with a Group payload as follows:

{ 
   "type": "group",
   "groupId": "{{ record['OrgID'] }}",
   "traits": {
        "name": "{{ record['Org Name'] }}", 
        "last_update": "{{ record['Last Updated'] }}"
    }
}

The traits above should be customized with your own data.

Sync Group Membership

Set up a new Sync following steps 4-7 above.

Use eventWebhook as the target once again. The payload template is as follows:

{ 
    "type": "group",
    "userId": "{{ record['UserID'] }}",
    "groupId": "{{ record['OrgID'] }}"
}

For additional help, contact [email protected]