> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wellapp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# PersonMedia

> PersonMedia is a soft-deletable pivot (junction) entity that links a People record to a Media record, enabling a person to have one or more associated media ass

PersonMedia is a soft-deletable pivot (junction) entity that links a People record to a Media record, enabling a person to have one or more associated media assets (profile photos, avatars, documents). It carries no business attributes beyond its two foreign keys and lifecycle timestamps. The entity is workspace-scoped implicitly through its People relation; it belongs to the Supporting category alongside similar pivot tables such as CompanyMedia and PersonEmail. Every row is authored by the connector sync or enrichment pipeline; no public PATCH route exists for end-users to modify it directly.

| Naming                          | Value                             |
| ------------------------------- | --------------------------------- |
| Object                          | PersonMedia                       |
| Resource type (JSON:API `type`) | `person_media`                    |
| Collection / records root       | — <sub>(not a records root)</sub> |
| REST base                       | `/v1/person-media`                |
| Entity class                    | `PersonMedia`                     |

<Note>
  **Internal object.** Not currently exposed on the public REST API. The operations below describe the intended contract.
</Note>

## API operations

| Operation | Method & path                  | Status     |
| --------- | ------------------------------ | ---------- |
| List      | `GET /v1/person-media`         | 🟡 Planned |
| Retrieve  | `GET /v1/person-media/{id}`    | 🟡 Planned |
| Create    | `POST /v1/person-media`        | 🟡 Planned |
| Update    | `PATCH /v1/person-media/{id}`  | 🟡 Planned |
| Delete    | `DELETE /v1/person-media/{id}` | 🟡 Planned |

## Data model

### Attributes

| Field       | Type               | Required | Constraints                                 | Allowed values                | Description                                                                                                                                    |
| ----------- | ------------------ | -------- | ------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| created\_at | datetime 🔒 system | ✅ Yes    | NOT NULL; set by onCreate: () => new Date() | ISO 8601 UTC datetime         | Timestamp set once at row creation via MikroORM onCreate hook. Never updated afterwards.                                                       |
| deleted\_at | datetime \| null   | ⚪ No     | nullable                                    | ISO 8601 UTC datetime or null | Soft-delete timestamp. NULL means the pivot link is active. Set by the soft-delete lifecycle when the link is removed; never cleared once set. |

### Relationships

| Name   | Type               | Required | Description                                                                                                                                                                                                    |
| ------ | ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| person | to-one (ManyToOne) | ✅ Yes    | The People record this media asset is attached to. FK person\_pk → core\_api.peoples.pk. Indexed via idx\_person\_media\_person for reverse traversal from People to its media.                                |
| media  | to-one (ManyToOne) | ✅ Yes    | The Media record (file/image asset) associated with the person. FK media\_pk → core\_api.media.pk. Indexed via idx\_person\_media\_media to support Hasura media → person\_media array relationship traversal. |

### System-computed

* pk — auto-increment serial integer, internal join key only; never exposed via the public API.
* created\_at — set by MikroORM onCreate hook (onCreate: () => new Date()) at row insertion; not updated on subsequent writes.
* deleted\_at — managed by the soft-delete lifecycle; NULL on creation, set to current timestamp when the pivot link is logically removed. Queries must always filter deleted\_at IS NULL to respect soft-delete semantics.
* Note on migration parity gap: the Migration20250919154301.ts DDL created the table with an updated\_at timestamptz NULL column, but the entity class declares no @Property for updated\_at. The column exists in the database but is unmapped in ORM layer — it will remain NULL for all rows unless manually backfilled or the entity is amended.

## Example

```json theme={null}
{
  "data": {
    "type": "person_media",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "attributes": {
      "created_at": "2025-11-14T09:22:34.000Z",
      "deleted_at": null
    },
    "relationships": {
      "person": {
        "data": { "type": "people", "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }
      },
      "media": {
        "data": { "type": "media", "id": "c3d4e5f6-a1b2-4890-bcde-f01234567890" }
      }
    }
  }
}
```

<sub>Source: `apps/api/src/database/entities/PersonMedia.ts` · domain: financial-graph · tier: Supporting</sub>