Assigning Rules for Default Spaces

Workvivo Spaces support automatic enrollment of users based on their team memberships. Through the API, you can configure two types of enrollment logic for a Default Space: OR logic and AND logic. These options provide the same flexibility available in the Workvivo admin UI under Spaces → Default Spaces → Rules.

• OR logic: A user is enrolled if they belong to any one of the specified teams.
• AND logic: A user is enrolled only if they belong to all of the teams within a defined rule group.

How it works

The two types of logic use separate parameters and separate endpoints. This distinction is important when configuring a Default Space:

A team that should qualify users on its own must always be assigned through the Update Default Space endpoint using term_ids. Use the Rules endpoints only when a user must belong to multiple teams simultaneously to qualify for enrollment.

Both types of rules can be used independently or together for the same space.

Endpoint reference

1. Update Default Space — OR logic

Use this endpoint to assign teams that individually qualify a user for automatic enrollment. A user who is a member of any of the listed teams will be enrolled in the space.

curl -X PUT "https://api.workvivo.com/v1/spaces/1/default" \
  -H "Authorization: Bearer $WORKVIVO_TOKEN" \
  -H "Workvivo-Id: $WORKVIVO_ORG_ID" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "term_ids": [10, 30, 50]
  }'

{
    "data":
    [
        {
            "id": 10,
            "name": "Accounting",
            "external_id": "accounting-0001",
            "avatar_url": "https://workvivo.com/img/teams/accounting.jpg",
            "is_hidden": false,
            "permalink": "https://workvivo.com/teams/10"
        },
        {
            "id": 30,
            "name": "Sales",
            "external_id": "sales-0002",
            "avatar_url": "https://workvivo.com/img/teams/sales.jpg",
            "is_hidden": false,
            "permalink": "https://workvivo.com/teams/30"
        },
        {
            "id": 50,
            "name": "Communications",
            "external_id": "communications-0003",
            "avatar_url": "https://workvivo.com/img/teams/communications.jpg",
            "is_hidden": false,
            "permalink": "https://workvivo.com/teams/50"
        }
    ],
    "status": "success",
    "meta": {
        "terms_added": 3,
        "terms_removed": 0
    }
}

In this example, a user who belongs to team 10, team 30, or team 50 will be enrolled.

View the full API reference → Update Default Space

2. Get Default Space Rules — AND logic

Retrieve the current AND-logic rules configured for a Default Space.

curl -X GET "https://api.workvivo.com/v1/spaces/1/default/rules" \
  -H "Authorization: Bearer $WORKVIVO_TOKEN" \
  -H "Workvivo-Id: $WORKVIVO_ORG_ID" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \

{
    "data": [
        [
            {
                "id": 10,
                "name": "Accounting",
                "external_id": "accounting-0001",
                "avatar_url": "https://workvivo.com/img/teams/accounting.jpg",
                "is_hidden": false,
                "permalink": "https://workvivo.com/teams/10"
            },
            {
                "id": 50,
                "name": "Communications",
                "external_id": "communications-0005",
                "avatar_url": "https://workvivo.com/img/teams/communications.jpg",
                "is_hidden": false,
                "permalink": "https://workvivo.com/teams/50"
            }
        ],
        [
            {
                "id": 30,
                "name": "Sales",
                "external_id": "sales-0003",
                "avatar_url": "https://workvivo.com/img/teams/sales.jpg",
                "is_hidden": false,
                "permalink": "https://workvivo.com/teams/30"
            },
            {
                "id": 50,
                "name": "Communications",
                "external_id": "communications-0005",
                "avatar_url": "https://workvivo.com/img/teams/communications.jpg",
                "is_hidden": false,
                "permalink": "https://workvivo.com/teams/50"
            }
        ],
    ],
    "status": "success",
    "meta": {
        "pagination": {
            "skip": 0,
            "take": 10,
            "total_records": 2,
            "next_page": null
        }
    }
}

This returns the collection of term_id_rules currently configured for the space.

View the full API reference → Get Default Space Rules

3. Update Default Space Rules — AND logic

Use this endpoint to define rules where a user must belong to all teams within a rule group to qualify for enrollment.

The term_id_rules parameter is an array of arrays. Each inner array is an AND group, while multiple inner arrays are evaluated with OR logic between them:

curl -X PUT "https://api.workvivo.com/v1/spaces/1/default/rules" \
  -H "Authorization: Bearer $WORKVIVO_TOKEN" \
  -H "Workvivo-Id: $WORKVIVO_ORG_ID" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "term_id_rules": [[10, 20], [30, 40]]
  }'

{
    "data": [
        [
            {
                "id": 10,
                "name": "Accounting",
                "external_id": "accounting-0001",
                "avatar_url": "https://workvivo.com/img/teams/accounting.jpg",
                "is_hidden": false,
                "permalink": "https://workvivo.com/teams/10"
            },
            {
                "id": 20,
                "name": "Communications",
                "external_id": "communications-0002",
                "avatar_url": "https://workvivo.com/img/teams/communications.jpg",
                "is_hidden": false,
                "permalink": "https://workvivo.com/teams/20"
            }
        ],
        [
            {
                "id": 30,
                "name": "Sales",
                "external_id": "sales-0003",
                "avatar_url": "https://workvivo.com/img/teams/sales.jpg",
                "is_hidden": false,
                "permalink": "https://workvivo.com/teams/30"
            },
            {
                "id": 40,
                "name": "HR",
                "external_id": "hr-0004",
                "avatar_url": "https://workvivo.com/img/teams/hr.jpg",
                "is_hidden": false,
                "permalink": "https://workvivo.com/teams/40"
            }
        ],
    ],
    "status": "success",
    "meta": {
        "term_rules_added": 2,
        "term_rules_removed": 0
    }
}

This enrolls a user who belongs to team 10 and team 20, or who belongs to team 30 and team 40.

Each inner array must contain a minimum of 2 and a maximum of 10 distinct team IDs. A space can have a maximum of 50 rules. If you only need a single team to qualify a user, use term_ids on the Update Default Space endpoint instead.

Both this endpoint and the Update Default Space endpoint (/default) use replacement behaviour. Any existing values not included in the request body are removed, so always send the complete set of rules or team IDs you want to keep.

View the full API reference → Update Default Space Rules

4. Delete Default Space Rules — AND logic

Remove all AND-logic rules from a Default Space.

curl -X DELETE "https://api.workvivo.com/v1/spaces/1/default/rules" \
  -H "Authorization: Bearer $WORKVIVO_TOKEN" \
  -H "Workvivo-Id: $WORKVIVO_ORG_ID" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \

{
    "data": {
        "id": 1,
        "parent_space_id": null,
        "name": "Health & Wellbeing",
        "avatar_url": null,
        "description": "A space where we share updates on initiatives and helpful tips..",
        "visibility": "public",
        "is_external": false,
        "is_corporate": false,
        "is_mandatory": false,
        "is_read_only": false,
        "categories": [
            {
                "id": 1,
                "name": "Health & Wellbeing",
                "description": null,
                "created_at": "2021-08-11T11:43:43Z",
                "updated_at": "2021-08-11T11:43:43Z"
            }
        ],
        "created_at": "2021-08-11T11:43:28Z",
        "updated_at": "2023-06-15T08:55:19Z",
        "permalink": "https://workvivo.com,/spaces/1"
    },
    "status": "success",
    "meta": {
        "term_rules_removed": 2
    }
}

This removes all term_id_rules configured for the space. It does not affect the term_ids configured through the Update Default Space endpoint; those standalone team assignments are managed separately.

For example, if a space has these enrollment settings:

• Team 10 and team 20
• Team 30 and team 40
• Team 50 (standalone)
• Team 60 (standalone)

Calling this endpoint removes the first two rules. Teams 50 and 60 remain enrolled through term_ids.

View the full API reference → Delete Default Space Rules

Combining OR and AND logic

You can use both term_ids and term_id_rules together to build flexible, layered enrollment configurations for the same space.

For example, to automatically enroll users into Space Ireland if they are a member of the Dublin team, or a member of both the Cork and New Hires teams:

1. Set the OR rule through PUT /v1/spaces/{space_id}/default:

   curl -X PUT "https://api.workvivo.com/v1/spaces/1/default" \
   -H "Authorization: Bearer $WORKVIVO_TOKEN" \
   -H "Workvivo-Id: $WORKVIVO_ORG_ID" \
   -H "Accept: application/json" \
   -H "Content-Type: application/json" \
   -d '{
       "term_ids": [101]
   }'
   

   {
       "data": [
           {
               "id": 101,
               "name": "Dublin",
               "external_id": "dublin-101",
               "avatar_url": "https://workvivo.com/img/teams/dublin.jpg",
               "is_hidden": false,
               "permalink": "https://workvivo.com/teams/101"
           }
       ],
       "status": "success",
       "meta": {
           "terms_added": 1,
           "terms_removed": 0
       }
   }
   

   Here, 101 is the Dublin team ID.

2. Set the AND rule through PUT /v1/spaces/{space_id}/default/rules:

   curl -X PUT "https://api.workvivo.com/v1/spaces/1/default/rules" \
   -H "Authorization: Bearer $WORKVIVO_TOKEN" \
   -H "Workvivo-Id: $WORKVIVO_ORG_ID" \
   -H "Accept: application/json" \
   -H "Content-Type: application/json" \
   -d '{
       "term_id_rules": [[102, 103]]
   }'
   

   {
       "data": [
           [
               {
                   "id": 102,
                   "name": "Cork",
                   "external_id": "accounting-102",
                   "avatar_url": "https://workvivo.com/img/teams/cork.jpg",
                   "is_hidden": false,
                   "permalink": "https://workvivo.com/teams/102"
               },
               {
                   "id": 103,
                   "name": "New Hires",
                   "external_id": "communications-103",
                   "avatar_url": "https://workvivo.com/img/teams/new-hires.jpg",
                   "is_hidden": false,
                   "permalink": "https://workvivo.com/teams/103"
               }
           ]
       ],
       "status": "success",
       "meta": {
           "term_rules_added": 1,
           "term_rules_removed": 0
       }
   }
   

   Here, 102 is the Cork team ID and 103 is the New Hires team ID.

The resulting enrollment logic is: a user is enrolled if they belong to Dublin, or if they belong to both Cork and New Hires.

Key constraints and notes

• term_id_rules accepts a nested array. Each inner array is an AND group; multiple inner arrays are evaluated with OR logic between them.
• Each inner array requires a minimum of 2 and a maximum of 10 distinct team IDs. A space can have a maximum of 50 rules.
• Single-team qualifications must use term_ids on the Update Default Space endpoint.
• Both update endpoints use replacement behaviour. Values not included in the request are removed, so always send the complete set of term_ids or term_id_rules you want to keep.
• term_id_rules is available only on the Rules endpoints (/default/rules). It cannot be passed to the base Default Space endpoint (/default).
• The Rules endpoints are separate from the base Default Space endpoint because their response structures differ.
• The DELETE method removes all AND-logic rules at once. It does not support deleting individual rules and does not affect standalone team assignments (term_ids).

Quick reference