Entities

Entities are the fundamental nodes in Addepar's portfolio graph. Every client, account, trust, fund, and security is an entity. Positions connect entities to each other (an account holds a stock), transactions record value flowing between them, and portfolio queries aggregate across them. Before you can record a position, run a query, or generate a report, the entities must exist.

How entities work

An entity represents a single financial object. The system distinguishes entities by two properties set at creation time:

Model type determines what kind of thing the entity is: a person (person_node), a trust (trust), a stock (stock), a bond (bond), a holding account (financial_account), etc. The full taxonomy has 40+ model types organized into categories (Client, Security, Vehicle, Account). Use GET /v1/entity_types to retrieve the complete list with each type's required fields and mutability rules. See Model Types for the full reference.

Ownership type determines how positions in this entity are measured:

The ownership type is assigned based on the model type and cannot be changed after creation. This is the most consequential decision in entity creation: it determines how the system calculates performance, allocations, and portfolio values for every position involving that entity. If you create a managed fund as PERCENT_BASED when it should be SHARE_BASED, the only fix is to delete it and recreate it with the correct model type.

Some model types support multiple ownership types (e.g., hedge_fund can be share-based or value-based, real_estate can be share-based or value-based). For these, the ownership type is specified at creation and becomes immutable.

Overview

📘

Access requirements

API Access: Create, edit, and delete.
Portfolio Access: Required to retrieve, update, and delete entities. Not required to create.
Manage Attributes: Required to apply, edit, or delete attributes on entities.

Resource attributes

Every entity carries these core attributes. Additional standard and custom Addepar Attributes can be applied via PATCH.

Field mutability: The Model Types API returns a writability value for each attribute per entity type. MUTABLE fields can be edited freely. IMMUTABLE fields cannot be changed after creation (most security identifiers like cusip, isin, sedol are immutable on market securities). FINAL fields can be set at creation but not modified afterward.

Get an entity

Retrieves all attributes for a specific entity.

GET /v1/entities/:id

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

{
  "data": {
    "id": "1000002",
    "type": "entities",
    "attributes": {
      "created_at": "2023-07-28T02:24:30Z",
      "currency_factor": "USD",
      "display_name": "Citco",
      "is_rolled_up": false,
      "model_type": "FINANCIAL_ACCOUNT",
      "modified_at": "2023-07-30T10:43:21Z",
      "original_name": "X092849032",
      "ownership_type": "PERCENT_BASED"
    },
    "links": {
      "self": "/v1/entities/1000002"
    }
  }
}

{
  "errors": [
    {
      "id": "not_found",
      "status": "404",
      "title": "Not Found",
      "detail": "The entity does not exist or you do not have access to it."
    }
  ]
}

A 404 response can mean the entity does not exist or that the authenticated user lacks Portfolio Access to it. Addepar returns 404 (not 403) when the user cannot see the resource, to avoid leaking information about what exists.

Get all entities

Retrieves all entities you have permission to access. Results are paginated.

GET /v1/entities

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

{
  "data": [
    {
      "id": "1000001",
      "type": "entities",
      "attributes": {
        "created_at": "2023-07-28T02:24:30Z",
        "model_type": "PERSON_NODE",
        "modified_at": "2023-07-30T10:43:21Z",
        "original_name": "Adam Smith"
      },
      "links": {
        "self": "/v1/entities/1000001"
      }
    },
    {
      "id": "1000002",
      "type": "entities",
      "attributes": {
        "created_at": "2023-07-28T02:24:30Z",
        "currency_factor": "USD",
        "display_name": "Citco",
        "is_rolled_up": false,
        "model_type": "FINANCIAL_ACCOUNT",
        "modified_at": "2023-07-30T10:43:21Z",
        "original_name": "X092849032",
        "ownership_type": "PERCENT_BASED"
      },
      "links": {
        "self": "/v1/entities/1000002"
      }
    }
  ],
  "links": {
    "next": "/v1/entities?page[limit]=25&page[cursor]=abc123"
  }
}

📘

Performance

Use fields[entities] to request only the attributes you need:
GET /v1/entities?fields[entities]=model_type,original_name,created_at
This significantly reduces response size for firms with many custom attributes applied to entities.

Filter parameters:

Create entities

Creates one or more entities. You must include original_name, model_type, and currency_factor (for non-client types) in the request body. The system assigns ownership_type based on model_type.

POST /v1/entities

Single entity:

curl -X POST "https://{firm}.addepar.com/api/v1/entities" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "entities",
      "attributes": {
        "currency_factor": "USD",
        "model_type": "PERSON_NODE",
        "original_name": "Adam Smith"
      }
    }
  }'

{
  "data": {
    "id": "1111",
    "type": "entities",
    "attributes": {
      "currency_factor": "USD",
      "model_type": "PERSON_NODE",
      "original_name": "Adam Smith"
    },
    "links": {
      "self": "/v1/entities/1111"
    }
  }
}

Multiple entities:

Pass an array in data to create several entities in one request:

curl -X POST "https://{firm}.addepar.com/api/v1/entities" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": [
      {
        "type": "entities",
        "attributes": {
          "currency_factor": "USD",
          "model_type": "PERSON_NODE",
          "original_name": "Adam Smith"
        }
      },
      {
        "type": "entities",
        "attributes": {
          "currency_factor": "USD",
          "model_type": "TRUST",
          "original_name": "Smith Trust"
        }
      }
    ]
  }'

{
  "data": [
    {
      "id": "1111",
      "type": "entities",
      "attributes": {
        "currency_factor": "USD",
        "model_type": "PERSON_NODE",
        "original_name": "Adam Smith"
      },
      "links": {
        "self": "/v1/entities/1111"
      }
    },
    {
      "id": "1112",
      "type": "entities",
      "attributes": {
        "currency_factor": "USD",
        "model_type": "TRUST",
        "original_name": "Smith Trust",
        "ownership_type": "PERCENT_BASED"
      },
      "links": {
        "self": "/v1/entities/1112"
      }
    }
  ]
}

Query parameter:

Response codes:

• 201 Created -- Entity created successfully
• 400 Bad Request -- Invalid payload or model_type cannot be created
• 403 Forbidden -- Insufficient permissions or scope not granted
• 409 Conflict -- The type field in the body must be "entities"

Edit entities

Updates attributes on one or more existing entities. Only include the attributes you want to change. The response returns all attributes of the updated entity.

PATCH /v1/entities/:id (single) or PATCH /v1/entities (bulk)

See Addepar Attributes for applying custom attributes and time-varying values.

Single entity:

curl -X PATCH "https://{firm}.addepar.com/api/v1/entities/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": "entities",
      "attributes": {
        "original_name": "Adam T. Smith"
      }
    }
  }'

{
  "data": {
    "id": "1111",
    "type": "entities",
    "attributes": {
      "model_type": "PERSON_NODE",
      "original_name": "Adam T. Smith"
    },
    "links": {
      "self": "/v1/entities/1111"
    }
  }
}

Multiple entities:

curl -X PATCH "https://{firm}.addepar.com/api/v1/entities" \
  -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": "entities",
        "attributes": {
          "original_name": "Adam T. Smith"
        }
      },
      {
        "id": "1112",
        "type": "entities",
        "attributes": {
          "original_name": "The Smith Family Trust"
        }
      }
    ]
  }'

Bulk edit is not available for DIGITAL_ASSET entities.

Response codes:

• 200 OK -- Entity updated successfully
• 400 Bad Request -- Invalid payload or attempting to write an immutable field
• 403 Forbidden -- Insufficient permissions or scope not granted
• 404 Not Found -- Entity does not exist or not accessible
• 409 Conflict -- ID in path does not match ID in payload, or type is not "entities"

Delete entities

Permanently removes one or more entities. This operation is irreversible. An entity cannot be deleted if it has positions, affiliations, or child entities referencing it. Remove those relationships first.

DELETE /v1/entities/:id (single) or DELETE /v1/entities (bulk)

Single entity:

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

204 No Content

Multiple entities:

curl -X DELETE "https://{firm}.addepar.com/api/v1/entities" \
  -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": "entities" },
      { "id": "1112", "type": "entities" }
    ]
  }'

Bulk delete is not available for DIGITAL_ASSET entities.

Response codes:

• 204 No Content -- Entity deleted successfully
• 400 Bad Request -- Entity is referenced by positions or affiliations and cannot be deleted
• 403 Forbidden -- Insufficient permissions or scope not granted
• 404 Not Found -- Entity does not exist or not accessible

Search entities

Find entities by attribute values without listing all entities and filtering client-side.

POST /v1/entities/search

curl -X POST "https://{firm}.addepar.com/api/v1/entities/search" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "entity_searches",
      "attributes": {
        "name": "Smith"
      }
    }
  }'

The search endpoint returns entities matching the specified criteria. Use this for targeted lookups (e.g., finding an entity by name before creating a position) rather than paginating through the full entity list.

Validate entities

Check whether an entity payload is valid before creating it.

POST /v1/entities/validate

curl -X POST "https://{firm}.addepar.com/api/v1/entities/validate" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "entities",
      "attributes": {
        "currency_factor": "USD",
        "model_type": "TRUST",
        "original_name": "Test Trust"
      }
    }
  }'

Returns 200 OK if the payload would succeed, or 400 Bad Request with validation errors. Use this in onboarding workflows where you want to check data quality before committing entities to the system.

Changing an entity's model type

The model type itself can be changed after creation via the Model Types API (PATCH /v1/entity_types). This allows reclassifying entities (e.g., converting a generic_asset to a hedge_fund) when the ownership type is compatible. The new model type must share the same ownership type as the original, or the entity must have no existing positions that would conflict with the ownership change.

Common integration patterns

CRM sync (clients and accounts): Create person_node entities for clients and financial_account entities for their accounts. Use External Identifiers to store the CRM record ID on each entity for bidirectional reconciliation.

Custodian feed (securities): Before creating a security entity, check if it already exists using GET /v1/entities?filter[model_types]=STOCK&fields[entities]=cusip,original_name or the search endpoint. Duplicate securities cause position reconciliation failures.

Bulk onboarding: Use bulk POST to create many entities in a single request. Pair with the validate endpoint to pre-check each entity's payload. For firms onboarding hundreds of entities, this avoids discovering validation errors partway through individual creates.

📘

Related

• Model Types -- Full taxonomy of entity types with required fields and mutability rules
• Positions -- The ownership relationships between entities
• Groups -- Organize entities into hierarchies for reporting and access control
• Addepar Attributes -- Apply standard and custom metadata to entities
• External Identifiers -- Cross-system IDs for entity reconciliation
• Portfolio Query -- Aggregate and analyze data across entities