# Entities ## List all entities `entities.list(EntityListParams**kwargs) -> SyncCursorPagination[Entity]` **get** `/entities` Retrieve a paginated list of entities (trusts, businesses, accounts, etc.) using cursor-based pagination ### Parameters - `after: Optional[str]` Cursor for forward pagination. Returns items after this cursor. - `before: Optional[str]` Cursor for backward pagination. Returns items before this cursor. - `external_id: Optional[str]` Filter by external ID (exact match within the caller's tenant) - `household_id: Optional[str]` Filter entities by household ID - `kind: Optional[EntityKind]` Filter by entity kind/type - `"REVOCABLE_TRUST"` - `"IRREVOCABLE_TRUST"` - `"SLAT_TRUST"` - `"ILIT_TRUST"` - `"QPRT_TRUST"` - `"GRAT_TRUST"` - `"CRT_TRUST"` - `"CLT_TRUST"` - `"INDIVIDUAL_PERSONAL_ACCOUNT"` - `"JOINT_PERSONAL_ACCOUNT"` - `"CUSTODIAL_PERSONAL_ACCOUNT"` - `"INSURANCE_PERSONAL_ACCOUNT"` - `"QUALIFIED_TUITION_PERSONAL_ACCOUNT"` - `"RETIREMENT_PERSONAL_ACCOUNT"` - `"DONOR_ADVISED_FUND"` - `"PRIVATE_FOUNDATION"` - `"LLC_BUSINESS_ENTITY"` - `"LP_BUSINESS_ENTITY"` - `"GP_BUSINESS_ENTITY"` - `"SOLE_PROPRIETORSHIP_BUSINESS_ENTITY"` - `"SCORP_BUSINESS_ENTITY"` - `"CCORP_BUSINESS_ENTITY"` - `limit: Optional[int]` Maximum number of items to return ### Returns - `class Entity: …` - `id: str` Unique identifier with entity_ prefix - `created_at: datetime` Timestamp when the entity was created - `display_name: str` Display name of the entity - `household_id: str` Household ID this entity belongs to - `in_estate_status: Literal["in_estate", "out_of_estate", "none"]` Whether the entity is in or out of the estate - `"in_estate"` - `"out_of_estate"` - `"none"` - `kind: EntityKind` Type of entity - determines the specific subtype and applicable fields - `"REVOCABLE_TRUST"` - `"IRREVOCABLE_TRUST"` - `"SLAT_TRUST"` - `"ILIT_TRUST"` - `"QPRT_TRUST"` - `"GRAT_TRUST"` - `"CRT_TRUST"` - `"CLT_TRUST"` - `"INDIVIDUAL_PERSONAL_ACCOUNT"` - `"JOINT_PERSONAL_ACCOUNT"` - `"CUSTODIAL_PERSONAL_ACCOUNT"` - `"INSURANCE_PERSONAL_ACCOUNT"` - `"QUALIFIED_TUITION_PERSONAL_ACCOUNT"` - `"RETIREMENT_PERSONAL_ACCOUNT"` - `"DONOR_ADVISED_FUND"` - `"PRIVATE_FOUNDATION"` - `"LLC_BUSINESS_ENTITY"` - `"LP_BUSINESS_ENTITY"` - `"GP_BUSINESS_ENTITY"` - `"SOLE_PROPRIETORSHIP_BUSINESS_ENTITY"` - `"SCORP_BUSINESS_ENTITY"` - `"CCORP_BUSINESS_ENTITY"` - `stage: Literal["PRE_CREATED", "AI_CREATING", "AI_CREATION_FAILED", 7 more]` Lifecycle stage of the entity - `"PRE_CREATED"` - `"AI_CREATING"` - `"AI_CREATION_FAILED"` - `"AI_NEEDS_REVIEW"` - `"DRAFT"` - `"READY_FOR_PROPOSAL"` - `"IMPLEMENTATION"` - `"ACTIVE"` - `"COMPLETED"` - `"ARCHIVED"` - `updated_at: datetime` Timestamp when the entity was last updated - `external_id: Optional[str]` Customer-supplied identifier from an external system. Unique within the caller's tenant when set. ### Example ```python from withluminary import Luminary client = Luminary() page = client.entities.list() page = page.data[0] print(page.id) ``` #### Response ```json { "data": [ { "id": "entity_01ARZ3NDEKTSV4RRFFQ69G5FAV", "created_at": "2024-01-15T09:30:00Z", "display_name": "My Revocable Trust", "household_id": "household_01ARZ3NDEKTSV4RRFFQ69G5FAV", "in_estate_status": "in_estate", "kind": "REVOCABLE_TRUST", "stage": "PRE_CREATED", "updated_at": "2024-01-20T14:45:00Z", "external_id": "crm-entity-12345" } ], "page_info": { "has_next_page": true, "has_previous_page": false, "end_cursor": "eyJpZCI6ImhvdXNlaG9sZF8wMUFSWjNOREVLVFNWNFJSRkZRNjlHNUZBViJ9", "start_cursor": "eyJpZCI6ImhvdXNlaG9sZF8wMUFSWjNOREVLVFNWNFJSRkZRNjlHNUZBViJ9" }, "total_count": 100 } ``` ## Delete an entity `entities.delete(strid)` **delete** `/entities/{id}` Delete an entity and all of it's related data ### Parameters - `id: str` ### Example ```python from withluminary import Luminary client = Luminary() client.entities.delete( "id", ) ``` ## Get an entity by ID `entities.retrieve(strid) -> Entity` **get** `/entities/{id}` Retrieve detailed information about a specific entity ### Parameters - `id: str` ### Returns - `class Entity: …` - `id: str` Unique identifier with entity_ prefix - `created_at: datetime` Timestamp when the entity was created - `display_name: str` Display name of the entity - `household_id: str` Household ID this entity belongs to - `in_estate_status: Literal["in_estate", "out_of_estate", "none"]` Whether the entity is in or out of the estate - `"in_estate"` - `"out_of_estate"` - `"none"` - `kind: EntityKind` Type of entity - determines the specific subtype and applicable fields - `"REVOCABLE_TRUST"` - `"IRREVOCABLE_TRUST"` - `"SLAT_TRUST"` - `"ILIT_TRUST"` - `"QPRT_TRUST"` - `"GRAT_TRUST"` - `"CRT_TRUST"` - `"CLT_TRUST"` - `"INDIVIDUAL_PERSONAL_ACCOUNT"` - `"JOINT_PERSONAL_ACCOUNT"` - `"CUSTODIAL_PERSONAL_ACCOUNT"` - `"INSURANCE_PERSONAL_ACCOUNT"` - `"QUALIFIED_TUITION_PERSONAL_ACCOUNT"` - `"RETIREMENT_PERSONAL_ACCOUNT"` - `"DONOR_ADVISED_FUND"` - `"PRIVATE_FOUNDATION"` - `"LLC_BUSINESS_ENTITY"` - `"LP_BUSINESS_ENTITY"` - `"GP_BUSINESS_ENTITY"` - `"SOLE_PROPRIETORSHIP_BUSINESS_ENTITY"` - `"SCORP_BUSINESS_ENTITY"` - `"CCORP_BUSINESS_ENTITY"` - `stage: Literal["PRE_CREATED", "AI_CREATING", "AI_CREATION_FAILED", 7 more]` Lifecycle stage of the entity - `"PRE_CREATED"` - `"AI_CREATING"` - `"AI_CREATION_FAILED"` - `"AI_NEEDS_REVIEW"` - `"DRAFT"` - `"READY_FOR_PROPOSAL"` - `"IMPLEMENTATION"` - `"ACTIVE"` - `"COMPLETED"` - `"ARCHIVED"` - `updated_at: datetime` Timestamp when the entity was last updated - `external_id: Optional[str]` Customer-supplied identifier from an external system. Unique within the caller's tenant when set. ### Example ```python from withluminary import Luminary client = Luminary() entity = client.entities.retrieve( "id", ) print(entity.id) ``` #### Response ```json { "id": "entity_01ARZ3NDEKTSV4RRFFQ69G5FAV", "created_at": "2024-01-15T09:30:00Z", "display_name": "My Revocable Trust", "household_id": "household_01ARZ3NDEKTSV4RRFFQ69G5FAV", "in_estate_status": "in_estate", "kind": "REVOCABLE_TRUST", "stage": "PRE_CREATED", "updated_at": "2024-01-20T14:45:00Z", "external_id": "crm-entity-12345" } ``` ## Domain Types ### Entity - `class Entity: …` - `id: str` Unique identifier with entity_ prefix - `created_at: datetime` Timestamp when the entity was created - `display_name: str` Display name of the entity - `household_id: str` Household ID this entity belongs to - `in_estate_status: Literal["in_estate", "out_of_estate", "none"]` Whether the entity is in or out of the estate - `"in_estate"` - `"out_of_estate"` - `"none"` - `kind: EntityKind` Type of entity - determines the specific subtype and applicable fields - `"REVOCABLE_TRUST"` - `"IRREVOCABLE_TRUST"` - `"SLAT_TRUST"` - `"ILIT_TRUST"` - `"QPRT_TRUST"` - `"GRAT_TRUST"` - `"CRT_TRUST"` - `"CLT_TRUST"` - `"INDIVIDUAL_PERSONAL_ACCOUNT"` - `"JOINT_PERSONAL_ACCOUNT"` - `"CUSTODIAL_PERSONAL_ACCOUNT"` - `"INSURANCE_PERSONAL_ACCOUNT"` - `"QUALIFIED_TUITION_PERSONAL_ACCOUNT"` - `"RETIREMENT_PERSONAL_ACCOUNT"` - `"DONOR_ADVISED_FUND"` - `"PRIVATE_FOUNDATION"` - `"LLC_BUSINESS_ENTITY"` - `"LP_BUSINESS_ENTITY"` - `"GP_BUSINESS_ENTITY"` - `"SOLE_PROPRIETORSHIP_BUSINESS_ENTITY"` - `"SCORP_BUSINESS_ENTITY"` - `"CCORP_BUSINESS_ENTITY"` - `stage: Literal["PRE_CREATED", "AI_CREATING", "AI_CREATION_FAILED", 7 more]` Lifecycle stage of the entity - `"PRE_CREATED"` - `"AI_CREATING"` - `"AI_CREATION_FAILED"` - `"AI_NEEDS_REVIEW"` - `"DRAFT"` - `"READY_FOR_PROPOSAL"` - `"IMPLEMENTATION"` - `"ACTIVE"` - `"COMPLETED"` - `"ARCHIVED"` - `updated_at: datetime` Timestamp when the entity was last updated - `external_id: Optional[str]` Customer-supplied identifier from an external system. Unique within the caller's tenant when set. ### Entity Kind - `Literal["REVOCABLE_TRUST", "IRREVOCABLE_TRUST", "SLAT_TRUST", 19 more]` Type of entity - determines the specific subtype and applicable fields - `"REVOCABLE_TRUST"` - `"IRREVOCABLE_TRUST"` - `"SLAT_TRUST"` - `"ILIT_TRUST"` - `"QPRT_TRUST"` - `"GRAT_TRUST"` - `"CRT_TRUST"` - `"CLT_TRUST"` - `"INDIVIDUAL_PERSONAL_ACCOUNT"` - `"JOINT_PERSONAL_ACCOUNT"` - `"CUSTODIAL_PERSONAL_ACCOUNT"` - `"INSURANCE_PERSONAL_ACCOUNT"` - `"QUALIFIED_TUITION_PERSONAL_ACCOUNT"` - `"RETIREMENT_PERSONAL_ACCOUNT"` - `"DONOR_ADVISED_FUND"` - `"PRIVATE_FOUNDATION"` - `"LLC_BUSINESS_ENTITY"` - `"LP_BUSINESS_ENTITY"` - `"GP_BUSINESS_ENTITY"` - `"SOLE_PROPRIETORSHIP_BUSINESS_ENTITY"` - `"SCORP_BUSINESS_ENTITY"` - `"CCORP_BUSINESS_ENTITY"` ### Entity List - `class EntityList: …` - `data: List[Entity]` - `id: str` Unique identifier with entity_ prefix - `created_at: datetime` Timestamp when the entity was created - `display_name: str` Display name of the entity - `household_id: str` Household ID this entity belongs to - `in_estate_status: Literal["in_estate", "out_of_estate", "none"]` Whether the entity is in or out of the estate - `"in_estate"` - `"out_of_estate"` - `"none"` - `kind: EntityKind` Type of entity - determines the specific subtype and applicable fields - `"REVOCABLE_TRUST"` - `"IRREVOCABLE_TRUST"` - `"SLAT_TRUST"` - `"ILIT_TRUST"` - `"QPRT_TRUST"` - `"GRAT_TRUST"` - `"CRT_TRUST"` - `"CLT_TRUST"` - `"INDIVIDUAL_PERSONAL_ACCOUNT"` - `"JOINT_PERSONAL_ACCOUNT"` - `"CUSTODIAL_PERSONAL_ACCOUNT"` - `"INSURANCE_PERSONAL_ACCOUNT"` - `"QUALIFIED_TUITION_PERSONAL_ACCOUNT"` - `"RETIREMENT_PERSONAL_ACCOUNT"` - `"DONOR_ADVISED_FUND"` - `"PRIVATE_FOUNDATION"` - `"LLC_BUSINESS_ENTITY"` - `"LP_BUSINESS_ENTITY"` - `"GP_BUSINESS_ENTITY"` - `"SOLE_PROPRIETORSHIP_BUSINESS_ENTITY"` - `"SCORP_BUSINESS_ENTITY"` - `"CCORP_BUSINESS_ENTITY"` - `stage: Literal["PRE_CREATED", "AI_CREATING", "AI_CREATION_FAILED", 7 more]` Lifecycle stage of the entity - `"PRE_CREATED"` - `"AI_CREATING"` - `"AI_CREATION_FAILED"` - `"AI_NEEDS_REVIEW"` - `"DRAFT"` - `"READY_FOR_PROPOSAL"` - `"IMPLEMENTATION"` - `"ACTIVE"` - `"COMPLETED"` - `"ARCHIVED"` - `updated_at: datetime` Timestamp when the entity was last updated - `external_id: Optional[str]` Customer-supplied identifier from an external system. Unique within the caller's tenant when set. - `page_info: PageInfo` - `has_next_page: bool` When paginating forwards, are there more items? - `has_previous_page: bool` When paginating backwards, are there more items? - `end_cursor: Optional[str]` Cursor pointing to the last item in the current page - `start_cursor: Optional[str]` Cursor pointing to the first item in the current page - `total_count: int` Total number of items matching the query (across all pages) # Valuation ## Get the current valuation for an entity `entities.valuation.retrieve(strid) -> Valuation` **get** `/entities/{id}/valuation` Retrieve the most recent valuation with flattened asset values by type ### Parameters - `id: str` ### Returns - `class Valuation: …` - `id: str` Unique identifier with valuationv2_ prefix - `created_at: datetime` Timestamp when the valuation was created - `directly_held_asset_value: float` Total value of all directly held assets in USD - `directly_held_assets: List[DirectlyHeldAsset]` List of individual assets in this valuation - `id: str` Asset ID - `asset_class: DirectlyHeldAssetAssetClass` - `id: str` Asset class ID - `display_name: str` Display name of the asset class - `display_name: str` Display name of the asset - `value: float` Value of this asset in USD - `external_id: Optional[str]` External ID from the static asset (if available) - `effective_date: date` The date this valuation is effective - `entity_id: str` Entity ID this valuation belongs to - `total_value: float` Total value of all assets minus liabilities in USD - `updated_at: datetime` Timestamp when the valuation was last updated - `description: Optional[str]` Free-form notes about this valuation ### Example ```python from withluminary import Luminary client = Luminary() valuation = client.entities.valuation.retrieve( "id", ) print(valuation.id) ``` #### Response ```json { "id": "valuationv2_01ARZ3NDEKTSV4RRFFQ69G5FAV", "created_at": "2024-01-15T09:30:00Z", "directly_held_asset_value": 1000000, "directly_held_assets": [ { "id": "assetv2_01ARZ3NDEKTSV4RRFFQ69G5FAV", "asset_class": { "id": "asset_class_01ARZ3NDEKTSV4RRFFQ69G5FAV", "display_name": "Equities" }, "display_name": "Apple Inc. Stock", "value": 50000, "external_id": "AAPL-12345" } ], "effective_date": "2024-01-15", "entity_id": "entity_01ARZ3NDEKTSV4RRFFQ69G5FAV", "total_value": 1000000, "updated_at": "2024-01-20T14:45:00Z", "description": "description" } ``` ## Create a new valuation for an entity `entities.valuation.create(strid, ValuationCreateParams**kwargs) -> Valuation` **post** `/entities/{id}/valuation` Add a new valuation to the entity's history ### Parameters - `id: str` - `directly_held_assets: Iterable[DirectlyHeldAsset]` List of assets to include in this valuation - `asset_class_id: str` Asset class ID to associate with this asset - `display_name: str` Display name of the asset - `value: float` Value of this asset in USD - `external_id: Optional[str]` External ID for the asset - `effective_date: Union[null, null]` The date this valuation is effective - `description: Optional[str]` Free-form notes about this valuation ### Returns - `class Valuation: …` - `id: str` Unique identifier with valuationv2_ prefix - `created_at: datetime` Timestamp when the valuation was created - `directly_held_asset_value: float` Total value of all directly held assets in USD - `directly_held_assets: List[DirectlyHeldAsset]` List of individual assets in this valuation - `id: str` Asset ID - `asset_class: DirectlyHeldAssetAssetClass` - `id: str` Asset class ID - `display_name: str` Display name of the asset class - `display_name: str` Display name of the asset - `value: float` Value of this asset in USD - `external_id: Optional[str]` External ID from the static asset (if available) - `effective_date: date` The date this valuation is effective - `entity_id: str` Entity ID this valuation belongs to - `total_value: float` Total value of all assets minus liabilities in USD - `updated_at: datetime` Timestamp when the valuation was last updated - `description: Optional[str]` Free-form notes about this valuation ### Example ```python from datetime import date from withluminary import Luminary client = Luminary() valuation = client.entities.valuation.create( id="id", directly_held_assets=[{ "asset_class_id": "asset_class_01ARZ3NDEKTSV4RRFFQ69G5FAV", "display_name": "Apple Inc. Stock", "value": 50000, }], effective_date=date.fromisoformat("2024-01-15"), ) print(valuation.id) ``` #### Response ```json { "id": "valuationv2_01ARZ3NDEKTSV4RRFFQ69G5FAV", "created_at": "2024-01-15T09:30:00Z", "directly_held_asset_value": 1000000, "directly_held_assets": [ { "id": "assetv2_01ARZ3NDEKTSV4RRFFQ69G5FAV", "asset_class": { "id": "asset_class_01ARZ3NDEKTSV4RRFFQ69G5FAV", "display_name": "Equities" }, "display_name": "Apple Inc. Stock", "value": 50000, "external_id": "AAPL-12345" } ], "effective_date": "2024-01-15", "entity_id": "entity_01ARZ3NDEKTSV4RRFFQ69G5FAV", "total_value": 1000000, "updated_at": "2024-01-20T14:45:00Z", "description": "description" } ``` ## Domain Types ### Valuation - `class Valuation: …` - `id: str` Unique identifier with valuationv2_ prefix - `created_at: datetime` Timestamp when the valuation was created - `directly_held_asset_value: float` Total value of all directly held assets in USD - `directly_held_assets: List[DirectlyHeldAsset]` List of individual assets in this valuation - `id: str` Asset ID - `asset_class: DirectlyHeldAssetAssetClass` - `id: str` Asset class ID - `display_name: str` Display name of the asset class - `display_name: str` Display name of the asset - `value: float` Value of this asset in USD - `external_id: Optional[str]` External ID from the static asset (if available) - `effective_date: date` The date this valuation is effective - `entity_id: str` Entity ID this valuation belongs to - `total_value: float` Total value of all assets minus liabilities in USD - `updated_at: datetime` Timestamp when the valuation was last updated - `description: Optional[str]` Free-form notes about this valuation