# User Status API

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

## 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

{% hint style="warning" %}
**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. 
{% endhint %}

### **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:

      ```postman_json
          "send_email": true
      ```

{% hint style="info" %}
Unless you are using Village's standalone dashboard, we recommend that you **do not** send emails when creating users with the User Status API.
{% endhint %}

2. **Revoke Invite:** Revokes an existing Village Invite so that if the user can no longer join the network (if they have not already). 
3. **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:

<figure><img src="/files/E0xVyDkx9OOvD9ZtGiFY" alt="" width="375"><figcaption><p>Accessing User Status</p></figcaption></figure>

## Endpoint

**`POST`**`/networks/YOUR_NETWORK_ID/user_status`

Where 'YOUR\_NETWORK\_ID' is replaced with your actual Network ID.&#x20;

## API Field Overview

The User Status API allows you to change a user's status programmatically.&#x20;

### Body Fields

<table><thead><tr><th width="142">Field Name</th><th width="179">JSON Key</th><th>Type</th><th width="582">Description</th><th>Required</th></tr></thead><tbody><tr><td>User</td><td>user</td><td>string</td><td>The user. Must be a valid email. </td><td>Yes</td></tr><tr><td>Status Change</td><td>status_change</td><td>string</td><td>Options include:<br>1. "create_user" -> Creates the Village account and registers the user with your network.  <br>2. "revoke_invite" -> Revokes an existing Village Invite.<br>3. "ban" -> Suspends the user from all network activity and eligibility. Existing funds can still be accessed.</td><td>Yes</td></tr><tr><td>Send Email</td><td>send_email</td><td>boolean</td><td>Paired with "create_user". If <strong>true</strong>, an invite email is sent when the user is created. If this field is not included, or <strong>false</strong>, an email will not be sent. </td><td>No</td></tr><tr><td>Referrer*</td><td>referrer</td><td>string</td><td>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 <a href="/pages/9KWoDIFHQ0etv7T0OLzu">Connections (referrals) APIs -></a>.</td><td>No</td></tr><tr><td>Segment Adds*</td><td>segment_adds</td><td>array</td><td>Optional array of Segment IDs to add this user to upon creation. </td><td>No</td></tr><tr><td>Metadata</td><td>metadata</td><td>object</td><td>Additional metadata for the user status change. See Metadata fields for options.</td><td>No</td></tr></tbody></table>

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

### Metadata

{% hint style="warning" %}
\*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.`
{% endhint %}

<table><thead><tr><th width="141">Field Name</th><th width="181">JSON Key</th><th width="132">Type</th><th width="467">Description</th><th>Required</th></tr></thead><tbody><tr><td>Reference ID</td><td>reference_id</td><td>string</td><td>An optional identifier that can be used for reporting purposes.</td><td>No</td></tr><tr><td>Status Change Timestamp</td><td>status_change_timestamp</td><td>integer</td><td>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.</td><td>No</td></tr><tr><td>Description</td><td>description</td><td>string</td><td>A reason and description for the status change.</td><td>No</td></tr></tbody></table>

## Examples

### Body

```json
// Example User Status Body
{
    "user": "johnny.invite@villagelabs.co",
    "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

{% tabs %}
{% tab title="Javascript" %}

```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}`, ""]]);
    }
  }
}


```

{% endtab %}

{% tab title="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": "ajwurts@villagelabs.co",
    "status_change": "create_user"
}'

```

{% endtab %}
{% endtabs %}

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://village-labs.gitbook.io/coworker-product-and-developer-docs/legacy-developer-docs/village-apis-introduction/user-status-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.