Entities are any asset within a portfolio (like a trust), holding account, or investment. Clients themselves are also entities. Use the Entities API to create and delete entities in Addepar, and retrieve and update entity details.

Base route/v1/entities
EndpointsGET
/v1/entities/:id
/v1/entities

POST
/v1/entities/

PATCH
/v1/entities/:id
/v1/entities

DELETE
/v1/entities/:id
/v1/entities
ProducesJSON
PaginationYes
Application Permissions Required"API Access: Create, edit, and delete"

"Portfolio Access" is required to retrieve, update, and delete entities.

No specific portfolio access is required to create entities.

"Manage Attributes: Only edit certain attribute values or Manage all values and settings” is required to apply, edit, or delete attributes.
OAuth ScopesENTITIES or ENTITIES_WRITE

Resource Overview

Entities are described by the below resource object attributes. Attributes required for creating, updating or deleting entities are noted. You can assign additional standard and custom attributes to Entities.

All attributes will be returned in successful GET, POST & PATCH responses.

AttributeTypeExample
original_nameName of the entity. String."Smith Trust"
model_typeDescribes the type of entity. String."TRUST"
ownership_typeNot editable and cannot be passed in, though a value will be returned for all non-client entities. String.
Supported values:
- PERCENT_BASED
- SHARE_BASED
- VALUE_BASED
"PERCENT_BASED"
currency_factorRequired but only applicable for non-client entities. String."USD"
underlying_typeRequired but only applicable for forward and futures contract entities. String.
Supported values:
- INTEREST_RATE
- CURRENCY
- COMMODITY
- SECURITY
- INDEX
CURRENCY
delivery_priceRequired for forward contract entities. String.{ "value": 100.5 "currency": "USD" }
created_atNot editable and cannot be passed in. String."2023-07-28T02:24:30Z"
modified_atNot editable and cannot be passed in. String."2023-07-30T10:43:21Z"
Optional AttributesAdditional attributes can be applied to entities. String.See Addepar Attributes

Get an Entity

Retrieves all attributes for a specific entity.

GET /v1/entities/:id

Example:

GET https://examplefirm.addepar.com/api/v1/entities/1000002
HTTP/1.1 200

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

Response Codes:

  • 200 OK: Success
  • 403 Forbidden: Insufficient application permissions or appropriate scope not granted
  • 404 Not Found: The entity does not exist or you do not have access to it

Get All Entities

Retrieves the full list of all entities you have permission to access, as well as all attributes for each entity.

GET /v1/entities

Example:

GET https://examplefirm.addepar.com/api/v1/entities
HTTP/1.1 200

{
  "data": [
    {
      "id": "1000001",
      "type": "entities",
      "attributes": {
        "created_at": "2023-07-28T02:24:30Z",
        "model_type": "PERSON_NODE",
        "original_name": "Adam Smith",
        "modified_at": "2023-07-30T10:43:21Z"
        
      },
      "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",
        "original_name": "X092849032",
        "ownership_type": "PERCENT_BASED",  
        "modified_at": "2023-07-30T10:43:21Z"
      },
      "links": {
        "self": "/v1/entities/1000002"
      }
    },
    {
      "id": "1000003",
      "type": "entities",
      "attributes": {
        "created_at": "2023-07-28T02:24:30Z",
        "currency_factor": "USD",
        "model_type": "TRUST",
        "original_name": "Adam Irrevocable Trust",
        "ownership_type": "PERCENT_BASED",  
        "modified_at": "2023-07-30T10:43:21Z",
        "_custom_firm_id_ABC123": [
           {
              "date": null,
              "value": "ABC123",
              "weight": 1.0
           }
         ]
      },
      "links": {
        "self": "/v1/entities/1000003"
      }
    }
  ],
  "links": {
    "next": null
  }
}

Optional Parameters

FilterDescriptionExample
entity_typesReturns only the entity type(s) specified. Ignores spaces.

You can't combine entity type and linking status filters.
filter[entity_types]=VALUE1,VALUE2
linking_status=linkedReturns all online accounts that are linked to an owner.filter[linking_status]=linked
linking_status=unlinkedReturns all online accounts that are not linked to an owner.filter[linking_status]=unlinked
created_beforeReturns all entities created on or before a date, formatted as YYYY-MM-DD.filter[created_before]="2023-04-12"
created_afterReturns all entities created on or after a date, formatted as YYYY-MM-DD.filter[created_after]="2023-04-12"
fields[entities]Returns only the attributes specified for each entity. Ignores spaces.fields[entities]=model_type,ownership_type

Response Codes:

  • 200 OK: Success
  • 400 Bad Request: Invalid filter parameters
  • 403 Forbidden: Insufficient application permissions or appropriate scope not granted

Create an Entity

Adds a new entity to your firm. You can use the API to create all entities, except for the following:

Attributes original_name, model_type and currency_factor must be included.

Returns all attributes of the new entity.

POST /v1/entities/

Example:

POST https://examplefirm.addepar.com/api/v1/entities

{
  "data":{
    "type":"entities",
    "attributes":{
      "original_name":"New entity",
      "currency_factor":"USD",
      "model_type":"PERSON_NODE"
    }
  }
}
HTTP/1.1 201 Created

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

Response Codes:

  • 201 Created: Success
  • 400 Bad Request: Invalid payload or type of entities (model_type) cannot be created
  • 403 Forbidden : Insufficient application permissions or appropriate scope not granted
  • 409 Conflict: The "type" was not specified as "entities"

Create Multiple Entities

Adds new entities to your firm. You can use the API to create all entities except for the following:

Attributes original_name, model_type and currency_factor must be included.

Returns all attributes for each new entity.

POST /v1/entities/

Example:

POST https://examplefirm.addepar.com/api/v1/entities

{
  "data":[
    {
      "type":"entities",
      "attributes":{
        "model_type":"PERSON_NODE",
        "original_name":"Adam Smith",
        "currency_factor":"USD"
      }
    },
    {
      "type":"entities",
      "attributes":{
        "currency_factor":"USD",
        "model_type":"TRUST",
        "original_name":"Smith Trust"
      }
    }
  ]
}
HTTP/1.1 201 Created

{
   "data":[
      {
         "id":"1111",
         "type":"entities",
         "attributes":{
            "model_type":"PERSON_NODE",
            "original_name":"Adam Smith",
            "currency_factor":"USD"
         },
         "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"
         }
      }
   ]
}

Response Codes:

  • 201 Created: Success
  • 400 Bad Request: Invalid payload or one or more types of entities (model_type) cannot be created
  • 403 Forbidden : Insufficient application permissions or appropriate scope not granted
  • 409 Conflict : The "type" for one or more entities was not specified as "entities"

Update an Entity

Adds, modifies, or deletes the attributes or custom attributes of an existing entity for all but the following:

Returns all attributes of the updated entity.

PATCH /v1/entities/: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/entities/1111
                    
{
  "data":{
    "id":"1111",
    "type":"entities",
    "attributes":{
      "original_name":"Adam T. Smith"
    }
  }
}
HTTP/1.1 200 
                    
{
  "data": {
	"id": "1111",
       "type": "entities",
       "attributes": {
          "model_type": "PERSON_NODE",
          "original_name": "Adam T. Smith"      
    },
      "links": {
        "self": "/v1/entities/1111"
     }
  }
}

Response Codes:

  • 200 OK: Success
  • 400 Bad Request: Invalid payload or the type of entity (model_type) cannot be updated
  • 403 Forbidden : Insufficient application permissions or appropriate scope not granted
  • 404 Not Found: One or more entities do not exist or you do not have access to it
  • 409 Conflict: The ID in the path doesn't match the ID in the payload
  • 409 Conflict: The "type" was not specified as "entities"

Update Multiple Entities

Adds, modifies, or deletes attributes of existing entities. Returns all attributes of the updated entities. In the example, the two entity names are being updated from “Adam Smith” and “Smith Family Trust” as seen in the POST example above, to “Adam T. Smith” and “The Smith Family Trust” respectively.

Model types not supported:

  • Digital Asset (DIGITAL_ASSET)

PATCH /v1/entities

Example:

PATCH https://examplefirm.addepar.com/api/v1/entities

{
  "data":[
    {
      "id":"1111",
      "type":"entities",
      "attributes":{
        "original_name":"Adam T. Smith"
      }
    },
    {
      "id":"1112",
      "type":"entities",
      "attributes":{
        "original_name":"The Smith Family Trust"
      }
    }
  ]
}
HTTP/1.1 200 

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

Response Codes:

  • 200 OK: Success
  • 400 Bad Request: Invalid payload or one or more types of entities (model_type) cannot be updated
  • 403 Forbidden: Insufficient application permissions or appropriate scope not granted
  • 404 Not Found: One or more entities do not exist or you do not have access to them
  • 409 Conflict: The "type" for one or more entities was not specified as "entities"

Delete an Entity

Deletes an existing entity from your firm. An entity cannot be deleted if it holds other entities. For example, you cannot delete a holding company if it owns a security.

DELETE /v1/entities/:id

Example:

DELETE https://examplefirm.addepar.com/api/v1/entities/1111
HTTP/1.1 204 No Content

Response Codes:

  • 204 No Content: Success
  • 400 Bad Request: Invalid payload, or the entity is referenced by positions/affiliations
  • 403 Forbidden: Insufficient application permissions or appropriate scope not granted
  • 404 Not Found: The entity does not exist or you do not have access to it
  • 409 Conflict : The "type" was not specified as "entities"

Delete Multiple Entities

Deletes multiple existing entities from your firm. An entity cannot be deleted if it holds other entities. For example, you cannot delete a holding company if it owns a security.

Model types not supported:

  • Digital Asset (DIGITAL_ASSET)

DELETE /v1/entities

Example:

DELETE https://examplefirm.addepar.com/api/v1/entities

{
  "data":[
    {
      "id":1111,
      "type":"entities"
    },
    {
      "id":1112,
      "type":"entities"
    }
  ]
}
HTTP/1.1 204 No Content

Response Codes:

  • 204 No Content: Success
  • 400 Bad Request: Invalid payload, or one or more entities are referenced by positions/affiliations
  • 403 Forbidden : Insufficient application permissions or appropriate scope not granted
  • 404 Not Found: One or more entities do not exist or you do not have access to them
  • 409 Conflict : The "type" for one or more entities was not specified as "entities"