No & Low Code Solutions
Copy/paste options for low-code Activity API Use
In this section
Need help? Email us at support@villagelabs.co.
Using Google Sheets and an Apps Script
Using an Airtable automation
Using Hubspot Workflows
Background
When you integrate with the Village API, Village listens to user activities like actions or transactions on your platform that are associated with Triggers you've created. When these activities occur, rules are then triggered and Village takes action according to relevant rules logic.
By contrast, this page explains how to pass user activities to Village without an API connection using low-code or no-code solutions like Google Sheets and a Google Apps Script, Airtable automations, and Hubspot Workflows. This will allow you to send relevant user activities (eg. events, actions, or transactions) to Village and effectively replicate the function of the API. These user activities are then able to trigger rules and cause output operations to occur in Village.
Using Google Sheets
Please read: When you are connecting to Village through our Google Sheets Solution, you are interfacing directly with Village's APIs when you run the scripts in Sheets. It is therefore extremely important that you read the relevant API documentation for each script below. This will tell you the correct format to input data (for example, the Associated Users input is case sensitive) and what each command does. In parallel, you should also read the instructions below for how to operate the sheets, and anything you should be aware of.
This will allow you to populate a sheet with relevant user activities (eg. events, actions, or transactions), and then run a script to pass them through to Village (effectively replicating the function of the API). These user activities are then able to trigger rules and cause output operations to occur in Village.
Go to our Google Sheet Example and File -> Make a Copy. Save this copy in your company drive.
Warning: If you use this method, we highly recommend limiting access to this spreadsheet to ensure your API key remains private.
Script Setup
In the Settings tab, paste your API Key to replace "YOUR_API_KEY" in B3. Do the same with "YOUR_NETWORK_ID". You can find both items by navigating to Village's Side Menu -> API Keys.
Go back to the Google Sheet. Navigate on the menu bar to Google Sheets -> Extensions -> Apps Scripts.
When you make a copy of the spreadsheet, the Apps Script should also copy and appear when you open Apps Script.
Important: You may be asked to provide read/write access to this script by Google because this script needs those permissions to run. Ensure you're logged in to the proper Google account before approving permissions.
Run a Test
Pay attention to the amount field: most of the time, the amount field is going to be set to 1, since 1 event or activity of that type occurred. If you have a rule in Village that pays $50 when a task is completed, the rule will multiply the task activity amount (1) by $50 to calculate the payout. In this case, if you entered 50 in the activity amount field, this would result in a payout of 50 * $50 = $2500!
The exception to this rule is when you are configuring sales triggers. In this case, the amount field should be the total amount of the transaction or sale, eg. 500 if it was a $500 sale. For example, if a rule pays 1% cash back on each sale, it would multiply the rule amount field (.01) by the sales activity amount field ($500) to get a cash back of $5 for that sale.
We recommend running tests BEFORE trying in production. To run a test, set up a test program similar to what's in the Admin Quickstart ->.
Next, go to the "Inputs" tab. You can input some number of activities as tests. Make sure you use the correct Short ID for the Activities submitted (find in the Village Side Menu -> Triggers page) and the user_1_type matches a valid User type (which can be found on the same Trigger Detail page).
The sheet supports up to two user types. If you need to use this for Activities with more users, email us at support@villagelabs.co.
The activity_timestamp is required if you have an activity_timestamp column in your spreadsheet. It must be in Unix Timestamp format. You can use this website to translate human-readable date/times to unix timestamps, or the input in the furthest to the right column.
You can also delete the activity_timestamp column, in which case Village will consider the time and date that the activities were received through this process as the time and date at which the activities occurred.
Warning: Columns A & B (Status & Response) are used to ensure that already submitted data does not get resubmitted.
If you are adding additional data below already submitted data, and do not want previous rows to be resubmitted, do not delete the Status & Response for previous submissions from Columns A & B.
If you are adding all new data, make sure you delete old Status & Responses from Columns A & B otherwise your new data will not be submitted properly. "
Sheet example:
Warning: do not change the order of the columns, as this will prevent the Apps Script from functioning correctly.
Once you're done testing to ensure you're hitting the API successfully, you may begin using this sheet for submission of real Activities to the Village Activity API.
Warning: all inputs are case sensitive. This means that if your activity_short_id is 'item-sold', activity will not log for this trigger if your activity_short_id is 'Item-Sold'
In this case, 'item-sold' will still successfully log as an activity when you submit it to Village, but it will not associate with any trigger and therefore not activate any rule.
Does a success message in the spreadsheet mean the activity was successfully logged? Not necessarily! A success message received in the sheet does not always means that the activity was logged successfully. There are a few cases - like when you submit the wrong user type associated with a trigger - where the data will be sent successfully to the API, but the activity will not submit successfully because the user type is incorrect.
Therefore, you should always review the API Results table in Side Menu > API > API Results to confirm that your activity successfully submitted.
Using Airtable Automations
Note: You'll need a Airtable Pro plan to access scripting.
You can connect any existing tables you like, but for our purposes we're going to create a simple table that has Activity ID (which will match your Village Trigger Activity ID), Amount, Buyer, and Seller.
For this example we'll pretend we have two different users associated with this activity. Buyer and Seller.
Go to Automations in the top bar. Our goal will be to send new Activity to Village whenever a new record is added to this table, but you can select any trigger you need.
Now select Advanced Logic or Action -> Run Script.
Now you'll want to copy and paste the code snippet below into the Airtable Script Editor (see screenshot).
Airtable Automation Code Snippet to copy/paste.
You'll need to edit two things before running it.
First, change YOUR_NETWORK_ID to the short Network ID, and the YOUR_API_KEY to your API Key. You can find both of these items in Village through Side Menu -> API Keys.
Warning: Ensure that you closely manage access to your Airtable script to keep your API Key secret and secure!
Using HubSpot Workflows
This method uses webhooks in HubSpot's Workflows automation. This requires at minimum the Operations Hub Professional plan.
This section covers sending data and information from HubSpot to Village. We'll cover how to send data from Village to HubSpot separately (eg. how to send information from Village to HubSpot in order to send incentives comms to HubSpot contacts).
HubSpot workflows allow you to create trigger-based rules when defined criteria are met or events happen within HubSpot.
One action that HubSpot can take when a HubSpot trigger occurs is to send data to Village through a webhook. Effectively this allows you to do anything you'd be able to do with Village's APIs in a no-code way, including triggering rules in Village based on activity, updates, or properties in HubSpot such as contacts or deals being created, deals progressing through different stages, sales revenue generated, contact properties being updated, or even updating segments in Village based on HubSpot lists.
Create a workflow
Inside your HubSpot account, navigate to Automation > Workflows > Create workflow
Select the trigger type for your Workflows. If you are triggering rules within Village based on individual user information such as a user being created, changing status, progressing through the funnel or some other characteristic, you're likely going to create a Contact-based workflow, however there are many other workflows you can create around deals, tickets, or conversations.
In this example, we're going to distribute points-based incentives in Village to sales team members based every time they generate a new qualified lead in HubSpot.
Select Contact-based > Blank workflow > Next
We're going to use the contact's lead status changing to a defined value "Open Deal" as the trigger, but there are hundreds of different events, properties or actions you can use as a trigger to send data to Village.
Set up triggers > when an event occurs > Property value changed > Lead status is any of 'Open Deal' > Apply Filter > No, only enroll each contact once (since we only want an incentive to be issued the first time this activity occurs) > Save
Send data to Village when the trigger occurs
Next, we're going to set up a webhook as the action that takes place when the trigger occurs in HubSpot. This webhook will send data to Village's Activity API whenever the trigger occurs in HubSpot.
Click "+" > Choose an action > Workflow > Send a webhook
You'll need to set up your webhook with the following configuration:
Using the Village User Status & Segments APIs with HubSpot
The above example shows the HubSpot webhook configuration for sending activity data to Village through the Activity API. As discussed, you can also create users in Village, and add or remove users from Segments in Village using the same Automations flow in HubSpot. Instead of sending data to the Activity API when a trigger occurs in HubSpot, we're going to send data to Village's User Status API as well as the Segments API.
In this example, we're going to create a user in Village when a new contact is added in HubSpot, and then we're going to add them to a segment in Village called 'New Users'.
The setup is largely the same as above:
Select Contact-based > Blank workflow > Next
We're going to use a CRM object being created as the trigger. We're also going to add a refinement filter to limit the CRM object creation to a new contact.
Set up triggers > when an event occurs > CRM object created > Add refinement filter > Lead Status > is any of "New" > Apply filter > Save filters > No, only enroll each contact once (since we only want an incentive to be issued the first time this activity occurs) > Save
Send data to Village's User Status API when contact is created
Next, we're going to set up a webhook as the action that takes place when the trigger occurs in HubSpot. This webhook will send data to Village's User Status API (the API that adds and/or invites users to your network in Village) whenever this trigger occurs in HubSpot.
Click "+" > Choose an action > Workflow > Send a webhook
You'll need to set up your webhook with the following configuration. Remember to change the URL to point at the Village User Status API versus the Activity API :
This will create a new user in Village when a new contact is created in HubSpot.
If you also want to send an email invitation for this user to access the Village user dashboard after the user has been created, add an additional webhook action after the first action by clicking the "+" icon below your first webhook action. Then use the same setup as above, but a different status_change value to send_invite.
Send data to Village's Segments API to add contact to a Segment in Village.
Next, we're going to add this new user to the "New Users" segment we've set up in Village. The Segment ID of this segment is "2".
This webhook will send data to Village's Segments API (the API that adds and/or removes users from a Segment in Village) whenever this trigger occurs in HubSpot.
Click "+" > Choose an action > Workflow > Send a webhook
You'll need to set up your webhook with the following configuration. Remember to change the URL to point at the Segments API:
One important note: adding a user to or removing a user from a Segment using the Segments API overrides any other rule logic created in the admin dashboard in Village. That means that if you use the Segments API to add a user to a Segment, that user will remain in that Segment, even if they qualify for future rules logic that would otherwise remove them from this Segment.
If you do not want rules logic to be ignored after using the Segments API, ensure you send a subsequent 'reset' message to the Segments API. See more here. To do this, add another webhook after the first request to the Segments API:
Click "+" > Choose an action > Workflow > Send a webhook
Then use the following Request body configuration:
Last updated