Skip to content
Levr API Documentation
Download OpenAPI specOpenAPI

Hand off to an AI agent

Copy instructions to your AI agent

Copy this guide into your AI agent. It links to the current REST API and MCP documentation.

You are helping someone integrate their system with Levr. Use Levr's published documentation and machine-readable contracts as the source of truth. Do not invent endpoints, fields, or MCP tools.

  1. Start with the Levr API documentation to choose between a server-to-server REST integration and a user-authorized MCP connection.
  2. For REST, read the Markdown REST API guide, choose the user’s task, then fetch only the relevant resource guide and operation Markdown. Resource indexes include task guidance. For funding recommendations, start with the Matchmaking guide. Use the OpenAPI specification for exact paths, authentication, parameters, and envelope schemas.
  3. For REST client intake, Deal applications, or project Criteria, fetch that resource's contract_url. Its Application Contract is the authority for the current questions, stable keys, repeatable groups, file-transfer steps, accepted answer shapes, conditional visibility, supported operation URLs, and integration instructions. Repeatable fields require the returned item_id. File bytes use the expiring upload_url and multipart field named file; they never belong in JSON. Do not substitute a static example or the latest application definition.
  4. For an AI client acting with a signed-in user's access, read the MCP connection instructions in Markdown first, then the Model Context Protocol guide if needed. Let the connected MCP server expose its current tools and input contracts; do not infer tools from the REST API. Read the relevant MCP resource guide and follow the discovered tool’s revision, file-transfer, and confirmation requirements.
  5. Use URLs from the record handoff when supplied; otherwise use this documentation environment. Keep API keys and file-transfer credentials out of browser code, logs, prompts, and source control.
  6. Before implementing a write, verify authentication, required inputs, idempotency, error responses, and retry guidance in the current contract. If an operation is not documented, do not assume it exists.

Early access

Request an integration

Tell us what your integration needs to do. Add an email if you want a reply.

People guide

Manage people and their CRM history

Read as Markdown

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.

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:

ReadWhat 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.