People guide
Manage people and their CRM history
Read as MarkdownFind 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.
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:
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.
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 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.
