Entities

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
Endpoints	GET /v1/entities/:id /v1/entities POST /v1/entities/ PATCH /v1/entities/:id /v1/entities DELETE /v1/entities/:id /v1/entities
Produces	JSON
Pagination	Yes
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 Scopes	`ENTITIES`

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.

Attribute	Type	Example
`original_name`	Name of the entity. String.	`"Smith Trust"`
`model_type`	Describes the type of entity. String.	`"TRUST"`
`ownership_type`	Not 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_factor`	Required but only applicable for non-client entities. String.	`"USD"`
Optional Attributes	Additional 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

Filter	Description	Example
entity_types	Returns 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=linked	Returns all online accounts that are linked to an owner.	`filter[linking_status]=linked`
linking_status=unlinked	Returns 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"

Addepar Developer Portal

Entities

Resource Overview

Get an Entity

Get All Entities

Create an Entity

Create Multiple Entities

Update an Entity

Update Multiple Entities

Delete an Entity

Delete Multiple Entities

Entities

Suggested Edits are limited on API Reference Pages