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/:entity-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

S

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

e

Name of the entity. String.

"

model_type

Describes the type of entity. String.

"

ownership_type

Not editable and cannot be passed in, though a value will be returned for all non-client entities. String.
Supported values:

  • D
    
  • SHARE_BASED
  • D
    

"PERCENT_BASED"

r

Required but only applicable for non-client entities. String.

"

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 parameter(s):

  • filter[entity_types]: Returns only the type of entity specified. Ignores spaces.
  • To filter multiple entities, format the request as: filter[entity_types]=VALUE1&filter[entity_types]=VALUE2

Response Codes:

  • 200 OK: Success
  • 403 Forbidden: Insufficient application permissions or appropriate scope not granted

Create an Entity

Adds a new entity to your firm. Currently, the following entities can be created with this API:

  • Client (PERSON_NODE)
  • Trust (TRUST)
  • Holding Company (HOLDING_COMPANY)
  • Holding Account (FINANCIAL_ACCOUNT)
  • Fund (FUND)
  • Managed Partnership (MANAGED_PARTNERSHIP)

Attributes for 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. Currently, the following entities can be created with this API:

  • Client (PERSON_NODE)
  • Trust (TRUST)
  • Holding Company (HOLDING_COMPANY)
  • Holding Account (FINANCIAL_ACCOUNT)
  • Fund (FUND)
  • Managed Partnership (MANAGED_PARTNERSHIP)

Attributes for 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 of an existing entity.

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 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 13 days 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.