search_workgroups

Syntax

{
  <credentials object>, 
  "criteria": {
    "domain": <domain name>,
    "match": <wildcard pattern> 
  }
  "range":{
     "first": <number>, 
     "limit": <number> 
     "sort": {
        "by": workgroup | users
        "direction": ascending | descending
    }
}

Request fields for search_workgroups

The following fields can be used in the search_workgroups method:

Field name	Obligation	Definition/Value
criteria	Required	Narrows the results by restricting the search. Allowed values are: domain — Specifies the domain to search. This is required. match — Returns only those workgroups that match the specified pattern. You can use the following wildcards: ? ― Match a single character * ― Match multiple characters.
range	Optional	Limits the results to a subset of those selected by the criteria values. Allowed values are: first — Specify the first workgroup to return; the default is the first result. limit — Specify the maximum number of results to return.
sort	Optional	Determines the way in which to sort and display results. Allowed values are: by — Specify the attribute to use to sort results. Allowed values are: user — The number of users in the workgroup. workgroup — The workgroup name (this is the default). direction — Specify the sort order. Allowed values are ascending (this is the default) or descending.

Response fields for search_workgroups

The following fields may be returned in response to the search_workgroups method:

Field name	Obligation	Description/Value
count	Returned if success = true	The number of workgroups returned.
error	Returned if success = false	A text string that explains the error.
error_number	Returned if success = false	A number that represents the error.
success	Always returned	Indicates whether the request was successful or not. Allowed values are true and false.
total_count	Returned if success = true	The total number of workgroups that match the search criteria. This value may be more than the number of results returned if a range was specified in the request.
workgroups	Returned if success = true	A list of the workgroups that meet the criteria and their attributes. Includes the following: counts — The number of each type of mailbox in the workgroup. filter — The number of filter only mailboxes (delivery_filter attribute set to true). forward — The number of forward only mailboxes (delivery_forward attribute set to true and delivery_local set to false). mailbox — The number of mailboxes (delivery_local attribute set to true). total — The total number of users in the workgroup. workgroup — The workgroup name.

Examples for search_workgroups

Example 1

Retrieves all workgroups in the domain example.com.

Request

{
  "credentials": {
    "user": "domain_admin@example.com",
    "password": "pencil75"
  },
  "criteria": {
    "domain": "example.com"
  } 
}

Response

{
  "success": true,
  "count": 7,
  "total_count": 7,
  "workgroups": [
    {
      "workgroup": "contract",
      "counts": {
      	"filter": 0,
				"forward": 0,
				"mailbox": 0,
				"total": 0
      } 
    },
		{
    	"workgroup": "interns",
  		"counts": {
    		"filter": 0,
    		"forward": 1,
    		"mailbox": 2,
    		"total": 3
    }, 
    {
    	"workgroup": "sales",
				"counts": {
  			"filter": 0,
  			"forward": 0,
  			"mailbox": 1,
  			"total": 1
      } 
    },
    {
    	"workgroup": "sales_europe",
  		"counts": {
    		"filter": 0,
    		"forward": 0,
    		"mailbox": 0,
    		"total": 0
      } 
    },
    {
    	"workgroup": "staff",
  		"counts": {
      	"filter": 0,
        "forward": 1,
        "mailbox": 4,
        "total": 5
      } 
    },
    {
    	"workgroup": "stock_holders",
      "counts": {
        "filter": 0,
        "forward": 0,
        "mailbox": 0,
        "total": 0
      } 
    },
    {
    	"workgroup": "sysadmins",
      "counts": {
        "filter": 0,
        "forward": 0,
        "mailbox": 0,
        "total": 0
      }
    }
  ],
}

Example 2

Retrieves all workgroups that start with 's'.

Request

{
  "credentials": {
    "user": "domain_admin@example.com",
    "password": "pencil75"
  },
  "criteria": {
    "domain": "example.com",
    "match": "s*"
  } 
}

Response

{
  "success": true,
  "count": 5,
  "total_count": 5,
  "workgroups": [
    {
    	"workgroup": "sales",
      "counts": {
        "filter": 0,
        "forward": 0,
        "mailbox": 1,
        "total": 1
      }
    },
    {
    	"workgroup": "sales_europe",
      "counts": {
        "filter": 0,
        "forward": 0,
        "mailbox": 0,
        "total": 0
      }
    },
    {
    	"workgroup": "staff",
      "counts": {
        "filter": 0,
        "forward": 1,
        "mailbox": 4,
        "total": 5
      }
    },
    {
    	"workgroup": "stock_holders",
			"counts": {
  			"filter": 0,
  			"forward": 0,
  			"mailbox": 0,
  			"total": 0
      }
    },
    {
    	"workgroup": "sysadmins",
      "counts": {
        "filter": 0,
        "forward": 0,
        "mailbox": 0,
        "total": 0
      } 
    }
	], 
}

Example 3

Retrieves the first three workgroups that start with 's' in the domain example.com.

Request

{
  "credentials": {
		"user": "domain_admin@example.com",
    "password": "pencil75"
  },
  "criteria": {
    "domain": "example.com",
    "match": "s*"
  },
  "range": {
    "first": 0,
    "limit": 3
	} 
}

Response

{
  "success": true,
  "count": 3,
  "total_count": 5,
  "workgroups": [
    {
      "workgroup": "sales",
      "counts": {
        "filter": 0,
        "forward": 0,
        "mailbox": 1,
        "total": 1
      } 
    },
    {
    	"workgroup": "sales_europe",
      "counts": {
        "filter": 0,
        "forward": 0,
        "mailbox": 0,
        "total": 0
      } 
    },
    {
    	"workgroup": "staff",
      "counts": {
				"filter": 0,
        "forward": 1,
        "mailbox": 4,
        "total": 5
      } 
    }
  ], 
}

Example 4

Retrieves the next three workgroups that start with 's' in the domain example.com.

Request

{
  "credentials": {
		"user": "domain_admin@example.com",
    "password": "pencil75"
  },
  "criteria": {
    "domain": "example.com",
    "match": "s*"
	}, 
	"range": {
		"first": 3,
		"limit": 3 
 	}
}

Response

{
  "success": true,
  "count": 2,
  "total_count": 5,
  "workgroups": [
    {
      "workgroup": "stock_holders",
      	"counts": {
      	"filter": 0,
				"forward": 0,
				"mailbox": 0,
				"total": 0
      } 
    },
    {
    	"workgroup": "sysadmins",
      "counts": {
        "filter": 0,
        "forward": 0,
        "mailbox": 0,
        "total": 0
			} 
		}
	], 
}

Example 5

Retrieves the first three workgroups that start with 's' in the domain example.com, sorting by number of users in the workgroup, in descending order.

Request

{
  "credentials": {
		"user": "domain_admin@example.com",
    "password": "pencil75"
  },
  "criteria": {
    "domain": "example.com",
    "match": "s*"
	}, 
	"range": {
    "first": 0,
    "limit": 3
  }, 
  "sort": {
    "by": "users",
    "direction": "descending"
  }
}

Response

{
  "success": true,
  "workgroups": [
    {
      "workgroup": "staff",
      "counts": {
        "filter": 0,
        "forward": 1,
        "deleted": 2,
        "mailbox": 4,
        "total": 5
			} 
		},
    {
      "workgroup": "sales",
      "counts": {
        "filter": 0,
        "forward": 0,
        "deleted": 0,
        "mailbox": 1,
        "total": 1
			} 
		},
		{
      "workgroup": "sales_europe",
      "counts": {
        "filter": 0,
        "forward": 0,
        "deleted": 0,
				"mailbox": 0,
				"total": 0
      } 
    }
  ],
  "count": 3,
  "total_count": 5
}