Groups

Groups are a flexible way to organize your reports. Here are some ways you can use them
1. Organize your reports into groups that are meaningful to you
2. Add group members, limiting which reports each of your users can access within the Yardstik platform
3. Turn report-related notifications on/off for group members and add custom emails, like a shared inbox

Use this resource to create and manage groups and their memberships.

List groups

Retrieve a paginated list of groups for your account. See Pagination.

SecurityApiKey
Request
query Parameters
order
string

Order listing results in ascending or descending order, when using order_by.
Accepted values are asc or desc. If not passed, defaults to ascending asc.

Examples:
order=desc
order_by
string

Order listing results by a specific property.

Examples:
order_by=created_at
page
integer

The page number to retrieve.

per_page
integer

The maximum number of results per page.

query
string

Filter listing results by a specific property.

Examples:
query[created_at_gteq]=2022-01-01T00:00:00.000Z
Responses
200

List of groups.

401

Unauthorized

404

Not Found

get/groups
Request samples 
Response samples 
application/json
{
  • "object": "list",
  • "meta": {
    },
  • "data": [
    ]
}
Create a group
Create a new group.


SecurityApiKey 
Request 
Request Body schema: application/json
required
description
string
A description of the group.


 
enabled
boolean
 Default:  true
Whether the group is enabled.


 
label
required
string
The display label for the group.


 
name
string
The unique name of the group. Auto-generated from the label if not provided.


 
notification_email_addresses
Array of strings <email> 
A list of email addresses to receive notifications for this group. Useful for emails not associated with users. Note this is only evaluated if your account report_notifications setting notify_only_group_recipients is true.


 
send_notifications_to_members
boolean
 Default:  false
Whether to send notifications to group members. Note this is only evaluated if your account report_notifications setting notify_only_group_recipients is true.


 
Responses 
201
Group was created successfully.


401
Unauthorized


403
Forbidden


422
Unprocessable Entity


post/groups
Request samples 
application/json
{
  • "label": "string"
}
Response samples 
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "object": "group",
  • "name": "string",
  • "label": "string",
  • "description": "string",
  • "enabled": true,
  • "send_notifications_to_members": false,
  • "notification_email_addresses": [
    ],
  • "reports_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "memberships": [
    ]
}
Get a group
Retrieve a group with the given ID.


SecurityApiKey 
Request 
path Parameters
group_id
required
string <uuid>  (ResourceId)   <= 50 characters 
The group ID.


 
 Example:  4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses 
200
Group details.


401
Unauthorized


404
Not Found


get/groups/{group_id}
Request samples 
Response samples 
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "object": "group",
  • "name": "string",
  • "label": "string",
  • "description": "string",
  • "enabled": true,
  • "send_notifications_to_members": false,
  • "notification_email_addresses": [
    ],
  • "reports_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "memberships": [
    ]
}
Update a group
Update a group with the given ID.


SecurityApiKey 
Request 
path Parameters
group_id
required
string <uuid>  (ResourceId)   <= 50 characters 
The group ID.


 
 Example:  4f6cf35x-2c4y-483z-a0a9-158621f77a21
Request Body schema: application/json
required
description
string
A description of the group.


 
enabled
boolean
 Default:  true
Whether the group is enabled.


 
label
required
string
The display label for the group.


 
name
string
The unique name of the group. Auto-generated from the label if not provided.


 
notification_email_addresses
Array of strings <email> 
A list of email addresses to receive notifications for this group. Useful for emails not associated with users. Note this is only evaluated if your account report_notifications setting notify_only_group_recipients is true.


 
send_notifications_to_members
boolean
 Default:  false
Whether to send notifications to group members. Note this is only evaluated if your account report_notifications setting notify_only_group_recipients is true.


 
Responses 
200
Group was updated successfully.


401
Unauthorized


403
Forbidden


404
Not Found


422
Unprocessable Entity


patch/groups/{group_id}
Request samples 
application/json
{
  • "label": "string"
}
Response samples 
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "object": "group",
  • "name": "string",
  • "label": "string",
  • "description": "string",
  • "enabled": true,
  • "send_notifications_to_members": false,
  • "notification_email_addresses": [
    ],
  • "reports_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "memberships": [
    ]
}
List group memberships
Retrieve a paginated list of memberships for a group. See Pagination.


SecurityApiKey 
Request 
path Parameters
group_id
required
string <uuid>  (ResourceId)   <= 50 characters 
The group ID.


 
 Example:  4f6cf35x-2c4y-483z-a0a9-158621f77a21
query Parameters
page
integer
The page number to retrieve.


 
per_page
integer
The maximum number of results per page.


 
Responses 
200
List of memberships.


401
Unauthorized


404
Not Found


get/groups/{group_id}/memberships
Request samples 
Response samples 
application/json
{
  • "object": "list",
  • "meta": {
    },
  • "data": [
    ]
}
Add a member to a group
Add an account user to a group.
 Group members can access the reports assigned to their group(s). They are restricted from accessing reports assigned to groups where they’re not members, as well as unassigned reports. 

 If the membership already exists, the existing membership is returned. Account owners cannot be added as group members.


SecurityApiKey 
Request 
path Parameters
group_id
required
string <uuid>  (ResourceId)   <= 50 characters 
The group ID.


 
 Example:  4f6cf35x-2c4y-483z-a0a9-158621f77a21
Request Body schema: application/json
required
account_user_id
required
string <uuid> 
The ID of the account user to add to the group.


 
Responses 
200
Membership already exists.


201
Membership was created successfully.


401
Unauthorized


403
Forbidden


404
Not Found


422
Unprocessable Entity


post/groups/{group_id}/memberships
Request samples 
application/json
{
  • "account_user_id": "aa809918-9412-40a8-b2fe-092591a90861"
}
Response samples 
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "group_id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "account_user_id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "user": {
    }
}
Get a group membership
Retrieve a specific membership within a group.


SecurityApiKey 
Request 
path Parameters
group_id
required
string <uuid>  (ResourceId)   <= 50 characters 
The group ID.


 
 Example:  4f6cf35x-2c4y-483z-a0a9-158621f77a21
membership_id
required
string <uuid>  (ResourceId)   <= 50 characters 
The membership ID.


 
 Example:  4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses 
200
Membership details.


401
Unauthorized


404
Not Found


get/groups/{group_id}/memberships/{membership_id}
Request samples 
Response samples 
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "group_id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "account_user_id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "user": {
    }
}
Remove a member from a group
Remove an account user from a group. This will not remove the account user from your account.


SecurityApiKey 
Request 
path Parameters
group_id
required
string <uuid>  (ResourceId)   <= 50 characters 
The group ID.


 
 Example:  4f6cf35x-2c4y-483z-a0a9-158621f77a21
membership_id
required
string <uuid>  (ResourceId)   <= 50 characters 
The membership ID.


 
 Example:  4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses 
200
Membership was removed successfully.


401
Unauthorized


403
Forbidden


404
Not Found


delete/groups/{group_id}/memberships/{membership_id}
Request samples 
Response samples 
application/json
{
  • "errors": [
    ]
}
➔ Next to Account Users