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

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"
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": {
      "currency_factor": "USD",    
      "original_name": "X092849032",
      "ownership_type": "PERCENT_BASED",
      "display_name": "Citco",
      "model_type": "FINANCIAL_ACCOUNT",
      "is_rolled_up": false
    },
    "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": {
        "model_type": "PERSON_NODE",
        "original_name": "Adam Smith"
        
      },
      "links": {
        "self": "/v1/entities/1000001"
      }
    },
    {
      "id": "1000002",
      "type": "entities",
      "attributes": {
        "currency_factor": "USD",
        "display_name": "Citco",
        "is_rolled_up": false,
        "model_type": "FINANCIAL_ACCOUNT",
        "original_name": "X092849032",
        "ownership_type": "PERCENT_BASED"     
      },
      "links": {
        "self": "/v1/entities/1000002"
      }
    },
    {
      "id": "1000003",
      "type": "entities",
      "attributes": {
        "currency_factor": "USD",
        "model_type": "TRUST",
        "original_name": "Adam Irrevocable Trust",
        "ownership_type": "PERCENT_BASED",  
        "_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 type of entity specified. Ignores spaces.

You cannot combine entity type and linking status filters.
* To filter multiple entities, format the request as:
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

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:

Unsupported entities:

  • Forward Contract (FORWARD_CONTRACT)
  • Futures Contract (FUTURES_CONTRACT)
  • Money Market Fund (MONEY_MARKET_FUND)

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:

Unsupported entities:

  • Forward Contract (FORWARD_CONTRACT)
  • Futures Contract (FUTURES_CONTRACT)
  • Money Market Fund (MONEY_MARKET_FUND)

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:

Unsupported entities:

  • Forward Contract (FORWARD_CONTRACT)
  • Futures Contract (FUTURES_CONTRACT)
  • Money Market Fund (MONEY_MARKET_FUND)

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.

Custom attributes can be updated for any entity. Addepar attributes, however, can only be updated for:

  • Clients (PERSON_NODE)
  • Funds (FUND)
  • Managed Funds (MANAGED_PARTNERSHIP)
  • Trusts (TRUST)
  • Holding Company (HOLDING_COMPANY)
  • Holding Account (FINANCIAL_ACCOUNT)

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.

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.

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"

Updated 9 months ago


Entities


Suggested Edits are limited on API Reference Pages

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