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` 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.

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"`
`underlying_type`	Required but only applicable for forward and futures contract entities. String. Supported values: - `INTEREST_RATE` - `CURRENCY` - `COMMODITY` - `SECURITY` - `INDEX`	`CURRENCY`
`delivery_price`	Required for forward contract entities. String.	`{ "value": 100.5 "currency": "USD" }`
`created_at`	Not editable and cannot be passed in. String.	`"2023-07-28T02:24:30Z"`
`modified_at`	Not editable and cannot be passed in. String.	`"2023-07-30T10:43:21Z"`
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": {
      "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

Filter	Description	Example
entity_types	Returns 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=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`
created_before	Returns all entities created on or before a date, formatted as YYYY-MM-DD.	`filter[created_before]="2023-04-12"`
created_after	Returns all entities created on or after a date, formatted as YYYY-MM-DD.	`filter[created_after]="2023-04-12"`
modified_before	Returns all entities last modified on or before a date, formatted as YYYY-MM-DD.	`filter[modified_before]="2023-04-12"`
modified_after	Returns all entities last modified on or after a date, formatted as YYYY-MM-DD.	`filter[modified_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.

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.

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.

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"