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.
PersonPhone is a pivot entity that links a People record to a Phone record within a workspace, carrying metadata about the association. It implements the canonical pivot pattern with is_primary, is_verify, and label fields so a single person can hold multiple phone numbers under different categories. Records are written by the connector sync pipeline and by user-facing People mutations (add/remove phone); there is no standalone PATCH surface for individual person_phones rows. Soft-delete semantics via deleted_at are enforced, and partial unique indexes guarantee at most one primary phone per person at any time.
| Naming | Value |
|---|
| Object | PersonPhone |
Resource type (JSON:API type) | person_phone |
| Collection / records root | — (not a records root) |
| REST base | /v1/person-phones |
| Entity class | PersonPhone |
Internal object. Not currently exposed on the public REST API. The operations below describe the intended contract.
API operations
| Operation | Method & path | Status |
|---|
| List | GET /v1/person-phones | 🟡 Planned |
| Retrieve | GET /v1/person-phones/{id} | 🟡 Planned |
| Create | POST /v1/person-phones | 🟡 Planned |
| Update | PATCH /v1/person-phones/{id} | 🟡 Planned |
| Delete | DELETE /v1/person-phones/{id} | 🟡 Planned |
Data model
Attributes
| Field | Type | Required | Constraints | Allowed values | Description |
|---|
| is_primary | boolean | ⚪ No | DEFAULT false; partial unique index uniq_person_phones_primary_person enforces at most one row per person_pk WHERE deleted_at IS NULL AND is_primary IS TRUE | true / false | Marks this phone number as the person’s primary contact number. At most one active PersonPhone per person may have is_primary = true at a time (enforced by partial unique index). |
| is_verify | boolean | ⚪ No | DEFAULT false | true / false | Indicates whether the phone number has been verified (e.g., via OTP or connector confirmation). |
| label | 🔒 system enum — person_phone_label_enum (native PostgreSQL enum) | ✅ Yes | DEFAULT ‘other’; stored as native enum core_api.person_phone_label_enum; values are the enum VALUE strings (lowercase) | mobile | work | personal | other | Categorises the nature or context of the phone number. Stored in a native PostgreSQL enum; the persisted value is the lowercase string (e.g. "mobile", not the TypeScript key MOBILE). |
| created_at | 🔒 system datetime | ✅ Yes | Set automatically on INSERT via onCreate hook; timestamptz NOT NULL | — | Timestamp when the pivot record was created. Set by the MikroORM onCreate lifecycle hook; never updated afterward. |
| deleted_at | 🔒 system datetime | null | ⚪ No | Nullable timestamptz; all active-record queries must filter deleted_at IS NULL | — | Soft-delete timestamp. When set, the link between the person and phone is logically removed but the row is retained for audit. The partial indexes on person_pk and the primary-phone uniqueness constraint both scope themselves to deleted_at IS NULL. |
Relationships
| Name | Type | Required | Description |
|---|
| person | to-one (ManyToOne) | ✅ Yes | The People record this phone number is associated with. Foreign key person_pk → core_api.people.pk. Indexed via partial index idx_person_phones_person (person_pk WHERE deleted_at IS NULL) for forward traversal, plus partial unique index for primary-phone uniqueness. |
| phone | to-one (ManyToOne) | ✅ Yes | The atomic Phone record containing the actual phone number value (e.g. e164_number). Foreign key phone_pk → core_api.phones.pk. Indexed via idx_person_phones_phone (phone_pk) for reverse traversal (phones → person_phones array relationship). |
System-computed
- pk — auto-increment serial, internal join key only; never exposed in the public API
- created_at — set on INSERT by MikroORM
onCreate: () => new Date() hook; no onUpdate hook exists on this entity (no updated_at column)
- deleted_at — soft-delete field; set to current timestamp when the phone association is removed via People mutation or connector sync; null on active records
- label default — ORM default
PersonPhoneLabelEnum.OTHER (‘other’) applied on entity construction; also enforced as DEFAULT 'other' in PostgreSQL via the native enum column
- is_primary default — ORM default
false; also DEFAULT false in PostgreSQL
- is_verify default — ORM default
false; also DEFAULT false in PostgreSQL
- Partial unique index
uniq_person_phones_primary_person — system-enforced constraint preventing more than one primary phone per person among non-deleted rows; managed at DB level, not ORM level
Example
{
"data": {
"type": "person_phone",
"attributes": {
"is_primary": true,
"is_verify": false,
"label": "mobile",
"created_at": "2025-11-14T09:23:17.000Z",
"deleted_at": null
},
"relationships": {
"person": {
"data": { "type": "people", "id": "d3a1c9e7-4f02-4b88-9c11-2e5f7a83bc40" }
},
"phone": {
"data": { "type": "phone", "id": "a7b2e451-0c3d-4e6f-8110-9d4f2c1b5e78" }
}
}
}
}
apps/api/src/database/entities/PersonPhone.ts · domain: financial-graph · tier: Supporting
