# Entities

## List all entities

**get** `/entities`

Retrieve a paginated list of entities (trusts, businesses, accounts, etc.) using cursor-based pagination

### Query Parameters

- `after: optional string`

  Cursor for forward pagination. Returns items after this cursor.

- `before: optional string`

  Cursor for backward pagination. Returns items before this cursor.

- `external_id: optional string`

  Filter by external ID (exact match within the caller's tenant)

- `household_id: optional string`

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

  Maximum number of items to return

### Returns

- `EntityList object { data, page_info, total_count }`

  - `data: array of Entity`

    - `id: string`

      Unique identifier with entity_ prefix

    - `created_at: string`

      Timestamp when the entity was created

    - `display_name: string`

      Display name of the entity

    - `household_id: string`

      Household ID this entity belongs to

    - `in_estate_status: "in_estate" or "out_of_estate" or "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: "PRE_CREATED" or "AI_CREATING" or "AI_CREATION_FAILED" or 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: string`

      Timestamp when the entity was last updated

    - `external_id: optional string`

      Customer-supplied identifier from an external system. Unique within the caller's tenant when set.

  - `page_info: PageInfo`

    - `has_next_page: boolean`

      When paginating forwards, are there more items?

    - `has_previous_page: boolean`

      When paginating backwards, are there more items?

    - `end_cursor: optional string`

      Cursor pointing to the last item in the current page

    - `start_cursor: optional string`

      Cursor pointing to the first item in the current page

  - `total_count: number`

    Total number of items matching the query (across all pages)

### Example

```http
curl https://$WITHLUMINARY_SUBDOMAIN.withluminary.com/api/public/v1/entities
```

#### 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

**delete** `/entities/{id}`

Delete an entity and all of it's related data

### Path Parameters

- `id: string`

### Example

```http
curl https://$WITHLUMINARY_SUBDOMAIN.withluminary.com/api/public/v1/entities/$ID \
    -X DELETE
```

## Get an entity by ID

**get** `/entities/{id}`

Retrieve detailed information about a specific entity

### Path Parameters

- `id: string`

### Returns

- `Entity object { id, created_at, display_name, 6 more }`

  - `id: string`

    Unique identifier with entity_ prefix

  - `created_at: string`

    Timestamp when the entity was created

  - `display_name: string`

    Display name of the entity

  - `household_id: string`

    Household ID this entity belongs to

  - `in_estate_status: "in_estate" or "out_of_estate" or "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: "PRE_CREATED" or "AI_CREATING" or "AI_CREATION_FAILED" or 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: string`

    Timestamp when the entity was last updated

  - `external_id: optional string`

    Customer-supplied identifier from an external system. Unique within the caller's tenant when set.

### Example

```http
curl https://$WITHLUMINARY_SUBDOMAIN.withluminary.com/api/public/v1/entities/$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

- `Entity object { id, created_at, display_name, 6 more }`

  - `id: string`

    Unique identifier with entity_ prefix

  - `created_at: string`

    Timestamp when the entity was created

  - `display_name: string`

    Display name of the entity

  - `household_id: string`

    Household ID this entity belongs to

  - `in_estate_status: "in_estate" or "out_of_estate" or "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: "PRE_CREATED" or "AI_CREATING" or "AI_CREATION_FAILED" or 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: string`

    Timestamp when the entity was last updated

  - `external_id: optional string`

    Customer-supplied identifier from an external system. Unique within the caller's tenant when set.

### Entity Kind

- `EntityKind = "REVOCABLE_TRUST" or "IRREVOCABLE_TRUST" or "SLAT_TRUST" or 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

- `EntityList object { data, page_info, total_count }`

  - `data: array of Entity`

    - `id: string`

      Unique identifier with entity_ prefix

    - `created_at: string`

      Timestamp when the entity was created

    - `display_name: string`

      Display name of the entity

    - `household_id: string`

      Household ID this entity belongs to

    - `in_estate_status: "in_estate" or "out_of_estate" or "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: "PRE_CREATED" or "AI_CREATING" or "AI_CREATION_FAILED" or 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: string`

      Timestamp when the entity was last updated

    - `external_id: optional string`

      Customer-supplied identifier from an external system. Unique within the caller's tenant when set.

  - `page_info: PageInfo`

    - `has_next_page: boolean`

      When paginating forwards, are there more items?

    - `has_previous_page: boolean`

      When paginating backwards, are there more items?

    - `end_cursor: optional string`

      Cursor pointing to the last item in the current page

    - `start_cursor: optional string`

      Cursor pointing to the first item in the current page

  - `total_count: number`

    Total number of items matching the query (across all pages)

# Valuation

## Get the current valuation for an entity

**get** `/entities/{id}/valuation`

Retrieve the most recent valuation with flattened asset values by type

### Path Parameters

- `id: string`

### Returns

- `Valuation object { id, created_at, directly_held_asset_value, 6 more }`

  - `id: string`

    Unique identifier with valuationv2_ prefix

  - `created_at: string`

    Timestamp when the valuation was created

  - `directly_held_asset_value: number`

    Total value of all directly held assets in USD

  - `directly_held_assets: array of object { id, asset_class, display_name, 2 more }`

    List of individual assets in this valuation

    - `id: string`

      Asset ID

    - `asset_class: object { id, display_name }`

      - `id: string`

        Asset class ID

      - `display_name: string`

        Display name of the asset class

    - `display_name: string`

      Display name of the asset

    - `value: number`

      Value of this asset in USD

    - `external_id: optional string`

      External ID from the static asset (if available)

  - `effective_date: string`

    The date this valuation is effective

  - `entity_id: string`

    Entity ID this valuation belongs to

  - `total_value: number`

    Total value of all assets minus liabilities in USD

  - `updated_at: string`

    Timestamp when the valuation was last updated

  - `description: optional string`

    Free-form notes about this valuation

### Example

```http
curl https://$WITHLUMINARY_SUBDOMAIN.withluminary.com/api/public/v1/entities/$ID/valuation
```

#### 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

**post** `/entities/{id}/valuation`

Add a new valuation to the entity's history

### Path Parameters

- `id: string`

### Body Parameters

- `directly_held_assets: array of object { asset_class_id, display_name, value, external_id }`

  List of assets to include in this valuation

  - `asset_class_id: string`

    Asset class ID to associate with this asset

  - `display_name: string`

    Display name of the asset

  - `value: number`

    Value of this asset in USD

  - `external_id: optional string`

    External ID for the asset

- `effective_date: string`

  The date this valuation is effective

- `description: optional string`

  Free-form notes about this valuation

### Returns

- `Valuation object { id, created_at, directly_held_asset_value, 6 more }`

  - `id: string`

    Unique identifier with valuationv2_ prefix

  - `created_at: string`

    Timestamp when the valuation was created

  - `directly_held_asset_value: number`

    Total value of all directly held assets in USD

  - `directly_held_assets: array of object { id, asset_class, display_name, 2 more }`

    List of individual assets in this valuation

    - `id: string`

      Asset ID

    - `asset_class: object { id, display_name }`

      - `id: string`

        Asset class ID

      - `display_name: string`

        Display name of the asset class

    - `display_name: string`

      Display name of the asset

    - `value: number`

      Value of this asset in USD

    - `external_id: optional string`

      External ID from the static asset (if available)

  - `effective_date: string`

    The date this valuation is effective

  - `entity_id: string`

    Entity ID this valuation belongs to

  - `total_value: number`

    Total value of all assets minus liabilities in USD

  - `updated_at: string`

    Timestamp when the valuation was last updated

  - `description: optional string`

    Free-form notes about this valuation

### Example

```http
curl https://$WITHLUMINARY_SUBDOMAIN.withluminary.com/api/public/v1/entities/$ID/valuation \
    -H 'Content-Type: application/json' \
    -d '{
          "directly_held_assets": [
            {
              "asset_class_id": "asset_class_01ARZ3NDEKTSV4RRFFQ69G5FAV",
              "display_name": "Apple Inc. Stock",
              "value": 50000
            }
          ],
          "effective_date": "2024-01-15"
        }'
```

#### 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

- `Valuation object { id, created_at, directly_held_asset_value, 6 more }`

  - `id: string`

    Unique identifier with valuationv2_ prefix

  - `created_at: string`

    Timestamp when the valuation was created

  - `directly_held_asset_value: number`

    Total value of all directly held assets in USD

  - `directly_held_assets: array of object { id, asset_class, display_name, 2 more }`

    List of individual assets in this valuation

    - `id: string`

      Asset ID

    - `asset_class: object { id, display_name }`

      - `id: string`

        Asset class ID

      - `display_name: string`

        Display name of the asset class

    - `display_name: string`

      Display name of the asset

    - `value: number`

      Value of this asset in USD

    - `external_id: optional string`

      External ID from the static asset (if available)

  - `effective_date: string`

    The date this valuation is effective

  - `entity_id: string`

    Entity ID this valuation belongs to

  - `total_value: number`

    Total value of all assets minus liabilities in USD

  - `updated_at: string`

    Timestamp when the valuation was last updated

  - `description: optional string`

    Free-form notes about this valuation