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/:id
/v1/groups
/v1/groups/:id/relationships/members
/v1/groups/:id/members

POST
/v1/groups
/v1/groups/
/v1/groups/:id/relationships/members
/v1/groups/query

PATCH
/v1/groups/:id
/v1/groups
/v1/groups/:id/relationships/members

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

S

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

e

Group name. String. Required.

"

Optional Attributes

Additional attributes can be applied to groups.

See "Addepar Attributes"

Relationships

Relationship

Description

s

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.

e

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.

"relationships":{
        "members":{
          "links":{
            "self":"/v1/groups/9559/relationships/members",
            "related":"/v1/groups/9559/members"
          },
          "data":[
            {
              "type":"entities",
              "id":"259911"
            },
            {
              "type":"entities",
              "id":"259914"
            }
          ]
        },
        "group_type":{
          "links":{
            "self":"/v1/groups/9559/relationships/group_type",
            "related":"/v1/groups/9559/group_type"
          },
          "data":{
            "type":"group_types",
            "id":"GROUPS"
          }
        }
      }

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/9559
HTTP/1.1 200

{
    "data": {
        "id": "9559",
        "type": "groups",
        "attributes": {
            "name": "Bradford Trust"
        },
        "relationships": {
            "members": {
                "links": {
                    "self": "/v1/groups/9559/relationships/members",
                    "related": "/v1/groups/9559/members"
                },
                "data": [
                    {
                        "type": "entities",
                        "id": "259911"
                    },
                    {
                        "type": "entities",
                        "id": "259914"
                    }
                ]
            },
            "group_type": {
                "links": {
                    "self": "/v1/groups/9559/relationships/group_type",
                    "related": "/v1/groups/9559/group_type"
                },
                "data": {
                    "type": "group_types",
                    "id": "GROUPS"
                }
            }
        },
        "links": {
            "self": "/v1/groups/9559"
        }
    },
    "included": []
}

Response Codes:

  • 200 OK: Success
  • 400 Bad Request: Invalid payload
  • 403 Forbidden: You do not have permission to access the API
  • 404 Not Found: The group does not exist or you do not have access to it

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": [
        {
            "id": "5",
            "type": "groups",
            "attributes": {
                "name": "Group 1"
            },
            "relationships": {
                "members": {
                    "links": {
                        "self": "/v1/groups/5/relationships/members",
                        "related": "/v1/groups/5/members"
                    },
                    "data": [
                        {
                            "type": "entities",
                            "id": "117"
                        },
                        {
                            "type": "entities",
                            "id": "22"
                        },
                        {
                            "type": "entities",
                            "id": "24"
                        }
                    ]
                },
                "group_type": {
                    "links": {
                        "self": "/v1/groups/5/relationships/group_type",
                        "related": "/v1/groups/5/group_type"
                    },
                    "data": {
                        "type": "group_types",
                        "id": "GROUPS"
                    }
                }
            },
            "links": {
                "self": "/v1/groups/5"
            }
        },
        {
            "id": "6",
            "type": "groups",
            "attributes": {
                "name": "All Funds"
            },
            "relationships": {
                "members": {
                    "links": {
                        "self": "/v1/groups/6/relationships/members",
                        "related": "/v1/groups/6/members"
                    },
                    "data": [
                        {
                            "type": "entities",
                            "id": "116"
                        },
                        {
                            "type": "entities",
                            "id": "151"
                        },
                        {
                            "type": "entities",
                            "id": "152"
                        }
                    ]
                },
                "group_type": {
                    "links": {
                        "self": "/v1/groups/6/relationships/group_type",
                        "related": "/v1/groups/6/group_type"
                    },
                    "data": {
                        "type": "group_types",
                        "id": "GROUPS"
                    }
                }
            },
            "links": {
                "self": "/v1/groups/6"
            }
        },
        {
            "id": "7",
            "type": "groups",
            "attributes": {
                "name": "Limited Clients Access Group"
            },
            "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"
                    }
                }
            },
            "links": {
                "self": "/v1/groups/7"
            }
        }
    ],
    "included": [],
    "links": {
        "next": null
    }
}

Response Codes:

  • 200 OK: Success
  • 400 Bad Request: Invalid payload
  • 403 Forbidden: You do not have permission to access the API
  • 404 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: Success
  • 403 Forbidden: You do not have permission to access the API
  • 404 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: Success
  • 403 Forbidden: You do not have permission to access the API
  • 404 Not Found: The 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":{
      "type":"groups",
      "attributes":{
         "name":"New Group"
      },
      "relationships":{
         "group_type":{
            "data":{
               "type":"group_types",
               "id":"GROUPS"
            }
         }
      }
   }
}

Response Codes:

  • 201 Created: Success
  • 400 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 it
  • 403 Forbidden: You do not have permission to access the API, or you can't modify a passed in attribute
  • 404 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 exist
  • 409 Conflict: "Type" was not specified as "groups" or one or more members were not specified as "entities"

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": "New Group 1"
      },
      "relationships": {
       "members": {
        "data": [
              {
              "type": "entities",
              "id": "2000001"
              },
              {
              "type": "entities",
              "id": "2000002"
              }
          ]
      },
      "group_type": {
          "data": {
          "type": "group_types",
          "id": "GROUPS"
          }
      }
  },
{
      "type": "groups",
      "attributes": {
        "name": "New Group 2"
        "sector": [
        {
           "date": "2017-01-01",
           "value": "Large Cap",
           "weight": 0.5
        }
     ]
   },
      "relationships": {
         "members": {
        "data": [
              {
              "type": "entities",
              "id": "2000003"
              },
              {
              "type": "entities",
              "id": "2000004"
              }
           ]
         },
        "group_type": {
            "data": {
            "type": "group_types",
            "id": "GROUPS"
         }
          }
       }
     }
  ]
}
HTTP/1.1 201 Created

{
  "data": [
        {
     "id": "1113"
        "type": "groups",
        "attributes": {
          "name": "New Group 1"
         },
        "relationships": {
          "members": {
            "links": {
              "self": "/v1/groups/1113/relationships/members",
              "related": "/v1/groups/1113/members"
            },
             "data": [
                {
                "type": "entities",
                "id": "2000001"
                },
                {
                "type": "entities",
                "id": "2000002"
                }
            ]
        }
    },
    "links": {
      "self": "/v1/groups/1113"
    }
  },
{
    "id": "1114"
       "type": "groups",
       "attributes": {
          "name": "New Group 2"
          "sector": [
             {
             "date": "2017-01-01",
             "value": "Large Cap",
             "weight": 0.5
              }
           ]
        },
        "relationships": {
            "members": {
              "links": {
                  "self": "/v1/groups/1114/relationships/members",
                  "related": "/v1/groups/1114/members"
               },
              "data": [
                {
                "type": "entities",
                "id": "2000003"
                },
               {
                "type": "entities",
                "id": "2000004"
                }
            ]
        }
    },
    "links": {
      "self": "/v1/groups/1114"
    }
  }
 ]
}

Response Codes:

  • 201 Created: Success
  • 400 Unauthorized: Invalid payload; or an entity included either does not exist, or you do not have access to it
  • 403 Forbidden: You do not have permission to access the API
  • 404 Not Found: The group_type ID does not exist, or you do not have access to it
  • 409 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: Success
  • 400 Bad Request: One or more group members is not a valid type: client, account, holding company, trust, managed fund
  • 403 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 group
  • 404 Not Found: The group does not exist, or you do not have access to it
  • 409 Conflict: The input type of member is not "entities"

Search for Groups by Name & Group Types

For a refined list of results, you can retrieve only groups with a specific display name or group type.

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"
      ]
    }
  }
}
HTTP/1.1 200

{
  "data":[
    {
      "id":"5",
      "type":"groups",
      "attributes":{
        "name":"Group 1"
      },
      "relationships":{
        "members":{
          "links":{
            "self":"/v1/groups/5/relationships/members",
            "related":"/v1/groups/5/members"
          },
          "data":[
            {
              "type":"entities",
              "id":"117"
            },
            {
              "type":"entities",
              "id":"22"
            },
            {
              "type":"entities",
              "id":"24"
            }
          ]
        },
        "group_type":{
          "links":{
            "self":"/v1/groups/5/relationships/group_type",
            "related":"/v1/groups/5/group_type"
          },
          "data":{
            "type":"group_types",
            "id":"GROUPS"
          }
        }
      },
      "links":{
        "self":"/v1/groups/5"
      }
    },
    {
      "id":"6",
      "type":"groups",
      "attributes":{
        "name":"All Funds"
      },
      "relationships":{
        "members":{
          "links":{
            "self":"/v1/groups/6/relationships/members",
            "related":"/v1/groups/6/members"
          },
          "data":[
            {
              "type":"entities",
              "id":"116"
            },
            {
              "type":"entities",
              "id":"151"
            },
            {
              "type":"entities",
              "id":"152"
            }
          ]
        },
        "group_type":{
          "links":{
            "self":"/v1/groups/6/relationships/group_type",
            "related":"/v1/groups/6/group_type"
          },
          "data":{
            "type":"group_types",
            "id":"GROUPS"
          }
        }
      },
      "links":{
        "self":"/v1/groups/6"
      }
    },
    {
      "id":"7",
      "type":"groups",
      "attributes":{
        "name":"Limited Clients Access Group"
      },
      "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"
          }
        }
      },
      "links":{
        "self":"/v1/groups/7"
      }
    },
    {
      "id":"8",
      "type":"groups",
      "attributes":{
        "name":"New Group"
      },
      "relationships":{
        "members":{
          "links":{
            "self":"/v1/groups/8/relationships/members",
            "related":"/v1/groups/8/members"
          },
          "data":[
            
          ]
        },
        "group_type":{
          "links":{
            "self":"/v1/groups/8/relationships/group_type",
            "related":"/v1/groups/8/group_type"
          },
          "data":{
            "type":"group_types",
            "id":"GROUPS"
          }
        }
      },
      "links":{
        "self":"/v1/groups/8"
      }
    }
  ],
  "included":[
    
  ],
  "links":{
    "next":null
  }
}

Response Codes:

  • 200 OK: Success
  • 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": "5678"
       "type": "groups",
       "attributes": {
         "name": "Updated Group Name"
    }
  }
}
HTTP/1.1 200 

{
  "data": {
    "id": "5678"
       "type": "groups",
       "attributes": {
          "name": "Updated Group Name"
    },
    "relationships": {
      "members": {
        "links": {
          "self": "/v1/groups/5678/relationships/members",
          "related": "/v1/groups/5678/members"
        },
        "data": [
        {
            "type": "entities",
            "id": "2000001"
             },
             {
            "type": "entities",
            "id": "2000002"
          }
      ]
      }
    },
    "links": {
      "self": "/v1/groups/5678"
    }
  }
}

Response Codes:

  • 200 OK: Success
  • 400 Bad Request: Invalid payload; or an entity included either does not exist, or you do not have access to it
  • 403 Forbidden: You do not have permission to access the API, or you do not have access to the group
  • 404 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
HTTP/1.1 200 Created

{
  "data": [
        {
     "id": "1113"
        "type": "groups",
        "attributes": {
          "name": "New Group 1"
         },
        "relationships": {
          "members": {
            "links": {
              "self": "/v1/groups/1113/relationships/members",
              "related": "/v1/groups/1113/members"
            },
             "data": [
                {
                "type": "entities",
                "id": "2000001"
                },
                {
                "type": "entities",
                "id": "2000002"
                }
            ]
        }
    },
    "links": {
      "self": "/v1/groups/1113"
    }
  },
{
    "id": "1114"
       "type": "groups",
       "attributes": {
          "name": "New Group 2"
          "sector": [
             {
             "date": "2017-01-01",
             "value": "Large Cap",
             "weight": 0.5
              }
           ]
        },
        "relationships": {
            "members": {
              "links": {
                  "self": "/v1/groups/1114/relationships/members",
                  "related": "/v1/groups/1114/members"
               },
              "data": [
                {
                "type": "entities",
                "id": "2000003"
                },
               {
                "type": "entities",
                "id": "2000004"
                }
            ]
        }
    },
    "links": {
      "self": "/v1/groups/1114"
    }
  }
 ]
}

Response Codes:

  • 200 OK: Success
  • 400 Bad Request: Invalid payload; or an entity included in not a valid type: client, account, holding company, trust, managed fund
  • 403 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 attributes
  • 404 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 exist
  • 409 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: Success
  • 400 Bad Request: One or more group members in not a valid type: client, account, holding company, trust, managed fund
  • 403 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 group
  • 404 Not Found: The group does not exist, or you do not have access to it
  • 409 Conflict: The input type of member is not "entities"

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: Success
  • 403 Forbidden: You do not have access to the group itself or the type of group
  • 404 Not Found: The group does not exist
  • 409 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: Success
  • 403 Forbidden: You do not have access to one or more groups or types of groups
  • 404 Not Found: One or more groups do not exist
  • 409 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: Success
  • 400 Bad Request: One or more group members in not a valid type: client, account, holding company, trust, managed fund
  • 403 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 group
  • 404 Not Found: The group does not exist, or you do not have access to it
  • 409 Conflict: The input type of member is not "entities"

Updated 13 days ago


Groups


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.