# Connections (Referrals) APIs

{% hint style="info" %}
[**Is this page helpful? Give us feedback on our docs ->**](https://village-labs.gitbook.io/coworker-product-and-developer-docs/feedback/village-docs-feedback-form) [ ](https://village-labs.gitbook.io/coworker-product-and-developer-docs/feedback/village-docs-feedback-form)
{% endhint %}

{% hint style="info" %} <mark style="color:blue;">**Terminology Note: "Referrals" vs. "Connections" in the code**</mark>

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

**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.&#x20;
{% endhint %}

## About Connections (Referrals)&#x20;

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

These "connections" may be used in [**Program Rules ->** ](https://village-labs.gitbook.io/coworker-product-and-developer-docs/legacy-knowledge-base/programs-and-rules)to issue awards or comms to referrers when their referral completes an action, such as a signup.&#x20;

{% hint style="success" %}
**For detailed use cases:** Visit the [Village Postman collection](https://www.postman.com/village-labs/workspace/village-api-development/overview) to explore the endpoints and possible implementations of our Add Connection.
{% endhint %}

## POST Add Connection (Referrals) Between Users

<mark style="color:red;">**Note this API is primarily for**</mark><mark style="color:red;">**&#x20;**</mark>*<mark style="color:red;">**post hoc**</mark>*<mark style="color:red;">**&#x20;**</mark><mark style="color:red;">**connections!**</mark> (Or non-referral use cases)&#x20;

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.&#x20;

Instead, we recommend using the "referrer" field in the [**User Status API ->**](https://village-labs.gitbook.io/coworker-product-and-developer-docs/legacy-developer-docs/village-apis-introduction/user-status-api) to automatically create referral connections as soon as a suer signs up.&#x20;

### Endpoint Path

**`POST`**`/networks/YOUR_NETWORK_ID/connections/REFERRAL_PROGRAM_ID`&#x20;

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.&#x20;

### API Field Overview &#x20;

```postman_json
//Example JSON body 

{
    "user": "bradford@villagelabs.co", // The new user being referred
    "connection": "ajwurts@villagelabs.co" // The referrer
}

```

### Body Fields

<table><thead><tr><th width="138">Field Name</th><th width="236">JSON Key</th><th width="88">Type</th><th width="460">Description</th><th>Required</th></tr></thead><tbody><tr><td>User</td><td><code>user</code></td><td>string</td><td>Must be user email. In the case of referrals, this is the NEW user being referred. </td><td>Yes</td></tr><tr><td>Amount</td><td><code>amount</code></td><td>string</td><td>Must be user email. In the case of referrals, this is the EXISTING user who is referring the new user. </td><td>Yes</td></tr></tbody></table>

## GET Connection (Referrals) Data

For preprocessing or in-app display purposes, you may use the [**GET Request endpoints ->**](https://village-labs.gitbook.io/coworker-product-and-developer-docs/legacy-developer-docs/village-apis-introduction/get-apis) associated with Referrals to retrieve:&#x20;

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)**

{% hint style="info" %}
[**Is this page helpful? Give us feedback on our docs ->**](https://village-labs.gitbook.io/coworker-product-and-developer-docs/feedback/village-docs-feedback-form) [ ](https://village-labs.gitbook.io/coworker-product-and-developer-docs/feedback/village-docs-feedback-form)
{% endhint %}

##