Groups

Groups organize entities into named collections for portfolio scoping, reporting, and access control. Every group belongs to a group type that determines its permission model. Groups can contain entity members (clients, accounts, funds) and nested child groups for hierarchical structures.

Use this API to create groups, manage membership, query by name or external ID, and build group hierarchies.

Overview

📘

Access requirements

API Access: Create, edit, and delete.
Portfolio Access: Determines which groups are visible and which entities can be added.
Groups: "Manage all groups" required for create, edit, and delete.
Manage Attributes: Required to set custom attributes on groups.

Resource attributes

Groups also accept custom Addepar Attributes.

Relationships

Get all groups

Returns all accessible groups with attributes and membership.

GET /v1/groups

curl -X GET "https://{firm}.addepar.com/api/v1/groups" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Accept: application/vnd.api+json"

{
  "data": [
    {
      "id": "100",
      "type": "groups",
      "attributes": {
        "created_at": "2023-07-28T02:24:30Z",
        "modified_at": "2023-07-30T10:43:21Z",
        "name": "Smith Family"
      },
      "relationships": {
        "members": {
          "data": [
            {"type": "entities", "id": "200"},
            {"type": "entities", "id": "204"}
          ]
        },
        "group_type": {
          "data": {"type": "group_types", "id": "HH_GROUPS"}
        },
        "child_groups": { "data": [] }
      },
      "links": { "self": "/v1/groups/100" }
    }
  ],
  "included": [],
  "links": { "next": "/v1/groups?page[limit]=25&page[cursor]=abc123" }
}

Filter parameters:

Response codes:

• 200 OK -- Success
• 400 Bad Request -- Invalid filter
• 403 Forbidden -- Insufficient permissions

Get a group

GET /v1/groups/:id

Returns a single group with attributes, members, and child groups.

Response codes:

• 200 OK -- Success
• 403 Forbidden -- Insufficient permissions
• 404 Not Found -- Group does not exist or not accessible

Get group members

Two endpoints for member data:

Response codes:

• 200 OK -- Success
• 403 Forbidden -- Insufficient permissions
• 404 Not Found -- Group does not exist or not accessible

Get child groups

GET /v1/groups/:id/child_groups

Returns full group resources for all direct children.

Response codes:

• 200 OK -- Success
• 403 Forbidden -- Insufficient permissions
• 404 Not Found -- Group does not exist or not accessible

Create groups

Creates one or more groups. Pass a single object or array (for bulk creation).

POST /v1/groups

Required: name attribute and group_type relationship.

curl -X POST "https://{firm}.addepar.com/api/v1/groups" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "groups",
      "attributes": { "name": "Advisory Team A" },
      "relationships": {
        "members": {
          "data": [
            {"type": "entities", "id": "34"},
            {"type": "entities", "id": "219"}
          ]
        },
        "group_type": {
          "data": {"type": "group_types", "id": "GROUPS"}
        }
      }
    }
  }'

{
  "data": {
    "id": "1494728",
    "type": "groups",
    "attributes": { "name": "Advisory Team A" },
    "relationships": {
      "members": {
        "data": [
          {"type": "entities", "id": "34"},
          {"type": "entities", "id": "219"}
        ]
      },
      "group_type": {
        "data": {"type": "group_types", "id": "GROUPS"}
      },
      "child_groups": { "data": [] }
    },
    "links": { "self": "/v1/groups/1494728" }
  },
  "included": []
}

Response codes:

• 201 Created -- Success
• 400 Bad Request -- Invalid payload or inaccessible entity
• 403 Forbidden -- Insufficient permissions
• 404 Not Found -- Group type does not exist
• 409 Conflict -- Type not "groups" or member type not "entities"

Search groups

Finds groups by display name, group type, or external ID. At least one search criterion is required.

POST /v1/groups/query

curl -X POST "https://{firm}.addepar.com/api/v1/groups/query" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "group_search",
      "attributes": {
        "display_names": ["Smith Family"],
        "group_types": ["HH_GROUPS"],
        "external_ids": [
          { "external_id_type": "salesforce", "external_id": "sf_12345" }
        ]
      }
    }
  }'

Search fields (at least one required):

Response codes:

• 200 OK -- Success
• 400 Bad Request -- No search criterion provided
• 403 Forbidden -- Insufficient permissions

Edit groups

Updates attributes on one or more groups. Single: /v1/groups/:id. Bulk: /v1/groups with array body.

PATCH /v1/groups/:id or PATCH /v1/groups

curl -X PATCH "https://{firm}.addepar.com/api/v1/groups/1111" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": {
      "id": "1111",
      "type": "groups",
      "attributes": { "name": "Updated Group Name" }
    }
  }'

Bulk PATCH also accepts relationships.members and relationships.child_groups to replace membership in the same request.

Response codes:

• 200 OK -- Success
• 400 Bad Request -- Invalid payload or member not a valid type
• 403 Forbidden -- Insufficient permissions or cannot modify attribute
• 404 Not Found -- Group does not exist
• 409 Conflict -- ID mismatch or type error

Manage members

Three operations for member management:

All three accept the same body format:

{ "data": [{"type": "entities", "id": "100"}, {"type": "entities", "id": "101"}] }

Constraints:

• Members must be of type "entities" (409 Conflict otherwise).
• Only valid member entity types: clients, accounts, trusts, holding companies, managed funds.
• Removing a member does not delete the entity itself.

Response: 204 No Content on success.

Manage child groups

Body format: { "data": [{"type": "groups", "id": "92"}] }

Response: 204 No Content on success.

Delete groups

Permanently removes one or more groups. Members are not deleted.

DELETE /v1/groups/:id or DELETE /v1/groups (array body)

curl -X DELETE "https://{firm}.addepar.com/api/v1/groups" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": [
      {"id": "1111", "type": "groups"},
      {"id": "1112", "type": "groups"}
    ]
  }'

Response codes:

• 204 No Content -- Deleted
• 403 Forbidden -- No access to group or group type
• 404 Not Found -- Group does not exist
• 409 Conflict -- Type not "groups"

📘

Related

• Group Types -- Define group categories and their permission models
• Entities -- The entities that groups contain as members
• Addepar Attributes -- Apply custom attributes to groups
• External Identifiers -- Map groups to external systems
• Portfolio Query -- Use groups as portfolio scope (portfolio_type: "GROUP")