# Manage people and their CRM history

## Find the person

People are your Portal's CRM records. A person can have several business and deal relationships and several contact methods,
without having a Levr account. Updating a person never invites a user or grants access to a conversation.

Authenticate with `Authorization: Bearer YOUR_API_KEY`. Use `people:read` for discovery and permitted history, or `people:write`
for CRM changes. The key's provider and source scope still apply. Source-scoped keys reach people through authorized business
or deal relationships; a contact's other relationships do not expand that scope.

```http
GET /v1/people/?search=alex&is_archived=false&page_size=20
Authorization: Bearer YOUR_API_KEY
```

Copy the `id` from the chosen result. It is a system-generated **person slug**, such as `pers_7k2m9q4v6x8n3p5r`,
not a name, email address, login user ID, or database primary key. Read that record's details:

```http
GET /v1/people/pers_7k2m9q4v6x8n3p5r/details/
Authorization: Bearer YOUR_API_KEY
```

Example response excerpt (`200 OK`, `ETag: "1768471200000000"`):

```
{
  "id": "pers_7k2m9q4v6x8n3p5r",
  "object": "person",
  "full_name": "Alex Rivera",
  "email": "alex@example.invalid",
  "phone_number": "+16045550123",
  "is_archived": false,
  "merged_into_id": null,
  "contact_methods": [
    {"slug": "pcm_7n2v9k4m6p3r8x5q", "kind": "email", "value": "alex@example.invalid", "label": "", "is_primary": true},
    {"slug": "pcm_2q8v4n6k9m3x7p5r", "kind": "email", "value": "alex.personal@example.invalid", "label": "Personal", "is_primary": false},
    {"slug": "pcm_5r8x2k6m9v3n7q4p", "kind": "phone", "value": "+16045550123", "label": "", "is_primary": true}
  ],
  "communication_preferences": [
    {"channel": "email", "purpose": "marketing", "status": "unspecified", "effective_status": "unspecified", "changed_at": null}
  ],
  "revision": 1768471200000000,
  "detail_link": "https://example.invalid/portal/acme/people/pers_7k2m9q4v6x8n3p5r"
}
```

The existing `email` and `phone_number` fields project the primary contact methods. Every method, including a primary,
has a stable `pcm_` slug; changing its label or primary designation retains that identity. The `example.invalid` link illustrates the shape; use the returned live link.
The existing `frontend_link` remains available for integrations that use the earlier People list destination.

## Update contact methods

Read details first. Send the complete set of methods to keep, including the primary values. Use `If-Match` with the current ETag
and a new `Idempotency-Key` for each intended write. Reuse the identical request and key after a timeout; use a new key for changed data.

```http
PUT /v1/people/pers_7k2m9q4v6x8n3p5r/contact-methods/
Authorization: Bearer YOUR_API_KEY
If-Match: "1768471200000000"
Idempotency-Key: crm-alex-contact-methods-1
Content-Type: application/json

{
  "methods": [
    {"kind": "email", "value": "alex@example.invalid", "label": "Work", "is_primary": true},
    {"kind": "email", "value": "alex.personal@example.invalid", "label": "Personal", "is_primary": false},
    {"kind": "phone", "value": "+16045550123", "label": "Mobile", "is_primary": true}
  ]
}
```

The response is the updated person details, with a new `revision` and ETag. Ordinary edits permit up to 20 methods.
If a merge leaves more than 20, you can retain or remove those inherited methods and edit labels or primary choices.
Each populated kind requires exactly one primary. An empty set clears methods only if the person still has a name. Changing a CRM address does not
rewrite message history or redirect an existing conversation's recipients. A matching address alone does not establish that two contacts are the same person.

Emails are trimmed and lowercased. Phone input accepts spaces, punctuation and extensions. National numbers default to
Canada/USA (+1); use an explicit country code for other countries. Complete numbers are returned in E.164 format,
with ` ext. N` for an extension. New numbers missing an area code are rejected; incomplete historical values remain
available for correction. For example, `(604) 555-0123 x42` becomes `+16045550123 ext. 42`.

A `412` means the record changed: read it again and reconcile the proposed edit. A changed body with an old idempotency key is a `409`.

## Read relationships and history

Use these collections with the same person slug:

| Read | What it returns |
| --- | --- |
| `GET /v1/people/{person_id}/relationships/` | Scoped businesses and deals, contextual roles, primary-contact status, and navigation links. |
| `GET /v1/people/{person_id}/activity/` | Permitted authored notes and activity, with timestamps, actors, and origin attribution. |
| `GET /v1/people/{person_id}/conversations/` | Associated public chat groups within the integration's current chat access. |
| `GET /v1/people/{person_id}/duplicates/` | Possible duplicates currently reachable by this key. |

Collections return `items`, `next_cursor`, and `previous_cursor`. Use `page_size` from 1 to 100; copy opaque cursors without
changing the original filters. Activity is newest first. Read the exact operation reference for supported search controls.
Access checks run before paging, so private or out-of-scope records do not appear in items or page metadata.

Example relationship item:

```
{
  "id": "biz_6q3n8v2k9m4x7p5r",
  "object": "person_relationship",
  "kind": "business",
  "name": "Acme Equipment",
  "role": "Owner",
  "is_primary": true,
  "frontend_link": "https://example.invalid/portal/acme/businesses/biz_6q3n8v2k9m4x7p5r"
}
```

Roles belong to a specific relationship. Alex can be the owner of one business and an adviser to another.
`POST /v1/people/{person_id}/relationship/` selects a `kind` (`business` or `deal`) and the related `record_id`,
with optional `role`, `is_primary`, and `remove`. Copy related IDs from their own discovery APIs.

Add an authored note through `POST /v1/people/{person_id}/notes/` with `{"text": "Alex asked for a call next Tuesday."}`.
This records a CRM note; it does not send a message.

## Work with conversations

A contact association records context. It neither adds the person to a group nor grants anyone conversation access.
To log an existing readable public group, POST its returned `conversation_id` to `/v1/people/{person_id}/conversation/`,
with the current Person ETag and an idempotency key. The integration needs access to that public group.

A People permission alone does not expose chat history. Without Chat groups read permission, the conversation collection is empty.
Private groups and direct conversations remain unavailable to API keys, including through People activity and associations.
Use the [chat guide](https://docs.levr.ai/guides/chat.md) to inspect actual participants and read or send messages. A CRM contact is not itself a chat recipient.

## Archive or review duplicates

POST `{"is_archived": true}` to `/v1/people/{person_id}/archive/` to remove a person from active use while preserving history.
Use `false` to restore them. Neither operation archives conversations. Supply `If-Match` and `Idempotency-Key` as for other CRM writes.

Use `GET /v1/people/{person_id}/duplicates/` to find possible duplicates. Review and merge them in the portal.
The External API does not merge people. A portal merge preserves the archived duplicate with a `merged_into_id` pointing to the retained person.

## Keep communication choices separate

PATCH a `preferences` array of the choices to update to `/v1/people/{person_id}/communication-preferences/`. Each item selects a `channel`
(`email` or `phone`), `purpose` (`operational` or `marketing`), and `status` (`allowed`, `blocked`, or `unspecified`).
Omitted channel/purpose pairs remain unchanged; set a pair explicitly to `unspecified` to reset it.
`is_do_not_contact` overrides individual allowances. `unspecified` marketing is not recorded consent.
The returned `effective_status` includes the global do-not-contact override; `changed_at` is null for an unset default.
These choices are separate from a user's in-app chat notifications and unread-message reminders.

Future workflow and campaign producers can retain person IDs, recipient snapshots, source references and execution outcomes
against these records. Setting a preference or adding a note does not enroll someone in a campaign or send an email.
