User Status API

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

About User Status

The User Status API allows Village customers to programmatically create or suspend the status of their end users in the Village System. Functional examples include:

1. Automatically add users to your Village Network when they sign up to your platform

2. Suspend users from Village when certain events occur on your platform

Please note: The User Status API should only be used when creating or suspending users. You should not use the User Status API for updating information of an already created user, such as name or segment. Please use the Segments API or User Patch API for these purposes.

Possible user status changes:

1. Create User: Creates the Village account for the user.

   1. May or may not send an email to this user depending on field:

          "send_email": true

Unless you are using Village's standalone dashboard, we recommend that you do not send emails when creating users with the User Status API.

1. Revoke Invite: Revokes an existing Village Invite so that if the user can no longer join the network (if they have not already).

2. Ban: Suspends the user from all network activity and eligibility. Existing funds can still be accessed.

Using the Admin Dashboard for Viewing User Status

Any Admin User on your Village Network can view the current status of any user through the Network Manager or Side Menu:

Accessing User Status

Endpoint

POST/networks/YOUR_NETWORK_ID/user_status

Where 'YOUR_NETWORK_ID' is replaced with your actual Network ID.

API Field Overview

The User Status API allows you to change a user's status programmatically.

Body Fields

Field Name	JSON Key	Type	Description	Required
User	user	string	The user. Must be a valid email.	Yes
Status Change	status_change	string	Options include: 1. "create_user" -> Creates the Village account and registers the user with your network. 2. "revoke_invite" -> Revokes an existing Village Invite. 3. "ban" -> Suspends the user from all network activity and eligibility. Existing funds can still be accessed.	Yes
Send Email	send_email	boolean	Paired with "create_user". If true, an invite email is sent when the user is created. If this field is not included, or false, an email will not be sent.	No
Referrer*	referrer	string	If a user signs up to your app and includes a Village referral code from another user, you may include that code here. If included, Village will update the Connection (Referral) Program with this new connection between users. See Connections (referrals) APIs ->.	No
Segment Adds*	segment_adds	array	Optional array of Segment IDs to add this user to upon creation.	No
Metadata	metadata	object	Additional metadata for the user status change. See Metadata fields for options.	No

* Only available on first successful create_user request. Afterwards this field is ignored and you should use the Segments API (or Connections API for referrals) after user creation.

Metadata

*Only available on first successful create_user request, afterwards the field is ignored. Please use the Segment API, or Connections API after user creation. Fields are ignored for status_change other than create_user.

Field Name	JSON Key	Type	Description	Required
Reference ID	reference_id	string	An optional identifier that can be used for reporting purposes.	No
Status Change Timestamp	status_change_timestamp	integer	The Unix timestamp of when the status change occurred. If this is blank, Village will use the timestamp the data was received via the Village API as the Status Change Timestamp.	No
Description	description	string	A reason and description for the status change.	No

Examples

Body

// Example User Status Body
{
    "user": "[e-mail]",
    "status_change": "create_user",
    "send_invite": true, // optional, create_user status change only
    "first_name": "Johnny", // optional, create_user status change only
    "last_name": "Invite", // optional, create_user status change only
    "referrer": "brad_82jx", // optional, create_user status change only
    "segment_adds": [0,1,2], // optional, create_user status change only
    "metadata": { // optional
        "reference_id": "dpi_Ylo2Cfr8US8u1JIdAl2eZvKB", // optional
        "status_change_timestamp": 1664900628, // optional
        "reason": "New user signup" // optional
    }
}

By Language

Javascript

//Example of a simple Google Apps script 
//Remember to replace 'Bearer YOUR_API_KEY' with your actual API key
//Replace 'YOUR_NETWORK_ID' with your actual network ID

// USER STATUS **********************
function submitUserStatusData() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const settingsSheet = ss.getSheetByName("Settings");
  const userStatusSheet = ss.getSheetByName("User Status");

  const apiKey = settingsSheet.getRange("B2").getValue();
  const networkId = settingsSheet.getRange("B3").getValue();
  const endpointUrl = settingsSheet.getRange("B4").getValue();
  const path = settingsSheet.getRange("B7").getValue();

  const url = `${endpointUrl}/networks/${networkId}/${path}`;
  const userStatusData = userStatusSheet.getDataRange().getValues();

  for(let i = 1; i < userStatusData.length; i++) {
    let row = userStatusData[i];
    
    if(row[0] === 'Success') continue;

    let postData = {
      "user": row[2],
      "status_change": row[3]
    };

    let options = {
      "method": "POST",
      "headers": {
        "Authorization": `Bearer ${apiKey}`,
        "Content-Type": "application/json"
      },
      "payload": JSON.stringify(postData),
      "muteHttpExceptions": true
    };

    try {
      let response = UrlFetchApp.fetch(url, options);
      let responseCode = response.getResponseCode();
      
      if(responseCode >= 200 && responseCode < 300) {
        userStatusSheet.getRange(i + 1, 1, 1, 2).setValues([["Success", responseCode]]);
      } else {
        let responseContent = JSON.parse(response.getContentText());
        let errorMessage = responseContent.error || "Unknown error";
        userStatusSheet.getRange(i + 1, 1, 1, 2).setValues([[`Failure: ${errorMessage}`, responseCode]]);
      }
    } catch (e) {
      userStatusSheet.getRange(i + 1, 1, 1, 2).setValues([[`Failure: ${e.message}`, ""]]);
    }
  }
}

cURL

// Remember to replace YOUR_NETWORK_ID with your Network ID
// Remember to replace YOUR_API_KEY with your API Key from the Village admin dashboard

curl --location 'https://ledger-api.villagelabs.dev/networks/YOUR_NETWORK_ID/user_status' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "user": "[e-mail]",
    "status_change": "create_user"
}'

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