Connections (Referrals) APIs

Is this page helpful? Give us feedback on our docs ->

Terminology Note: "Referrals" vs. "Connections" in the code

TL;DR - They're the same thing! In the API code, we refer generically to connections and connection programs--not referrals and referral programs.

Why? That's because our Connections system is actually used to power more than just referrals programs, although referrals is the most common use case.

About Connections (Referrals)

Village's Referral programs are used to let you create up to 10 levels of connections between users.

These "connections" may be used in Program Rules -> to issue awards or comms to referrers when their referral completes an action, such as a signup.

For detailed use cases: Visit the Village Postman collection to explore the endpoints and possible implementations of our Add Connection.

POST Add Connection (Referrals) Between Users

Note this API is primarily for post hoc connections! (Or non-referral use cases)

For example, if you have to correct or backfill referrals for an existing program, this is a good use case for the Add Connection API.

Instead, we recommend using the "referrer" field in the User Status API -> to automatically create referral connections as soon as a suer signs up.

Endpoint Path

POST/networks/YOUR_NETWORK_ID/connections/REFERRAL_PROGRAM_ID

Where 'YOUR_NETWORK_ID' is replaced with your actual Network ID and REFERRAL_PROGRAM_ID is the program under which you want to make the connection. This can be found in the Admin Dashboard under Side Menu > Incentives > Referrals.

API Field Overview

//Example JSON body 

{
    "user": "[e-mail]", // The new user being referred
    "connection": "[e-mail]" // The referrer
}

Body Fields

Field Name	JSON Key	Type	Description	Required
User	user	string	Must be user email. In the case of referrals, this is the NEW user being referred.	Yes
Amount	amount	string	Must be user email. In the case of referrals, this is the EXISTING user who is referring the new user.	Yes

GET Connection (Referrals) Data

For preprocessing or in-app display purposes, you may use the GET Request endpoints -> associated with Referrals to retrieve:

1. All user connections within a Referral Program (GET User Connections)

2. A user's unique referral code (GET Connection Codes)

3. A list of Referral Program IDs (GET Connections)

Is this page helpful? Give us feedback on our docs ->