Groups
Groups are a collection of entities in Addepar. Use the Groups API to create and delete groups in Addepar, and retrieve and update group details.
| Base Route | /v1/groups |
| Endpoints | GET /v1/groups /v1/groups/:id /v1/groups/:id/relationships/members /v1/groups/:id/members /v1/groups/:id/child_groups POST /v1/groups /v1/groups/:id/relationships/members /v1/groups/:id/relationships/child_groups /v1/groups/query PATCH /v1/groups/:id /v1/groups /v1/groups/:id/relationships/members /v1/groups/:id/relationships/child_groups DELETE v1/groups/:id /v1/groups /v1/groups/:id/relationships/members |
| Produces | JSON |
| Pagination | Yes |
| Application Permissions Required | "API Access: Create, edit, and delete" "Portfolio Access" determines the groups that are accesible and entities that can be added as members. "Groups: Manage all groups" is required to create, edit, and delete groups. "Manage Attributes: Only edit certain attribute values or Manage all values and settings” is required to apply, edit, or delete attributes. |
| OAuth Scopes | GROUPS or GROUPS_WRITE |
Resource overview
Groups are described by the below resource object attributes. Attributes required for creating, updating, or deleting Groups are noted. You can assign additional standard and custom attributes to Groups.
All attributes will be returned in successful GET, POST & PATCH responses.
| Attribute | Description | Example |
|---|---|---|
name | Group name. String. Required. | "Smith Family" |
created_at | Not editable and cannot be passed in. String. | "2023-07-28T02:24:30Z" |
modified_at | Not editable and cannot be passed in. String. | "2023-07-30T10:43:21Z" |
| Optional Attributes | Additional attributes can be applied to groups. | See "Addepar Attributes" |
Relationships
| Relationship | Description |
|---|---|
members | A group can consist of one or more of the following portfolios: - Client ( PERSON_NODE)- Managed fund ( MANAGED_PARTNERSHIP)- Trust ( TRUST)- Holding company ( HOLDING_COMPANY)- Holding account ( FINANCIAL_ACCOUNT)It is guaranteed that the array does not contain duplicates. |
group_type | A group type is a way to categorize a group and adjust access to the group's members. A group's type must be specified during creation. The standard value is `GROUPS, which represents out of the box Addepar groups. |
child_groups | A nested member of the group that enables groups within a group. |
"relationships": {
"members": {
"links": {
"self": "/v1/groups/100/relationships/members",
"related": "/v1/groups/100/members"
},
"data": [
{ "type": "entities", "id": "200" },
{ "type": "entities", "id": "204" },
{ "type": "entities", "id": "360" },
{ "type": "entities", "id": "486" }
]
},
"group_type": {
"links": {
"self": "/v1/groups/100/relationships/group_type",
"related": "/v1/groups/100/group_type"
},
"data": {
"type": "group_types",
"id": "GROUPS"
}
},
"child_groups": {
"links": {
"self": "/v1/groups/100/relationships/child_groups",
"related": "/v1/groups/100/child_groups"
},
"data": []
}
}
Get All Groups
Retrieves all groups you have access to. Returns attributes for each group, as well as a list of all entities within each group.
GET /v1/groups
Example:
GET https://examplefirm.addepar.com/api/v1/groups
HTTP/1.1 200
{
"data":[
{
"type":"groups",
"id":"100",
"attributes":{
"name":"Group 1",
"created_at": "2023-07-28T02:24:30Z",
"modified_at": "2023-07-30T10:43:21Z"
},
"relationships":{
"members":{
"links":{
"self":"/v1/groups/100/relationships/members",
"related":"/v1/groups/100/members"
},
"data":[
{
"type":"entities",
"id":"200"
},
{
"type":"entities",
"id":"204"
},
{
"type":"entities",
"id":"360"
},
{
"type":"entities",
"id":"486"
}
]
},
"group_type":{
"links":{
"self":"/v1/groups/100/relationships/group_type",
"related":"/v1/groups/100/group_type"
},
"data":{
"type":"group_types",
"id":"GROUPS"
}
},
"child_groups":{
"links":{
"self":"/v1/groups/100/relationships/child_groups",
"related":"/v1/groups/100/child_groups"
},
"data":[
]
}
},
"links":{
"self":"/v1/groups/100"
}
},
{
"type":"groups",
"id":"101",
"attributes":{
"name":"Group 2",
"created_at": "2023-07-28T02:24:30Z",
"modified_at": "2023-07-30T10:43:21Z"
},
"relationships":{
"members":{
"links":{
"self":"/v1/groups/101/relationships/members",
"related":"/v1/groups/101/members"
},
"data":[
{
"type":"entities",
"id":"102"
},
{
"type":"entities",
"id":"289"
},
{
"type":"entities",
"id":"349"
},
{
"type":"entities",
"id":"438"
}
]
},
"group_type":{
"links":{
"self":"/v1/groups/101/relationships/group_type",
"related":"/v1/groups/101/group_type"
},
"data":{
"type":"group_types",
"id":"HH_GROUPS"
}
},
"child_groups":{
"links":{
"self":"/v1/groups/101/relationships/child_groups",
"related":"/v1/groups/101/child_groups"
},
"data":[
{
"type":"groups",
"id":"102"
}
]
}
},
"links":{
"self":"/v1/groups/101"
}
}
],
"included":[
]
}
Optional parameters
| Filter | Description | Example |
|---|---|---|
| group_types | Returns only groups matching group type ID specified. | filter[group_types]="Advisor Group" |
| created_before | Returns all groups created on or before a date, formatted as YYYY-MM-DD. | filter[created_before]="2023-04-12" |
| created_after | Returns all groups created on or after a date, formatted as YYYY-MM-DD. | filter[created_after]="2023-04-12" |
| modified_before | Returns all groups last modified on or before a date, formatted as YYYY-MM-DD. | filter[modified_before]="2023-04-12" |
| modified_after | Returns all groups last modified on or after a date, formatted as YYYY-MM-DD. | filter[modified_after]="2023-04-12" |
| fields[groups] | Returns only the attributes specified for each group. Ignores spaces. | fields[groups]=name |
Response Codes:
200 OK: Success400 Bad Request: Invalid payload403 Forbidden: You do not have permission to access the API404 Not Found: The group does not exist or you do not have access to it
Get a Group
Retrieves a specific group based on its ID. Returns all group attributes, as well as a list of all members within the group.
GET /v1/groups/:id
Example:
GET https://examplefirm.addepar.com/api/v1/groups/5
HTTP/1.1 200
{
"data":{
"type":"groups",
"id":"5",
"attributes":{
"name":"Group 1",
"created_at": "2023-07-28T02:24:30Z",
"modified_at": "2023-07-30T10:43:21Z"
},
"relationships":{
"members":{
"links":{
"self":"/v1/groups/5/relationships/members",
"related":"/v1/groups/5/members"
},
"data":[
{
"type":"entities",
"id":"22"
},
{
"type":"entities",
"id":"24"
},
{
"type":"entities",
"id":"117"
}
]
},
"group_type":{
"links":{
"self":"/v1/groups/5/relationships/group_type",
"related":"/v1/groups/5/group_type"
},
"data":{
"type":"group_types",
"id":"GROUPS"
}
},
"child_groups":{
"links":{
"self":"/v1/groups/5/relationships/child_groups",
"related":"/v1/groups/5/child_groups"
},
"data":[
{
"type":"groups",
"id":"6"
}
]
}
},
"links":{
"self":"/v1/groups/5"
}
},
"included":[
]
}
Response Codes:
200 OK: Success400 Bad Request: Invalid payload403 Forbidden: You do not have permission to access the API404 Not Found: The group does not exist or you do not have access to it
Get a Group's Members
Returns a list of all relationships for the members of the specified group.
GET /v1/groups/:id/relationships/members
Example:
GET https://examplefirm.addepar.com/api/v1/groups/5678/relationships/members
HTTP/1.1 200
{
"data": [
{
"type": "entities",
"id": "2000001"
},
{
"type": "entities",
"id": "2000002"
}
]
}
Response Codes:
200 OK: Success403 Forbidden: You do not have permission to access the API404 Not Found: The group does not exist or you do not have access to it.
Get a Group's Member Details
Returns details of all the entities that are members of the specified group. Refer to the Entities API for details about the supported attributes and relationships, including sample responses.
GET /v1/groups/:id/members
Example:
GET https://examplefirm.addepar.com/api/v1/groups/5678/members
HTTP/1.1 200
{
"data": [
{
"id": "2000001",
"type": "entities",
"attributes": {
"currency_factor": "USD",
"original_name": "Adam Smith",
"model_type": "PERSON_NODE"
},
"links": {
"self": "/v1/entities/2000001"
}
},
{
"id": "2000002",
"type": "entities",
"attributes": {
"currency_factor": "USD",
"ownership_type": "PERCENT_BASED",
"original_name": "X092849032",
"display_name": "Citco",
"model_type": "FINANCIAL_ACCOUNT",
"is_rolled_up": false
},
"links": {
"self": "/v1/entities/2000002"
}
}
],
"links": {
"next": null
}
}
Response Codes:
200 OK: Success403 Forbidden: You do not have permission to access the API404 Not Found: The group does not exist or you do not have access to it
Get a Group's Child Groups
Retrieve a group's child groups.
GET /v1/groups/:id/child_groups
Example:
GET https://examplefirm.addepar.com/v1/groups/1/child_groups
HTTP/1.1 200
{
"data":[
{
"id":"92",
"type":"groups",
"attributes":{
"name":"Child Group",
"created_at": "2023-07-28T02:24:30Z",
"modified_at": "2023-07-30T10:43:21Z"
},
"relationships":{
"members":{
"links":{
"self":"/v1/groups/92/relationships/members",
"related":"/v1/groups/92/members"
},
"data":[
{
"type":"entities",
"id":"12"
}
]
},
"child_groups":{
"links":{
"self":"/v1/groups/92/relationships/child_groups",
"related":"/v1/groups/92/child_groups"
},
"data":[
]
},
"group_type":{
"links":{
"self":"/v1/groups/92/relationships/group_type",
"related":"/v1/groups/92/group_type"
},
"data":{
"type":"group_types",
"id":"GROUPS"
}
}
},
"links":{
"self":"/v1/groups/92"
}
}
],
"included":[
],
"links":{
"next":null
}
}
Response Codes:
200 Ok: Success403 Forbidden: You do not have permission to access the API404 Not Found: The child group does not exist or you do not have access to it
Create a Group
Adds a new group to your firm. You must specify the type, name, and group_type of the group.
Returns the details of the new group.
POST /v1/groups
Example:
POST https://examplefirm.addepar.com/api/v1/groups
{
"data":{
"type":"groups",
"attributes":{
"name":"New Group"
},
"relationships":{
"group_type":{
"data":{
"type":"group_types",
"id":"GROUPS"
}
}
}
}
}
HTTP/1.1 201 Created
{
"data":{
"id":"1494728",
"type":"groups",
"attributes":{
"name":"New Group"
},
"relationships":{
"members":{
"links":{
"self":"/v1/groups/1494728/relationships/members",
"related":"/v1/groups/1494728/members"
},
"data":[
]
},
"child_groups":{
"links":{
"self":"/v1/groups/1494728/relationships/child_groups",
"related":"/v1/groups/1494728/child_groups"
},
"data":[
]
},
"group_type":{
"links":{
"self":"/v1/groups/1494728/relationships/group_type",
"related":"/v1/groups/1494728/group_type"
},
"data":{
"type":"group_types",
"id":"GROUPS"
}
}
},
"links":{
"self":"/v1/groups/1494728"
}
},
"included":[
]
}
Response Codes:
201 Created: Success400 Bad Request: Invalid payload; an entity included either does not exist, or you do not have access to it or the group_type ID does not exist, or you do not have access to it403 Forbidden: You do not have permission to access the API, or you can't modify a passed in attribute404 Not Found: You don't have access to one or more group members or one or more members don't exist, or one or more attributes don't exist409 Conflict: "Type" was not specified as "groups" or one or more members were not specified as "entities"
Create a Child Group
Adds a new child group to an existing group.
POST /v1/groups/:id/relationships/child_groups
Example:
POST https://examplefirm.addepar.com/api/v1/groups/1/relationships/child_groups
{
"data": [
{
"type": "groups",
"id": "92"
}
]
}
HTTP/1.1 204 No Content
Response Codes:
201 OK: Success403 Forbidden: You do not have permission to access the API404 Not Found: The group does not exist or you do not have access to it
Create Multiple Groups
Adds a new group to your firm. You must specify the type, name, and group_type of the group.
Returns the details of each group created.
POST /v1/groups/
Example:
POST https://examplefirm.addepar.com/api/v1/groups
{
"data":[
{
"type":"groups",
"attributes":{
"name":"Group 1"
},
"relationships":{
"members":{
"data":[
{
"type":"entities",
"id":"34"
},
{
"type":"entities",
"id":"219"
}
]
},
"group_type":{
"data":{
"type":"group_types",
"id":"GROUPS"
}
}
}
},
{
"type":"groups",
"attributes":{
"name":"Group 2"
},
"relationships":{
"members":{
"data":[
{
"type":"entities",
"id":"22"
},
{
"type":"entities",
"id":"24"
}
]
},
"group_type":{
"data":{
"type":"group_types",
"id":"GROUPS"
}
}
}
}
]
}
HTTP/1.1 201 Created
{
"data":[
{
"id":"11",
"type":"groups",
"attributes":{
"name":"Group 1"
},
"relationships":{
"members":{
"links":{
"self":"/v1/groups/11/relationships/members",
"related":"/v1/groups/11/members"
},
"data":[
{
"type":"entities",
"id":"34"
},
{
"type":"entities",
"id":"219"
}
]
},
"group_type":{
"links":{
"self":"/v1/groups/11/relationships/group_type",
"related":"/v1/groups/11/group_type"
},
"data":{
"type":"group_types",
"id":"GROUPS"
}
},
"child_groups":{
"links":{
"self":"/v1/groups/11/relationships/child_groups",
"related":"/v1/groups/11/child_groups"
},
"data":[
]
}
},
"links":{
"self":"/v1/groups/11"
}
},
{
"id":"169",
"type":"groups",
"attributes":{
"name":"Group 2"
},
"relationships":{
"members":{
"links":{
"self":"/v1/groups/169/relationships/members",
"related":"/v1/groups/169/members"
},
"data":[
{
"type":"entities",
"id":"22"
},
{
"type":"entities",
"id":"24"
}
]
},
"group_type":{
"links":{
"self":"/v1/groups/169/relationships/group_type",
"related":"/v1/groups/169/group_type"
},
"data":{
"type":"group_types",
"id":"GROUPS"
}
},
"child_groups":{
"links":{
"self":"/v1/groups/169/relationships/child_groups",
"related":"/v1/groups/169/child_groups"
},
"data":[
]
}
},
"links":{
"self":"/v1/groups/169"
}
}
],
"included":[
]
}
Response Codes:
201 Created: Success400 Unauthorized: Invalid payload; or an entity included either does not exist, or you do not have access to it403 Forbidden: You do not have permission to access the API404 Not Found: The group_type ID does not exist, or you do not have access to it409 Conflict: "Type" was not specified as "groups" or one or more members were not specified as "entities"
Add Group Members
Adds existing entities as members to a group. Returns an empty response.
POST /v1/groups/:id/relationships/members
Example:
POST https://examplefirm.addepar.com/api/v1/groups/5678/relationships/members
{
"data": [
{
"type": "entities",
"id": "100"
},
{
"type": "entities",
"id": "101"
}
]
}
HTTP/1.1 204 No Content
Response Codes:
204 No Content: Success400 Bad Request: One or more group members is not a valid type: client, account, holding company, trust, managed fund403 Forbidden: You do not have permission to access the API, you don't have access to the group itself, or you do not have access to the type of group404 Not Found: The group does not exist, or you do not have access to it409 Conflict: The input type of member is not "entities"
Search for Groups by Name, Group Types & External ID
For a refined list of results, you can retrieve only groups with a specific display name, group type or external ID.
POST /v1/groups/query
Example:
POST https://examplefirm.addepar.com/api/v1/groups/query
{
"data":{
"type":"group_search",
"attributes":{
"display_names":[
"All",
"Limited",
"Group"
],
"group_types":[
"GROUPS",
"HOUSEHOLDS"
],
"external_ids":[
{
"external_id_type":"random_system",
"external_id":"34e0ec90-9ebb-4f25-9ee4-b86121c14c67"
}
]
}
}
}
HTTP/1.1 200
{
"data":[
{
"id":"7",
"type":"groups",
"attributes":{
"name":"Limited Clients Access Group",
"external_id_random_system":"34e0ec90-9ebb-4f25-9ee4-b86121c14c67"
},
"relationships":{
"members":{
"links":{
"self":"/v1/groups/7/relationships/members",
"related":"/v1/groups/7/members"
},
"data":[
]
},
"group_type":{
"links":{
"self":"/v1/groups/7/relationships/group_type",
"related":"/v1/groups/7/group_type"
},
"data":{
"type":"group_types",
"id":"GROUPS"
}
},
"child_groups":{
"links":{
"self":"/v1/groups/7/relationships/child_groups",
"related":"/v1/groups/7/child_groups"
},
"data":[
]
}
},
"links":{
"self":"/v1/groups/7"
}
}
],
"included":[
],
"links":{
"next":null
}
}
Response Codes:
200 OK: Success400 Forbidden: Missing or invalid attribute. One of [display_names,group_types,external_ids] is required.403 Forbidden: You do not have permission to access the API
Update a Group
Adds, modifies, or deletes the attributes of an existing group.
PATCH /v1/groups/:id
Example:
This example is for Addepar's Standard Attributes. See Addepar Attributes for a Custom Attribute example.
PATCH https://examplefirm.addepar.com/api/v1/groups/1111
{
"data": {
"id": "1111"
"type": "groups",
"attributes": {
"name": "Updated Group Name"
}
}
}
HTTP/1.1 200
{
"data":{
"id":"1111",
"type":"groups",
"attributes":{
"name":"Updated Group Name"
},
"relationships":{
"members":{
"links":{
"self":"/v1/groups/1111/relationships/members",
"related":"/v1/groups/1111/members"
},
"data":[
{
"type":"entities",
"id":"2000001"
},
{
"type":"entities",
"id":"2000002"
}
]
}
},
"child_groups":{
"links":{
"self":"/v1/groups/169/relationships/child_groups",
"related":"/v1/groups/169/child_groups"
},
"data":[
]
},
"links":{
"self":"/v1/groups/1111"
}
}
}
Response Codes:
200 OK: Success400 Bad Request: Invalid payload; or an entity included either does not exist, or you do not have access to it403 Forbidden: You do not have permission to access the API, or you do not have access to the group404 Not Found: The group ID does not exist, or you do not have access to it
Update Multiple Groups
Adds, modifies, or deletes attributes of existing groups.
PATCH /v1/groups
Example:
PATCH https://examplefirm.addepar.com/api/v1/groups
{
"data":[
{
"type":"groups",
"id":"169",
"attributes":{
"name":"Group 1"
},
"relationships":{
"members":{
"data":[
{
"type":"entities",
"id":"22"
},
{
"type":"entities",
"id":"117"
}
]
},
"child_groups":{
"data":[
{
"type":"groups",
"id":"85"
}
]
}
}
},
{
"type":"groups",
"id":"185",
"attributes":{
"name":"Group 2"
},
"relationships":{
"members":{
"data":[
{
"type":"entities",
"id":"22"
},
{
"type":"entities",
"id":"24"
}
]
}
}
}
]
}
HTTP/1.1 200
{
"data":[
{
"id":"11",
"type":"groups",
"attributes":{
"name":"Group 1"
},
"relationships":{
"members":{
"links":{
"self":"/v1/groups/11/relationships/members",
"related":"/v1/groups/11/members"
},
"data":[
{
"type":"entities",
"id":"34"
},
{
"type":"entities",
"id":"219"
},
{
"type":"entities",
"id":"957"
}
]
},
"group_type":{
"links":{
"self":"/v1/groups/11/relationships/group_type",
"related":"/v1/groups/11/group_type"
},
"data":{
"type":"group_types",
"id":"GROUPS"
}
},
"child_groups":{
"links":{
"self":"/v1/groups/11/relationships/child_groups",
"related":"/v1/groups/11/child_groups"
},
"data":[
]
}
},
"links":{
"self":"/v1/groups/11"
}
},
{
"id":"169",
"type":"groups",
"attributes":{
"name":"Group 2"
},
"relationships":{
"members":{
"links":{
"self":"/v1/groups/169/relationships/members",
"related":"/v1/groups/169/members"
},
"data":[
{
"type":"entities",
"id":"22"
},
{
"type":"entities",
"id":"24"
},
{
"type":"entities",
"id":"117"
}
]
},
"group_type":{
"links":{
"self":"/v1/groups/169/relationships/group_type",
"related":"/v1/groups/169/group_type"
},
"data":{
"type":"group_types",
"id":"GROUPS"
}
},
"child_groups":{
"links":{
"self":"/v1/groups/169/relationships/child_groups",
"related":"/v1/groups/169/child_groups"
},
"data":[
{
"type":"groups",
"id":"85"
}
]
}
},
"links":{
"self":"/v1/groups/169"
}
}
],
"included":[
]
}
Response Codes:
200 OK: Success400 Bad Request: Invalid payload; or an entity included in not a valid type: client, account, holding company, trust, managed fund403 Forbidden: You do not have permission to access the API; you do not have access to the type of group, or you can't modify one or more passed in attributes404 Not Found: The group_type ID does not exist, or you do not have access to it; you don't have access to one or more members or they don't exist; or a passed in attribute does not exist409 Conflict: The ID in the URL doesn't match the ID in the payload; the "type" was not specified as "groups"; or one or more members is not an entity
Replace Group Members
Replaces all the existing group members with new ones. Returns an empty response.
PATCH /v1/groups/:id/relationships/members
Example:
PATCH https://examplefirm.addepar.com/api/v1/groups/5678/relationships/members
{
"data": [
{
"type": "entities",
"id": "100"
},
{
"type": "entities",
"id": "101"
}
]
}
HTTP/1.1 204 No Content
Response Codes:
204 No Content: Success400 Bad Request: One or more group members in not a valid type: client, account, holding company, trust, managed fund403 Forbidden: You do not have permission to access the API, you don't have access to the group itself, or you do not have access to the type of group404 Not Found: The group does not exist, or you do not have access to it409 Conflict: The input type of member is not "entities"
Replace a Group's Child Groups
Replaces all the existing group members with new ones. Returns an empty response.
PATCH /v1/groups/:id/relationships/child_groups
Example:
PATCH https://examplefirm.addepar.com/api/v1/groups/111/relationships/child_groups
{
"data": [
{
"type": "groups",
"id": "92"
}
]
}
HTTP/1.1 204 No Content
Response Codes:
204 No Content: Success400 Bad Request: One or more group members in not a valid type: client, account, holding company, trust, managed fund403 Forbidden: You do not have permission to access the API, you don't have access to the group itself, or you do not have access to the type of group404 Not Found: The group does not exist, or you do not have access to it
Delete a Group
Deletes a group from your firm. Returns an empty response.
DELETE /v1/groups/:id
Example:
DELETE https://examplefirm.addepar.com/api/v1/groups/1111
HTTP/1.1 204 No Content
Response Codes:
204 No Content: Success403 Forbidden: You do not have access to the group itself or the type of group404 Not Found: The group does not exist409 Conflict: The ID in the URL doesn't match the ID in the payload; the "type" was not specified as "groups"; or one or more members is not an entity
Delete Multiple Groups
Deletes multiple existing groups from your firm. Returns an empty response.
DELETE /v1/groups
Example:
DELETE https://examplefirm.addepar.com/api/v1/groups
{
"data": [ {
"id": "1111",
"type": "groups"
},
{
"id": "1112",
"type": "groups"
}
]
}
HTTP/1.1 204 No Content
Responses:
204 No Content: Success403 Forbidden: You do not have access to one or more groups or types of groups404 Not Found: One or more groups do not exist409 Conflict: The ID in the URL doesn't match the ID in the payload; the "type" for one or more groups was not specified as "groups"; or one or more members is not an entity
Remove Group Members
Removes members of a group. Returns an empty response.
DELETE /v1/groups/:id/relationships/members
Example:
DELETE https://examplefirm.addepar.com/api/v1/groups/5678/relationships/members
{
"data": [
{
"type": "entities",
"id": "2000001"
}
]
}
HTTP/1.1 204 No Content
Responses:
204 No Content: Success400 Bad Request: One or more group members in not a valid type: client, account, holding company, trust, managed fund403 Forbidden: You do not have permission to access the API, you don't have access to the group itself, or you do not have access to the type of group404 Not Found: The group does not exist, or you do not have access to it409 Conflict: The input type of member is not "entities"
Updated about 2 months ago