Groups¶

class audience.api.controllers.groups.MemberGroupController(app, request, response)¶

Contains web service functions for managing member groups

list_groups(account_id)¶

GET /#account_id/groups

Get a basic listing of all active member groups for a single account.

Returns:	An array of groups.
Parameters:	group_types (string) – Accepts a comma-separated string with one or more of the following group_types: ‘g’ (group), ‘t’ (test), ‘h’ (hidden), ‘all’ (all). Defaults to ‘g’.

Sample Response [showhide]

	GET /100/groups?group_types=g,t

	[
	  {
		"active_count": 1, 
		"deleted_at": null, 
		"error_count": 0, 
		"optout_count": 1, 
		"group_type": "g", 
		"member_group_id": 150, 
		"account_id": 100, 
		"group_name": "Monthly Newsletter"
	  }, 
	  {
		"active_count": 2, 
		"deleted_at": null, 
		"error_count": 0, 
		"optout_count": 0, 
		"group_type": "g", 
		"member_group_id": 151, 
		"account_id": 100, 
		"group_name": "Widget Buyers"
	  }, 
	  {
		"active_count": 4, 
		"deleted_at": null, 
		"error_count": 0, 
		"optout_count": 0, 
		"group_type": "g", 
		"member_group_id": 152, 
		"account_id": 100, 
		"group_name": "Special Events"
	  }
	]
	

Sample Response [showhide]

	GET /100/groups?group_types=all

	[
	  {
		"active_count": 1, 
		"deleted_at": null, 
		"error_count": 0, 
		"optout_count": 1, 
		"group_type": "g", 
		"member_group_id": 150, 
		"account_id": 100, 
		"group_name": "Monthly Newsletter"
	  }, 
	  {
		"active_count": 2, 
		"deleted_at": null, 
		"error_count": 0, 
		"optout_count": 0, 
		"group_type": "g", 
		"member_group_id": 151, 
		"account_id": 100, 
		"group_name": "Widget Buyers"
	  }, 
	  {
		"active_count": 4, 
		"deleted_at": null, 
		"error_count": 0, 
		"optout_count": 0, 
		"group_type": "g", 
		"member_group_id": 152, 
		"account_id": 100, 
		"group_name": "Special Events"
	  }
	]
	

create_groups(account_id)¶

POST /#account_id/groups

Create one or more new member groups.

Returns:	An array of the new group ids and group names.
Parameters:	groups (array) – An array of group objects. Each object must contain a group_name parameter.

Sample Response [showhide]

	POST /100/groups
	{
	  "groups": [
		{
		  "group_name": "My Grp"
		}
	  ]
	}

	[
	  {
		"member_group_id": 1024, 
		"group_name": "My Grp"
	  }
	]
	

get_group_detail(account_id, member_group_id)¶

GET /#account_id/groups/#member_group_id

Get the detailed information for a single member group.

Returns:	A group.
Raises :	Http404 if the group does not exist.

Sample Response [showhide]

	GET /100/groups/150

	{
	  "active_count": 1, 
	  "deleted_at": null, 
	  "error_count": 0, 
	  "optout_count": 1, 
	  "group_type": "g", 
	  "member_group_id": 150, 
	  "account_id": 100, 
	  "group_name": "Monthly Newsletter"
	}
	

update_group(account_id, member_group_id)¶

PUT /#account_id/groups/#member_group_id

Update information for a single member group.

Parameters:	group_name (string) – Updated group name.
Returns:	True if the update was successful
Raises :	Http404 if the group does not exist.

Sample Response [showhide]

	PUT /100/groups/150
	{
	  "group_name": "New Group Name"
	}

	true
	

delete_group(account_id, member_group_id)¶

DELETE /#account_id/groups/#member_group_id

Delete a single member group.

Returns:	True if the group is deleted.
Raises :	Http404 if the group does not exist.

Sample Response [showhide]

	DELETE /100/groups/150

	true
	

list_group_members(account_id, member_group_id)¶

GET /#account_id/groups/#member_group_id/members

Get the members in a single active member group.

Returns:	An array of members.
Parameters:	deleted (boolean) – include deleted members. Optional, defaults to false.
Raises :	Http404 if the group does not exist.

Sample Response [showhide]

	GET /100/groups/150/members

	[
	  {
		"status": "active", 
		"confirmed_opt_in": null, 
		"account_id": 100, 
		"fields": {
		  "first_name": "Emma", 
		  "last_name": "Smith", 
		  "favorite_food": "tacos"
		}, 
		"member_id": 200, 
		"last_modified_at": null, 
		"member_status_id": "a", 
		"plaintext_preferred": false, 
		"email_error": null, 
		"member_since": "@D:2010-11-12T11:23:45", 
		"bounce_count": 0, 
		"deleted_at": null, 
		"email": "emma@myemma.com"
	  }, 
	  {
		"status": "opt-out", 
		"confirmed_opt_in": null, 
		"account_id": 100, 
		"fields": {
		  "first_name": "Gladys", 
		  "last_name": "Jones", 
		  "favorite_food": "toast"
		}, 
		"member_id": 201, 
		"last_modified_at": null, 
		"member_status_id": "o", 
		"plaintext_preferred": false, 
		"email_error": null, 
		"member_since": "@D:2011-01-03T15:54:13", 
		"bounce_count": 0, 
		"deleted_at": null, 
		"email": "gladys@myemma.com"
	  }
	]
	

add_members_to_group(account_id, member_group_id)¶

PUT /#account_id/groups/#member_group_id/members

Add a list of members to a single active member group.

Parameters:	member_ids (array) – An array of member ids.
Returns:	An array of references to the members added to the group. If a member already exists in the group or is not a valid member, that reference will not be returned.
Raises :	Http404 if the group does not exist.

Sample Response [showhide]

	PUT /100/groups/150/members
	{
	  "member_ids": [
		202
	  ]
	}

	[
	  202
	]
	

remove_members_from_group(account_id, member_group_id)¶

PUT /#account_id/groups/#member_group_id/members/remove

Remove members from a single active member group.

Parameters:	member_ids (array) – An array of member ids.
Returns:	An array of references to the removed members.
Raises :	Http404 if the group does not exist.

Sample Response [showhide]

	PUT /100/groups/150/members/remove
	{
	  "member_ids": [
		200, 
		201
	  ]
	}

	[
	  200, 
	  201
	]
	

remove_all_members_from_group(account_id, member_group_id)¶

DELETE /#account_id/groups/#member_group_id/members

Remove all members from a single active member group.

Parameters:	member_status_id (string) – Optional. This is ‘a’ctive, ‘o’ptout, or ‘e’error.
Returns:	Returns the number of members removed from the group.
Raises :	Http404 if the group does not exist.

Sample Response [showhide]

	DELETE /100/groups/151/members

	2
	

Sample Response [showhide]

	DELETE /100/groups/151/members?member_status_id=a

	2
	

remove_all_members_from_all_groups(account_id, member_group_id)¶

DELETE /#account_id/groups/#member_group_id/members/remove

Remove all members from all active member groups as a background job. The member_status_id parameter must be set.

Parameters:	member_status_id (string) – This is ‘a’ctive, ‘o’ptout, or ‘e’error.
Returns:	Returns true.
Raises :	Http404 if the group does not exist.

Sample Response [showhide]

	DELETE /100/groups/151/members/remove?member_status_id=a

	true
	

Sample Response [showhide]

	DELETE /100/groups/151/members/remove?member_status_id=a&delete_members=true

	true
	

copy_group_to_group(account_id, from_group_id, to_group_id)¶

PUT /#account_id/groups/#from_group_id/#to_group_id/members/copy

Copy all the users of one group into another group.

Parameters:	member_status_id (array) – This is ‘a’ctive, ‘o’ptout, or ‘e’error.
Returns:	True
Raises :	Http404 if the group does not exist.

Sample Response [showhide]

	PUT /100/groups/151/152/members/copy
	{
	  "member_status_id": [
		"a"
	  ]
	}

	true