Admin Quickstart

How to get started on Village in record time.

Note: These docs are still actively supported, but are considered Legacy as most of this content is no longer required by admins.

Looking for the Developer Quickstart? Go here ->

Quickstart: Administrators

This quick-start guide is for Village Administrators, and introduces you to the key concepts of the Village Admin Dashboard.

Here you will learn:

1. About Village and why you should use it

2. How to create a Network, the representation of your business on Village

3. How to Invite Users to your network

4. How to Customize your network

5. How to create your first Programs & Rules

6. How to make your first Data Connection to Village

The purpose of this guide is to get you set up in Village as quickly as possible.

We also recommend reading 'The basics of Village in 10 minutes'->, and other sections of this the Knowledge Base to understand Village in more depth.

To learn about Village through different use cases, you can also check out our Guides.

Creating and sending an incentive with Village.

Skip to the setup steps ->

What is Village?

Village is the brain of your business.

We turn any user on your platform into a power user by driving the right behavior at the right time.

Create and automate cash and non-monetary awards, credits, promos, referrals, goals, milestones, status, points, benefits, revenue share, and more — as well as powering the segmentation, comms and distribution of these incentives in the most efficient and effective way possible.

Village means more revenue, fewer costs, and, most importantly, a much stronger long-term relationship with your users.

A love story in the making

Creating an Admin Account

Village is invite-only. If you'd like an invitation to use Village, reach out to our team at [e-mail]

More about creating accounts ->

You will receive an email invite to Village:

Accept your invite

Click the link to accept the invite. You can log in through a third party or create an account with an email/password pair.

Create an account

You must use the email that received the invitation, otherwise you will not be authorized to create an account and Village Network.

Creating a Network

A Village Network is the representation of a business, organization, or platform within Village.

Your first step should be to create a Network.

You can only create one Network within Village by default. If you have any issues creating a network, or require additional networks, please reach out to [e-mail].

To create a Network, click on "Launch a Network."

Launch Network

Enter the required info:

Launching your network

Important: You cannot change your Unique Name once it's created. Although this is only used by your development team, please take care when creating it!

ID	Input	Description
1	Display Name	This is the user-facing name for your network, typically the name of your platform or company, e.g. "Nike."
2	Unique Name	This is a non-editable, unique identifier for your network. This will not be seen by users or customers, but will be used by your developer team to access the Village APIs. You cannot change this once your network is launched.
3	Description	This is a user-facing description, often the company description or tagline. It may be user-facing in some instances.

Review the information you've entered and click "I Want to Launch" when ready.

You'll be redirected to the Network Manager, your home base within Village, where you can invite users, create incentives, send communications, and manage the ongoing analytics of your network.

Invite Users

See more at User Access Management ->

There are two distinct user roles within your Village Network: 'Admin' and 'User.'

Admin Role

These are your team members. Admins have the ability to create and manage incentive structures, send comms, invite users, or configure your Network settings.

User Role

These are the end-users of your platform or business. Users could include customers, suppliers, workers, contractors, freelancers, etc. They can only access the End User Dashboard, which admins control the contents of.

User Access

Invite Your Team

Let's start by inviting your team members – your fellow admins.

Navigate to Side Menu -> Users -> Invites -> Add (+).

You can only add users of one type at a time. Select the Role you want to give (Admin for your team members), and enter as many emails as you like.

Once they're invited, they'll go through the same account creation process you did. But instead of creating a Network, they'll already have the option to "Manage Network" for the Network you invited them to.

Invite Your End Users

Bulk invites: Want to add a lot of users?

If you need to bulk invite tens, hundreds, or thousands of users at once, reach out to our team at [e-mail]. We'll work with you to backfill your existing user base.

To invite your end-users (suppliers, customers, partners, etc.), you can go through the same process, just make sure to set the role to "Member" instead of admin.

Automatically Invite Users: User Status API

For all non-admin users, you can skip manual invites and use the User Status API ->. This allows you to automatically invite your users to the Village Network.

This is typically the most efficient way to create users on an ongoing basis, such as auto-creating a Village account as soon as they sign up on your platform.

Customize Your Network

Bring your company's brand to Village! You can:

1. Change the color scheme of the end-user dashboard

2. Edit your user-facing Network name

3. Add a company logo that will appear on the admin and end-user dashboards

   1. We recommend a logo with a white background. Logo must be 2:1 (e.g. 250 px by 500 px) for best results.

Click the pencil icon on the Network Manager title widget to access Network customization features.

Create Your First Program

• Check out our Guides to learn through different use cases ->

• Knowledge Base for Programs & Rules ->

To get started, we will create a test Program. This program will create incentives for our team to have more fun. Here's the order of what we're going to do:

1. Create an Award: Fun Points
2. Create a Trigger: Dance Completed
3. Create a Program: Team Fun Initiative
4. Create a Rule: 1 Fun Point for per Dance Completed
5. [optional] Try it out

Creating Fun Points

Before we can create an incentive, we need something to award. First, navigate to Side Menu -> Incentives -> Awards -> Non-Monetary Awards -> New Non-Monetary Award. Don't worry - we can hide or delete these later.

Navigate to Non-Monetary Awards

Create some Fun Points

Create the "Dance Completed" Activity

Next, we need a user Activity that we want to award with Fun Points. Once we've set this up, we can use this Activity to trigger our Rule, and issue an Award (Fun Points).

Navigate to Side Menu -> Incentives -> Triggers -> Activities -> New Activity Trigger.

Create a New Trigger

Dances are fun

Create the Team Fun Initiative

More on the backbone of Village, Programs & Rules ->

Rules are the backbone of your Village automations. They execute output operations – like issuing Awards or adding/removing users from segments – based on business logic.

But first, all Rules need to be grouped by Programs. Navigate to Side Menu -> Incentives -> Programs -> Create New Program.

Program Overview -> Create New Program

Encouraging more fun

Creating Our First Rule

Now that we have a Program, I can navigate to Programs -> Draft Programs -> Manage Team Fun Initiative -> Create New Rule.

Now selecting from the dropdowns:

1. Name: Dance Award

2. Trigger Type: Action

3. Trigger: Dance Completed

4. Award: Fun Points

5. Amount: 1

6. Recipient: Primary Dancer

Creating a draft rule

Then click the launch 🚀 button on the Rule. Finally, launch 🚀 the Program (note: Programs are held in draft mode until they have at least one Rule ready to go live).

Test Your Rule! See Fun Points In Action.

Log a "Dance Completed" Activity to Trigger your Rule!

This section requires some light code using your terminal window, but this should be relatively straightforward, even for non-technical people.

To see your new incentive program in action, get an API key and send Dance Completed Activity to the Village Activity API.

Get an API Key

To get an API keys, navigate to Network Manager -> API Token and Documentation -> Create New Key.

Run a cURL Command to hit the Village API

Here's an example. Open the terminal window on your device, edit the cURL command below with your actual Network ID and API Key, then copy/paste it into the command line interface and log your own epic dance party!

//Replace 'YOUR_API_KEY' with your actual API key
//Replace 'YOUR_NETWORK_ID' with your actual Network ID 
//Replace 'YOUR_EMAIL' with your email

curl -X POST https://api.villagelabs.co/networks/YOUR_NETWORK_ID/activity \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
    "activity_short_id": "dance-completed",
    "amount": "1",
    "users": {
        "primary_dancer": "YOUR_EMAIL",
    },
    "metadata": {
        "reference_id": "abc123",
        "description": "It was an epic dance party."
    }
}'

See the Results

When the Activity is reported successfully, you'll see 1 Fun Point in your wallet.

Bonus: Creating Our First Comms

Village can automatically create personalized comms that explain how programs and/or rules work in a simple and engaging way your end users. These can be sent by Village on behalf of your platform, or through your existing 3rd-party CRM provider.

Here's an example of an email automatically generated based on the program and rule above:

Comms generated based on the rules you created.

This feature is in beta right now, please send us a request if you'd like access.

Suggested Next Steps

Suggested Next Steps:

1. Visit our Guides to learn about Village through examples ->

2. Read 'The Basics of Village in 10 Minutes' to see what else you can do ->
3. Connect your data to unlock Village. Connect the Activity API ->

More on Connecting Your Data to Village

The Village API

API Docs ->

Our RESTful API listens for events and activity on your platform and enables real-time Rule execution.

Only events and activity that have been configured as Triggers within Village will be securely passed to Village through the API. These Triggers are in turn used to start the evaluation of your rules logic within Village. To read more about setting up, configuring, and using the API, refer to our Engineering Documentation, or read more about Triggers here.

Low or No Code Data Upload

Low or No Code Data Upload ->

You can use our quick and dirty Python, Airtable, and Google Apps Scripts. These are ideal if you're initially testing an integration, if your data is not stored in a centralized database, or if you're just getting started.

Third Party Data Connections

Village connects to many 3rd-party data sources.

Data Connections

Village also has many one-click data connections for securely sharing events based data to be linked to triggers within the platform. These can be accessed in Village's production environment through the Data Connections tab.

In most cases, these connections are the easiest way to pass data to Village using common data sources and platforms

We currently support the following data connections with many more being added - please ping [e-mail] if you don't see your data source listed.

Productivity Tools

• Google Sheets

• Airtable

• Zapier

• Github

• Slack

Payments

• Stripe

• Paypal

Databases & Warehousing

• Bigquery

• MySQL

• PostgresSQL

• Snowflake

• Amazon Redshift

Cloud Storage

• Amazon S3

• Google Cloud

• MongoDB

CRM & Sales

• SendGrid

• Hubspot

• Intercom

• Pipedrive

• Salesforce

• Mailchimp