# Add a note to a company Source: https://leonar.mintlify.app/api-reference/companies/add-a-note-to-a-company /openapi.yaml post /companies/{id}/notes # Archive a company Source: https://leonar.mintlify.app/api-reference/companies/archive-a-company /openapi.yaml delete /companies/{id} # Create a company Source: https://leonar.mintlify.app/api-reference/companies/create-a-company /openapi.yaml post /companies # Get a company Source: https://leonar.mintlify.app/api-reference/companies/get-a-company /openapi.yaml get /companies/{id} Returns company details with contact and deal counts. # List companies Source: https://leonar.mintlify.app/api-reference/companies/list-companies /openapi.yaml get /companies # List company contacts Source: https://leonar.mintlify.app/api-reference/companies/list-company-contacts /openapi.yaml get /companies/{id}/contacts # List company custom field definitions Source: https://leonar.mintlify.app/api-reference/companies/list-company-custom-field-definitions /openapi.yaml get /companies/custom-fields Returns the workspace custom field definitions available for companies. # List company deals Source: https://leonar.mintlify.app/api-reference/companies/list-company-deals /openapi.yaml get /companies/{id}/deals # List company notes Source: https://leonar.mintlify.app/api-reference/companies/list-company-notes /openapi.yaml get /companies/{id}/notes # List company statuses Source: https://leonar.mintlify.app/api-reference/companies/list-company-statuses /openapi.yaml get /companies/statuses Returns the workspace company statuses that can be assigned through `status_id` on companies. # Update a company Source: https://leonar.mintlify.app/api-reference/companies/update-a-company /openapi.yaml put /companies/{id} Updates an existing company. `custom_data` uses partial merge semantics: - sent keys are upserted - keys set to `null` are removed - omitted keys are preserved # Add a note to a contact Source: https://leonar.mintlify.app/api-reference/contacts/add-a-note-to-a-contact /openapi.yaml post /contacts/{id}/notes # Add a tag to a contact Source: https://leonar.mintlify.app/api-reference/contacts/add-a-tag-to-a-contact /openapi.yaml post /contacts/{id}/tags # Archive a contact Source: https://leonar.mintlify.app/api-reference/contacts/archive-a-contact /openapi.yaml delete /contacts/{id} Archives a contact by setting `archived_at`. Archived contacts are excluded from list queries by default. # Create a contact Source: https://leonar.mintlify.app/api-reference/contacts/create-a-contact /openapi.yaml post /contacts Creates a new contact in the workspace. # Delete a contact CV Source: https://leonar.mintlify.app/api-reference/contacts/delete-a-contact-cv /openapi.yaml delete /contacts/{id}/cv Removes the current CV from a contact. # Enrich a contact Source: https://leonar.mintlify.app/api-reference/contacts/enrich-a-contact /openapi.yaml post /contacts/{id}/enrich Triggers enrichment to find email or phone number for a contact. # Get a contact Source: https://leonar.mintlify.app/api-reference/contacts/get-a-contact /openapi.yaml get /contacts/{id} Returns contact details including positions, pipeline entries, and active enrollments. # Get a contact CV Source: https://leonar.mintlify.app/api-reference/contacts/get-a-contact-cv /openapi.yaml get /contacts/{id}/cv Returns the current CV metadata for a contact. # List contact custom field definitions Source: https://leonar.mintlify.app/api-reference/contacts/list-contact-custom-field-definitions /openapi.yaml get /contacts/custom-fields Returns the workspace custom field definitions available for contacts. # List contact notes Source: https://leonar.mintlify.app/api-reference/contacts/list-contact-notes /openapi.yaml get /contacts/{id}/notes Returns contact notes. By default this lists only global contact notes; pass `project_id` to scope the listing to notes attached to that contact within a specific project. # List contacts Source: https://leonar.mintlify.app/api-reference/contacts/list-contacts /openapi.yaml get /contacts Returns a paginated list of contacts. Archived contacts are excluded by default. # Remove a tag from a contact Source: https://leonar.mintlify.app/api-reference/contacts/remove-a-tag-from-a-contact /openapi.yaml delete /contacts/{id}/tags # Search contacts Source: https://leonar.mintlify.app/api-reference/contacts/search-contacts /openapi.yaml post /contacts/search Advanced full-text search across contacts with combined filters. # Update a contact Source: https://leonar.mintlify.app/api-reference/contacts/update-a-contact /openapi.yaml put /contacts/{id} Updates an existing contact. Only specified fields are updated. `custom_data` uses partial merge semantics: - sent keys are upserted - keys set to `null` are removed - omitted keys are preserved # Upload or replace a contact CV Source: https://leonar.mintlify.app/api-reference/contacts/upload-or-replace-a-contact-cv /openapi.yaml post /contacts/{id}/cv Uploads a CV file for a contact using multipart/form-data. # Get a conversation Source: https://leonar.mintlify.app/api-reference/conversations/get-a-conversation /openapi.yaml get /conversations/{id} # List conversations Source: https://leonar.mintlify.app/api-reference/conversations/list-conversations /openapi.yaml get /conversations # List messages Source: https://leonar.mintlify.app/api-reference/conversations/list-messages /openapi.yaml get /conversations/{id}/messages # Send a message in a conversation Source: https://leonar.mintlify.app/api-reference/conversations/send-a-message-in-a-conversation /openapi.yaml post /conversations/{id}/messages # List deal pipelines Source: https://leonar.mintlify.app/api-reference/deal-pipelines/list-deal-pipelines /openapi.yaml get /deal-pipelines Returns all deal pipelines with their stages. # Add a note to a deal Source: https://leonar.mintlify.app/api-reference/deals/add-a-note-to-a-deal /openapi.yaml post /deals/{id}/notes # Archive a deal Source: https://leonar.mintlify.app/api-reference/deals/archive-a-deal /openapi.yaml delete /deals/{id} # Close a deal Source: https://leonar.mintlify.app/api-reference/deals/close-a-deal /openapi.yaml post /deals/{id}/close Closes a deal as won, lost, or unqualified. Lost and unqualified deals require a matching close reason, while won deals must not send one. # Create a deal Source: https://leonar.mintlify.app/api-reference/deals/create-a-deal /openapi.yaml post /deals # Create a deal from intake data Source: https://leonar.mintlify.app/api-reference/deals/create-a-deal-from-intake-data /openapi.yaml post /deals/intake Creates or reuses a company and contact, then creates a new deal in the requested stage. Company deduplication checks existing records by domain, then name. Contact deduplication checks existing records by email, then name + company. # Get a deal Source: https://leonar.mintlify.app/api-reference/deals/get-a-deal /openapi.yaml get /deals/{id} Returns deal details with company, stage, and linked contacts. # Link a contact to a deal Source: https://leonar.mintlify.app/api-reference/deals/link-a-contact-to-a-deal /openapi.yaml post /deals/{id}/contacts # List deal contacts Source: https://leonar.mintlify.app/api-reference/deals/list-deal-contacts /openapi.yaml get /deals/{id}/contacts # List deal notes Source: https://leonar.mintlify.app/api-reference/deals/list-deal-notes /openapi.yaml get /deals/{id}/notes # List deals Source: https://leonar.mintlify.app/api-reference/deals/list-deals /openapi.yaml get /deals # Move deal to a stage Source: https://leonar.mintlify.app/api-reference/deals/move-deal-to-a-stage /openapi.yaml put /deals/{id}/stage Moves a deal to a different pipeline stage. The deal must be open and the stage must belong to the same pipeline. # Reopen a deal Source: https://leonar.mintlify.app/api-reference/deals/reopen-a-deal /openapi.yaml post /deals/{id}/reopen Reopens a closed deal, setting status back to `open`. # Unlink a contact from a deal Source: https://leonar.mintlify.app/api-reference/deals/unlink-a-contact-from-a-deal /openapi.yaml delete /deals/{id}/contacts # Update a deal Source: https://leonar.mintlify.app/api-reference/deals/update-a-deal /openapi.yaml put /deals/{id} # Get enrichment status Source: https://leonar.mintlify.app/api-reference/enrichment/get-enrichment-status /openapi.yaml get /enrichment/{requestId} Poll the status of an enrichment request. # API Reference Source: https://leonar.mintlify.app/api-reference/introduction Complete reference for all Leonar API endpoints. The Leonar API is organized around REST. It uses standard HTTP methods, returns JSON responses, and uses Bearer token authentication. ## Base URL ``` https://app.leonar.app/api/v1 ``` ## Authentication Include your API key in the `Authorization` header: ``` Authorization: Bearer leo_your_api_key ``` ## Resources Manage contacts, search, enrich, and read custom field values. Track companies, their contacts, and company custom fields. Manage sales pipeline and deal stages. Organize recruiting projects. Automate outreach campaigns. Track to-dos and follow-ups. Send emails and WhatsApp messages. Find emails and phone numbers. ## Custom fields Contacts and companies can include workspace-defined custom fields in the `custom_data` object. * use `GET /contacts/custom-fields` and `GET /companies/custom-fields` to discover valid keys * read values from `custom_data` on contact and company responses * update values with partial merge semantics on `PUT /contacts/{id}` and `PUT /companies/{id}` # Send a message to a contact Source: https://leonar.mintlify.app/api-reference/messages/send-a-message-to-a-contact /openapi.yaml post /messages Sends a message to a contact. Creates a conversation if one doesn't exist. # Delete a note Source: https://leonar.mintlify.app/api-reference/notes/delete-a-note /openapi.yaml delete /notes/{id} # Get a note Source: https://leonar.mintlify.app/api-reference/notes/get-a-note /openapi.yaml get /notes/{id} # Update a note Source: https://leonar.mintlify.app/api-reference/notes/update-a-note /openapi.yaml patch /notes/{id} # Get a pipeline entry Source: https://leonar.mintlify.app/api-reference/pipeline-entries/get-a-pipeline-entry /openapi.yaml get /pipeline-entries/{id} # Partially update a pipeline entry Source: https://leonar.mintlify.app/api-reference/pipeline-entries/partially-update-a-pipeline-entry /openapi.yaml patch /pipeline-entries/{id} Partially updates a pipeline entry. Omitted fields are preserved. Use this endpoint to move a contact to another project stage by passing the target stage UUID in `stage_id`. `PUT` remains available with the same partial-update behavior for backward compatibility. # Remove from pipeline Source: https://leonar.mintlify.app/api-reference/pipeline-entries/remove-from-pipeline /openapi.yaml delete /pipeline-entries/{id} # Update a pipeline entry Source: https://leonar.mintlify.app/api-reference/pipeline-entries/update-a-pipeline-entry /openapi.yaml put /pipeline-entries/{id} Updates a pipeline entry. Use this endpoint to move a contact to another project stage by passing the target stage UUID in `stage_id`. To find available stage IDs for a project, call `GET /projects/{id}` and read `data.pipeline.stages`. # Add contact to pipeline Source: https://leonar.mintlify.app/api-reference/projects/add-contact-to-pipeline /openapi.yaml post /projects/{id}/entries Adds an existing contact to a project's pipeline. If `stage_id` is omitted, the contact is added to the first stage of the project's pipeline. To add directly to a stage such as `Sourced`, first retrieve the stage ID with `GET /projects/{id}`, then pass that UUID as `stage_id`. `custom_variables` stores per-contact sequence values on this pipeline entry. Project variables such as `project_variable_1` are shared by all entries in the project and cannot be set here; update them with `PUT /projects/{id}` using the `project_variables` object. # Archive a project Source: https://leonar.mintlify.app/api-reference/projects/archive-a-project /openapi.yaml delete /projects/{id} # Create a project Source: https://leonar.mintlify.app/api-reference/projects/create-a-project /openapi.yaml post /projects # Create or link the project's default sequence Source: https://leonar.mintlify.app/api-reference/projects/create-or-link-the-projects-default-sequence /openapi.yaml post /projects/{id}/sequences # Get a project Source: https://leonar.mintlify.app/api-reference/projects/get-a-project /openapi.yaml get /projects/{id} Returns project details including pipeline stages and entry counts. # Get the project's default sequence Source: https://leonar.mintlify.app/api-reference/projects/get-the-projects-default-sequence /openapi.yaml get /projects/{id}/sequences # List pipeline entries Source: https://leonar.mintlify.app/api-reference/projects/list-pipeline-entries /openapi.yaml get /projects/{id}/entries Returns candidates in a project's pipeline. The project is always scoped by the `{id}` path parameter. To narrow the result to one pipeline stage within that project, pass the stage UUID in the `stage_id` query parameter. Stage names such as `Sourced` are not accepted as filters. Use `GET /projects/{id}` to retrieve the project's pipeline stages and their IDs, then pass the matching stage ID here. # List projects Source: https://leonar.mintlify.app/api-reference/projects/list-projects /openapi.yaml get /projects # Remove the project's default sequence Source: https://leonar.mintlify.app/api-reference/projects/remove-the-projects-default-sequence /openapi.yaml delete /projects/{id}/sequences # Set or replace the project's default sequence Source: https://leonar.mintlify.app/api-reference/projects/set-or-replace-the-projects-default-sequence /openapi.yaml put /projects/{id}/sequences # Update a project Source: https://leonar.mintlify.app/api-reference/projects/update-a-project /openapi.yaml put /projects/{id} # Activate a draft sequence Source: https://leonar.mintlify.app/api-reference/sequences/activate-a-draft-sequence /openapi.yaml post /sequences/{id}/activate # Create a draft sequence Source: https://leonar.mintlify.app/api-reference/sequences/create-a-draft-sequence /openapi.yaml post /sequences Creates a draft sequence, optionally with branched steps and a project link. # Enroll contacts Source: https://leonar.mintlify.app/api-reference/sequences/enroll-contacts /openapi.yaml post /sequences/{id}/enroll Enrolls contacts in a sequence. Skips contacts that are blacklisted, already enrolled, or active in another sequence. Use the simple `contact_ids` format when no per-contact custom variables are needed. Use the extended `contacts` format to provide values for sequence placeholders `{{custom_variable_1}}` through `{{custom_variable_5}}`. Custom variable keys are fixed; arbitrary keys such as `project_name` are rejected. # Get a sequence Source: https://leonar.mintlify.app/api-reference/sequences/get-a-sequence /openapi.yaml get /sequences/{id} Returns sequence details with steps and enrollment counts. # List enrolled contacts Source: https://leonar.mintlify.app/api-reference/sequences/list-enrolled-contacts /openapi.yaml get /sequences/{id}/enrollments Returns the contacts enrolled in the sequence, with their embedded contact record. # List sequence steps Source: https://leonar.mintlify.app/api-reference/sequences/list-sequence-steps /openapi.yaml get /sequences/{id}/steps Returns full editable sequence steps, including content templates, sender config, branching, and delays. # List sequences Source: https://leonar.mintlify.app/api-reference/sequences/list-sequences /openapi.yaml get /sequences # Pause a sequence and its pending tasks Source: https://leonar.mintlify.app/api-reference/sequences/pause-a-sequence-and-its-pending-tasks /openapi.yaml post /sequences/{id}/pause # Replace sequence steps Source: https://leonar.mintlify.app/api-reference/sequences/replace-sequence-steps /openapi.yaml put /sequences/{id}/steps Replaces the editable step list for a draft or paused sequence. Omitted existing steps are deleted; steps without `id` are created. Use `client_key` to reference newly-created branch steps from `parent_step_id`. Pending paused tasks are synchronized before resume. # Resume a paused sequence and its pending tasks Source: https://leonar.mintlify.app/api-reference/sequences/resume-a-paused-sequence-and-its-pending-tasks /openapi.yaml post /sequences/{id}/resume # Unenroll contacts Source: https://leonar.mintlify.app/api-reference/sequences/unenroll-contacts /openapi.yaml post /sequences/{id}/unenroll Removes contacts from a sequence. # Update a draft or paused sequence Source: https://leonar.mintlify.app/api-reference/sequences/update-a-draft-or-paused-sequence /openapi.yaml patch /sequences/{id} Active and archived sequences cannot be edited. Pause an active sequence first. # Upload a sequence step attachment Source: https://leonar.mintlify.app/api-reference/sequences/upload-a-sequence-step-attachment /openapi.yaml post /sequences/attachments # Create a tag Source: https://leonar.mintlify.app/api-reference/tags/create-a-tag /openapi.yaml post /tags # Delete a tag Source: https://leonar.mintlify.app/api-reference/tags/delete-a-tag /openapi.yaml delete /tags/{id} Permanently deletes a tag and removes all associations. # List tags Source: https://leonar.mintlify.app/api-reference/tags/list-tags /openapi.yaml get /tags # Create a task Source: https://leonar.mintlify.app/api-reference/tasks/create-a-task /openapi.yaml post /tasks # Delete a task Source: https://leonar.mintlify.app/api-reference/tasks/delete-a-task /openapi.yaml delete /tasks/{id} # Get a task Source: https://leonar.mintlify.app/api-reference/tasks/get-a-task /openapi.yaml get /tasks/{id} # List tasks Source: https://leonar.mintlify.app/api-reference/tasks/list-tasks /openapi.yaml get /tasks # Update a task Source: https://leonar.mintlify.app/api-reference/tasks/update-a-task /openapi.yaml put /tasks/{id} Update task fields. Setting `status` to `done` automatically sets `completed_at`. # Authentication Source: https://leonar.mintlify.app/authentication Authenticate your API requests with Bearer tokens. All API requests require authentication via a Bearer token in the `Authorization` header. ## API keys API keys are prefixed with `leo_` and can be created in **Settings > API** in your Leonar dashboard. ```bash theme={null} curl -X GET "https://app.leonar.app/api/v1/contacts" \ -H "Authorization: Bearer leo_your_api_key" ``` Keep your API keys secure. Never expose them in client-side code, public repositories, or URLs. ## Scopes Each API key has granular permissions controlled by scopes. When creating a key, select only the scopes your integration needs. | Scope | Description | | ------------------ | --------------------------------------- | | `contacts:read` | List and view contacts | | `contacts:write` | Create and update contacts | | `contacts:delete` | Archive contacts | | `companies:read` | List and view companies | | `companies:write` | Create and update companies | | `companies:delete` | Archive companies | | `deals:read` | List and view deals and pipelines | | `deals:write` | Create, update, close, and reopen deals | | `deals:delete` | Archive deals | | `notes:read` | List and view notes | | `notes:write` | Create and update notes | | `tags:read` | List tags | | `tags:write` | Create and manage tags | | `tasks:read` | List and view tasks | | `tasks:write` | Create, update, and delete tasks | | `enrichment:read` | View enrichment request status | | `enrichment:write` | Trigger contact enrichment | | `messages:read` | List conversations and messages | | `messages:write` | Send messages | | `projects:read` | List and view projects | | `projects:write` | Create and update projects | | `pipeline:read` | View pipeline entries | | `pipeline:write` | Add and move candidates in pipelines | | `sequences:read` | List sequences and enrollments | | `sequences:write` | Enroll and unenroll contacts | ## Scope bundles For convenience, you can use scope bundles when creating API keys: | Bundle | Includes | | ------------- | ------------------------------------------------ | | `full_access` | All scopes | | `read_only` | All `:read` scopes | | `crm` | Companies, deals, contacts, notes, tags | | `automation` | Sequences, contacts, pipeline, enrichment, tasks | ## Error responses If authentication fails, the API returns a `401` error: ```json theme={null} { "error": { "code": "invalid_api_key", "message": "Invalid API key" } } ``` If the API key lacks the required scope, a `403` is returned: ```json theme={null} { "error": { "code": "insufficient_scope", "message": "This endpoint requires the 'contacts:write' scope" } } ``` # Errors Source: https://leonar.mintlify.app/errors Error codes and how to handle them. The Leonar API uses standard HTTP status codes and returns structured error responses. ## Error format ```json theme={null} { "error": { "code": "validation_error", "message": "email: Invalid email format" } } ``` ## Error codes | Code | HTTP status | Description | | ----------------------- | ----------- | ----------------------------------------------------------------- | | `validation_error` | 400 | Invalid request data | | `invalid_api_key` | 401 | Missing or invalid API key | | `insufficient_credits` | 402 | The workspace does not have enough credits to cover this request. | | `insufficient_scope` | 403 | API key lacks the required scope | | `billing_required` | 403 | No active subscription on the workspace | | `plan_upgrade_required` | 403 | The current plan does not include this feature | | `not_found` | 404 | Resource not found | | `rate_limit_exceeded` | 429 | Too many requests | | `internal_error` | 500 | Server error | ## Handling errors ```typescript theme={null} const response = await fetch(`${BASE_URL}/contacts`, { headers: { Authorization: `Bearer ${apiKey}` }, }); if (!response.ok) { const { error } = await response.json(); switch (error.code) { case "invalid_api_key": throw new Error("Check your API key"); case "rate_limit_exceeded": // Wait and retry break; case "validation_error": console.error("Validation:", error.message); break; default: throw new Error(error.message); } } const { data } = await response.json(); ``` ```python theme={null} response = requests.get( f"{BASE_URL}/contacts", headers={"Authorization": f"Bearer {api_key}"}, ) if not response.ok: error = response.json()["error"] if error["code"] == "rate_limit_exceeded": time.sleep(60) # Wait and retry else: raise Exception(f"{error['code']}: {error['message']}") data = response.json()["data"] ``` # AI Agent Integration Source: https://leonar.mintlify.app/guides/ai-agents Build AI agents that autonomously operate on Leonar CRM data using the API. This guide explains how to connect an AI agent (Claude, GPT, LangChain, CrewAI, etc.) to the Leonar API so it can manage contacts, enroll in sequences, and track deals on behalf of your users. ## How it works The Leonar API is a standard REST API with an OpenAPI 3.0 spec. AI agent frameworks consume this spec to generate tool definitions automatically. ``` Your Agent → OpenAPI Spec → Tool Definitions → Leonar API ``` The OpenAPI spec at `openapi.yaml` is the single source of truth for REST-based agents. If your client supports MCP, you can also connect directly to Leonar's native [MCP server](/guides/mcp-server). ## Setup ### 1. Create a scoped API key Go to **Settings > API** and create a key with only the scopes your agent needs. | Agent use case | Recommended scopes | | ------------------- | ----------------------------------------------------------------------- | | Read-only research | `contacts:read`, `projects:read`, `companies:read` | | Outreach automation | `sequences:read`, `sequences:write`, `contacts:read`, `messaging:write` | | Full CRM agent | `read_only` + `contacts:write`, `projects:write`, `deals:write` | Never give an agent `admin` scope. Always use the minimum scopes required. ### 2. Load the OpenAPI spec ```python Claude (tool_use) theme={null} import anthropic import yaml # Load spec and convert operations to tools with open("openapi.yaml") as f: spec = yaml.safe_load(f) # Claude's tool_use format accepts OpenAPI-style schemas directly tools = [] for path, methods in spec["paths"].items(): for method, operation in methods.items(): if isinstance(operation, dict) and "operationId" in operation: tools.append({ "name": operation["operationId"], "description": operation.get("description", operation.get("summary", "")), "input_schema": extract_schema(operation), # your conversion logic }) ``` ```python LangChain / OpenAPI toolkit theme={null} from langchain_community.agent_toolkits.openapi import planner from langchain_community.utilities.requests import TextRequestsWrapper headers = {"Authorization": "Bearer leo_your_api_key"} toolkit = planner.create_openapi_agent( spec="openapi.yaml", requests_wrapper=TextRequestsWrapper(headers=headers), ) ``` ```typescript Vercel AI SDK theme={null} import { openapi } from "@ai-sdk/openapi"; const leonar = openapi({ url: "https://app.leonar.app/api/v1", apiKey: "leo_your_api_key", spec: "./openapi.yaml", }); ``` ### 3. Set the base URL and auth header ``` Base URL: https://app.leonar.app/api/v1 Authorization: Bearer leo_your_api_key Content-Type: application/json ``` ## Rate limiting strategy The API allows **2000 requests per hour**. For autonomous agents: * **Check headers**: Every response includes `X-RateLimit-Remaining` and `X-RateLimit-Reset` * **Batch operations**: Use bulk endpoints (e.g., enroll up to 500 contacts at once) instead of individual calls * **Exponential backoff**: On `429` responses, wait `2^attempt` seconds before retrying * **Pagination**: Default `limit=50`. Use `offset` to paginate. Don't fetch all pages unless needed. ```python theme={null} import time def api_call_with_retry(url, **kwargs): for attempt in range(5): response = requests.request(url=url, **kwargs) if response.status_code == 429: wait = 2 ** attempt time.sleep(wait) continue return response raise Exception("Rate limit exceeded after 5 retries") ``` ## Common agent workflows ### Workflow 1: Enrich and enroll in sequence ``` 1. POST /contacts/search → Find contacts matching criteria 2. POST /contacts/{id}/enrich → Find email (async) 3. GET /enrichment/{id} → Poll until completed 4. GET /sequences → Pick target sequence 5. POST /sequences/{id}/enroll → Enroll contacts ``` ### Workflow 2: Deal pipeline management ``` 1. GET /deal-pipelines → Get pipeline stages 2. POST /deals → Create deal 3. POST /deals/{id}/contacts → Link contacts to deal 4. PUT /deals/{id}/stage → Move through stages 5. POST /deals/{id}/close → Close as won/lost ``` ## Error handling for agents Your agent should handle these error patterns: | HTTP code | Error code | Agent action | | --------- | ----------------------- | --------------------------------------------- | | `400` | `validation_error` | Fix the request parameters and retry | | `401` | `invalid_api_key` | Stop — API key is invalid or revoked | | `401` | `insufficient_scope` | Stop — need a key with more scopes | | `403` | `billing_required` | Stop — workspace needs an active subscription | | `403` | `plan_upgrade_required` | Stop — feature not available on current plan | | `404` | `not_found` | The resource ID is wrong — verify and retry | | `429` | `rate_limit_exceeded` | Wait and retry with exponential backoff | | `500` | `internal_error` | Retry once, then stop and report | ```python theme={null} def handle_response(response): if response.ok: return response.json() error = response.json().get("error", {}) code = error.get("code", "unknown") if code == "rate_limit_exceeded": return "RETRY" elif code in ("invalid_api_key", "insufficient_scope", "billing_required"): return f"STOP: {error['message']}" elif code == "validation_error": return f"FIX_INPUT: {error['message']}" elif code == "not_found": return "RESOURCE_NOT_FOUND" else: return f"ERROR: {error['message']}" ``` ## Best practices for autonomous agents Let the agent explore data before writing. Most mistakes come from creating or updating with wrong data. Enrolling 500 contacts in a sequence is hard to undo. Have the agent confirm with the user before bulk writes. Before creating a contact, search by email or profile URL to avoid duplicates. ## Testing your agent 1. **Create a test API key** with `read_only` scopes only 2. **Run your agent** on a read-only task (e.g., "list all active projects and their candidate counts") 3. **Verify outputs** — check that the agent correctly interprets the API responses 4. **Upgrade scopes** once read-only works, add write scopes one at a time 5. **Test write operations** on a test project before going live # Custom fields Source: https://leonar.mintlify.app/guides/custom-fields Read field definitions and manage custom field values on contacts and companies. Custom fields let each workspace store extra CRM data on contacts and companies. In the public API: * field definitions are exposed as read-only metadata * field values are stored in `custom_data` * updates to `custom_data` use **partial merge** semantics ## 1. Read field definitions Use the dedicated definition endpoints to discover valid field keys and types before writing values. ```bash Contacts theme={null} curl -X GET "https://app.leonar.app/api/v1/contacts/custom-fields" \ -H "Authorization: Bearer leo_your_api_key" ``` ```bash Companies theme={null} curl -X GET "https://app.leonar.app/api/v1/companies/custom-fields" \ -H "Authorization: Bearer leo_your_api_key" ``` Example response: ```json theme={null} { "data": [ { "id": "cf2b8df3-1c85-4e5d-8f50-0c10b3994e90", "key": "crm_tier", "label": "CRM Tier", "type": "select", "options": [ { "value": "enterprise", "label": "Enterprise" }, { "value": "mid_market", "label": "Mid-market" } ], "is_required": false, "position": 0 } ], "meta": { "total": 1, "limit": 1, "offset": 0, "has_more": false } } ``` ## 2. Read custom field values Custom field values are returned in the `custom_data` object on contact and company responses. ```json theme={null} { "data": { "id": "contact-uuid", "first_name": "Sophie", "custom_data": { "industry_code": "A12", "vip": true } } } ``` ## 3. Update custom field values `PUT /contacts/{id}` and `PUT /companies/{id}` merge `custom_data` into the existing object: * sent keys are created or updated * keys set to `null` are removed * omitted keys are preserved ```bash theme={null} curl -X PUT "https://app.leonar.app/api/v1/contacts/contact-uuid" \ -H "Authorization: Bearer leo_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "custom_data": { "industry_code": "A12", "vip": null } }' ``` If the contact already had: ```json theme={null} { "custom_data": { "crm_owner": "alice", "vip": true } } ``` the result becomes: ```json theme={null} { "custom_data": { "crm_owner": "alice", "industry_code": "A12" } } ``` ## 4. Validation rules The API validates `custom_data` against the workspace definitions: * unknown keys are rejected * `select` values must match an allowed option * `multiselect` values must all match allowed options * `number`, `currency`, `boolean`, `date`, `datetime`, `url`, and `email` values must match the field type * required fields cannot be removed with `null` ## 5. Recommended integration flow 1. Read definitions from `/contacts/custom-fields` or `/companies/custom-fields` 2. Cache `key`, `type`, and `options` 3. Read entities and inspect `custom_data` 4. Send partial `custom_data` updates only for the keys you want to change # MCP Server Source: https://leonar.mintlify.app/guides/mcp-server Connect Claude Code, Claude Desktop, Cursor, Codex, or any MCP client directly to Leonar using the Model Context Protocol. Leonar exposes a native [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that lets AI assistants call Leonar tools and read contextual resources directly. ``` AI Assistant → MCP Protocol → Leonar MCP Server → Leonar CRM data ``` ## Quick start ### 1. Choose your setup * **Claude Desktop / Claude.ai / Claude remote connector (recommended)**: use the hosted MCP endpoint directly. No Leonar API key is required; Claude redirects you to Leonar and you authorize one workspace via OAuth. * **Claude Code / Codex / Cursor / generic MCP clients that do not support OAuth remote connectors**: use either Direct HTTP with a Bearer API key, or the local `@leonar/mcp` NPX bridge. ### 2. Configure your MCP client For Claude Desktop, prefer the remote connector tab below. The NPX package is only for local/API-key clients that need a stdio command. In Claude Desktop or Claude.ai, go to **Settings / Customize > Connectors**, choose **Add custom connector**, and enter the Leonar MCP endpoint: ``` https://app.leonar.app/api/mcp ``` When Claude connects without a token, Leonar advertises its OAuth metadata automatically. Claude opens Leonar's sign-in page, you choose the workspace to share, and Leonar returns an OAuth access token scoped to that workspace. For Claude Desktop and Claude.ai, enter exactly `https://app.leonar.app/api/mcp`. Do not use another host, path, or any API key query parameter; Claude handles authorization through OAuth. For Team and Enterprise Claude plans, an organization owner may need to add the custom connector first. Members can then connect and enable it individually. Use this only for MCP clients that need a local stdio command and cannot use Claude's remote OAuth connector. Create a `leo_...` API key first in **Settings > API**. ```json Claude Code (.mcp.json) theme={null} { "mcpServers": { "leonar": { "command": "npx", "args": ["-y", "@leonar/mcp"], "env": { "LEONAR_API_KEY": "leo_your_api_key" } } } } ``` ```json Cursor (.cursor/mcp.json) theme={null} { "mcpServers": { "leonar": { "command": "npx", "args": ["-y", "@leonar/mcp"], "env": { "LEONAR_API_KEY": "leo_your_api_key" } } } } ``` Requires Node.js 18+. The package ([`@leonar/mcp`](https://www.npmjs.com/package/@leonar/mcp)) is a lightweight bridge that forwards MCP messages to the Leonar server over Streamable HTTP while preserving stdio request order. It authenticates with a Leonar API key, unlike the Claude remote connector OAuth flow. If your MCP client supports the `url` transport type, you can connect directly without any package: ``` https://app.leonar.app/api/mcp ``` ```json Claude Code (.mcp.json) theme={null} { "mcpServers": { "leonar": { "type": "url", "url": "https://app.leonar.app/api/mcp", "headers": { "Authorization": "Bearer leo_your_api_key" } } } } ``` ```json Codex / Generic MCP client theme={null} { "mcpServers": { "leonar": { "type": "url", "url": "https://app.leonar.app/api/mcp", "headers": { "Authorization": "Bearer leo_your_api_key" } } } } ``` ### 3. Start using tools Once connected, your AI assistant has access to the same safe workflow tools used by Leonar's integrated AI agent, plus 4 contextual resources. Ask it things like: * *"Show me the context for the Senior PM project"* * *"Find companies hiring Account Executives and identify their sales leaders"* ## Business-development prospecting ## Authentication Leonar supports two authentication modes for MCP: * **OAuth** for Claude remote connectors. This is the recommended path for Claude Desktop and Claude.ai. Claude discovers Leonar's OAuth metadata automatically from the MCP endpoint, redirects you to Leonar, and receives an access token scoped to one workspace. * **Bearer API keys** for local/API-key clients such as Claude Code, Codex, Cursor, and generic MCP clients that do not use the OAuth connector flow. For API-key clients, the MCP server uses the same `leo_` API keys as the REST API. Pass your key as a Bearer token in the `Authorization` header. ``` Authorization: Bearer leo_your_api_key ``` Each tool requires specific scopes. If the API key lacks a required scope, the tool returns an error. See the [scopes reference](/authentication#scopes) for the full list. Use the minimum scopes your assistant needs. For read-only exploration, start with `contacts:read`, `projects:read`, and `companies:read`. High-impact mutations should be handled carefully by MCP clients. For business-development prospecting, always show the result of `preview_prospecting_enrollment` and ask for confirmation before calling `commit_prospecting_enrollment`. ## Transport The MCP server uses **Streamable HTTP** transport over a single endpoint (`POST /api/mcp`). It is stateless — no session management is required. All MCP clients that support the `url` transport type can connect directly. For custom HTTP clients or manual tests, include both accepted response types: ```http theme={null} Accept: application/json, text/event-stream Authorization: Bearer leo_your_api_key Content-Type: application/json ``` The NPX bridge sets these headers automatically. ## Available resources The server also exposes these read-only resources: | Resource URI | Description | | ----------------------------- | ----------------------------------------------------------- | | `leonar://workspace/context` | Workspace metadata, billing state, and lightweight counters | | `leonar://accounts/connected` | Active connected accounts available for sending | | `leonar://team/members` | Workspace members and roles | | `leonar://pipeline/templates` | Pipeline templates with their stages | ## Available tools The MCP server exposes the main CRM API resources as explicit tools. Assistant memory tools and provider-specific search tools are not exposed over external MCP. | Object | Tools | Scopes | | ------ | ----- | ------ | \| Contacts | `search_contacts`, `get_contact`, `create_contact`, `update_contact`, `delete_contact` | `contacts:read`, `contacts:write`, `contacts:delete` | \| Companies | `search_companies`, `get_company`, `create_company`, `update_company`, `delete_company` | `companies:read`, `companies:write`, `companies:delete` | \| Projects | `search_projects`, `get_project`, `create_project`, `update_project`, `delete_project`, `add_contact_to_project` | `projects:read`, `projects:write`, `pipeline:write` | \| Sequences | `search_sequences`, `get_sequence`, `get_sequence_steps`, `update_sequence_steps`, `list_sequence_enrollments`, `enroll_contacts_in_sequence`, `unenroll_contacts_from_sequence` | `sequences:read`, `sequences:write` | \| Deals | `search_deals`, `get_deal`, `create_deal`, `update_deal`, `delete_deal` | `deals:read`, `deals:write`, `deals:delete` | \| Notes | `search_notes`, `create_note`, `update_note`, `delete_note` | `notes:read`, `notes:write` | Delete tools archive records when the API resource supports soft deletion. Notes are deleted from their note table. ## Tool parameters reference ### Common read parameters ```typescript theme={null} // get_* and delete_* tools { id: string } // search_* tools { search?: string limit?: number // max 100 offset?: number } ``` ### Contacts ```typescript theme={null} // search_contacts also accepts: { company_id?: string location?: string } // create_contact / update_contact { first_name: string last_name?: string title?: string current_company?: string location?: string linkedin_profile?: string emails?: { email: string; type?: "work" | "personal" }[] phones?: { phone: string; type?: "work" | "personal" }[] contact_type?: string[] tags?: string[] source?: string summary?: string company_id?: string custom_data?: Record } ``` ### Companies ```typescript theme={null} // search_companies also accepts: { industry?: string owner_id?: string } // create_company / update_company { name: string domain?: string industry?: string company_size?: string description?: string location?: string phone?: string linkedin_url?: string owner_id?: string custom_data?: Record } ``` ### Projects ```typescript theme={null} // search_projects also accepts: { status?: "active" | "archived" | "all" } // create_project / update_project { name: string client_name?: string client_company_id?: string owner_ids?: string[] template_id?: string location?: string description?: string } // add_contact_to_project { project_id: string contact_id: string stage_id?: string // defaults to the first stage } ``` ### Sequences ```typescript theme={null} // search_sequences also accepts: { status?: "active" | "paused" | "draft" | "archived" | "all" } // list_sequence_enrollments { sequence_id: string status?: "active" | "paused" | "pending" | "finished" | "replied" | "bounced" | "all" search?: string limit?: number offset?: number } // enroll_contacts_in_sequence { sequence_id: string contact_ids?: string[] contacts?: { contact_id: string custom_variables?: { custom_variable_1?: string | null custom_variable_2?: string | null custom_variable_3?: string | null custom_variable_4?: string | null custom_variable_5?: string | null } }[] } // unenroll_contacts_from_sequence { sequence_id: string contact_ids: string[] reason?: string } ``` ### Deals ```typescript theme={null} // search_deals also accepts: { status?: "open" | "won" | "lost" | "unqualified" | "all" company_id?: string owner_id?: string } // create_deal / update_deal { title: string company_id: string pipeline_id?: string stage_id?: string contact_id?: string project_id?: string owner_id?: string primary_source_id?: string | null amount?: number currency?: string expected_amount?: number expected_close_date?: string probability?: number custom_data?: Record } ``` ### Notes ```typescript theme={null} // search_notes { entity_type?: "contact" | "company" | "deal" | "project" entity_id?: string search?: string limit?: number offset?: number } // create_note { entity_type: "contact" | "company" | "deal" | "project" entity_id: string content: string is_pinned?: boolean project_id?: string } // update_note { id: string entity_type: "contact" | "company" | "deal" | "project" content?: string is_pinned?: boolean } ``` ## Example use cases *"Find contacts at Acme and summarize their current roles."* The assistant calls `search_contacts` and reads the returned contact records. *"Create a project for our new backend role and attach Acme as the client company."* The assistant can use `search_companies` then `create_project`. *"Update this deal amount and expected close date."* Uses `update_deal` with the same API key scopes as the REST API. *"Add this call summary to the company record."* Uses `create_note` with `entity_type: "company"`. ## Rate limits The MCP server shares the same base rate limit as the REST API: **2000 requests per hour**. * For API-key clients, the quota is tracked per API key. * For Claude remote connectors, the quota is tracked per OAuth authorization (`client + workspace + user`). Refreshing an access token does not reset the quota. Each tool call counts as one request. ## MCP vs REST API | | MCP Server | REST API | | ------------ | -------------------------------------------------------------------------------------------- | ---------------------------- | | **Best for** | AI assistants (Claude, Cursor, Codex) | Custom integrations, scripts | | **Protocol** | Model Context Protocol | HTTP REST | | **Auth** | OAuth for Claude remote connectors; `leo_` API keys for local/API-key MCP clients | Same `leo_` API keys | | **Scopes** | Same scope system | Same scope system | | **Tools** | Main CRM object tools, project pipeline entry tools, sequence enrollment tools + 4 resources | 60+ endpoints (full CRUD) | Use the MCP server when connecting an AI assistant. Use the REST API when building custom integrations or scripts that need full CRUD access to all resources. # Quickstart Source: https://leonar.mintlify.app/guides/quickstart Build your first Leonar integration in 5 minutes. This guide walks you through setting up API access and making your first requests. ## 1. Get your API key Go to **Settings > API** in your [Leonar dashboard](https://app.leonar.app). Click **Create API key**, give it a name, and select the scopes you need. For this quickstart, select the `read_only` bundle. Copy the key starting with `leo_`. You won't be able to see it again. ## 2. Make your first request ```bash cURL theme={null} curl -X GET "https://app.leonar.app/api/v1/contacts?limit=5" \ -H "Authorization: Bearer leo_your_api_key" ``` ```typescript TypeScript theme={null} const response = await fetch("https://app.leonar.app/api/v1/contacts?limit=5", { headers: { Authorization: "Bearer leo_your_api_key", }, }); const { data, meta } = await response.json(); console.log(`Found ${meta.total} contacts`); ``` ```python Python theme={null} import requests response = requests.get( "https://app.leonar.app/api/v1/contacts", headers={"Authorization": "Bearer leo_your_api_key"}, params={"limit": 5}, ) result = response.json() print(f"Found {result['meta']['total']} contacts") ``` ## 3. Create a contact ```bash cURL theme={null} curl -X POST "https://app.leonar.app/api/v1/contacts" \ -H "Authorization: Bearer leo_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "first_name": "Sophie", "last_name": "Martin", "title": "Senior Developer", "current_company": "Doctolib", "emails": [{"email": "sophie@example.com", "type": "work"}] }' ``` ```typescript TypeScript theme={null} const contact = await fetch("https://app.leonar.app/api/v1/contacts", { method: "POST", headers: { Authorization: "Bearer leo_your_api_key", "Content-Type": "application/json", }, body: JSON.stringify({ first_name: "Sophie", last_name: "Martin", title: "Senior Developer", current_company: "Doctolib", emails: [{ email: "sophie@example.com", type: "work" }], }), }); const { data } = await contact.json(); console.log(`Created contact: ${data.id}`); ``` ```python Python theme={null} response = requests.post( "https://app.leonar.app/api/v1/contacts", headers={ "Authorization": "Bearer leo_your_api_key", "Content-Type": "application/json", }, json={ "first_name": "Sophie", "last_name": "Martin", "title": "Senior Developer", "current_company": "Doctolib", "emails": [{"email": "sophie@example.com", "type": "work"}], }, ) data = response.json()["data"] print(f"Created contact: {data['id']}") ``` ## 4. Search contacts Use the search endpoint for full-text search across contacts: ```bash theme={null} curl -X POST "https://app.leonar.app/api/v1/contacts/search" \ -H "Authorization: Bearer leo_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "query": "developer python", "location": "Paris", "limit": 20 }' ``` ## 5. Read custom field definitions Before writing `custom_data`, fetch the workspace definitions to discover valid keys: ```bash theme={null} curl -X GET "https://app.leonar.app/api/v1/contacts/custom-fields" \ -H "Authorization: Bearer leo_your_api_key" ``` ## 6. Update custom fields safely `custom_data` updates are merged into the existing object: ```bash theme={null} curl -X PUT "https://app.leonar.app/api/v1/contacts/contact-uuid" \ -H "Authorization: Bearer leo_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "custom_data": { "industry_code": "A12", "vip": true } }' ``` Send `null` to remove a non-required custom field key. ## Next steps * [Authentication and scopes](/authentication) for fine-grained permissions * [Custom fields guide](/guides/custom-fields) for contacts and companies * [API Reference](/api-reference/introduction) for the full endpoint documentation * [Scopes guide](/guides/scopes) to understand permission bundles # Scopes Source: https://leonar.mintlify.app/guides/scopes Choose the right permissions for your API key. Scopes control what an API key can access. Follow the principle of least privilege: request only the scopes your integration needs. ## Scope format Scopes follow the pattern `resource:action`: * `:read` - List and view resources * `:write` - Create and update resources * `:delete` - Archive or delete resources `:write` does not include `:delete`. If your integration needs to archive contacts, you must request both `contacts:write` and `contacts:delete`. ## Common use cases Use the `read_only` bundle, which includes all `:read` scopes. ``` contacts:read, companies:read, deals:read, notes:read, tags:read, tasks:read, enrichment:read, messages:read, projects:read, pipeline:read, sequences:read, relationship:read ``` Syncing contacts, companies, and deals with an external CRM: ``` contacts:read, contacts:write companies:read, companies:write deals:read, deals:write notes:read, notes:write tags:read relationship:read, relationship:write, relationship:review ``` Or use the `crm` bundle. Automatically enrich contacts and check results: ``` contacts:read enrichment:read, enrichment:write ``` ## Bundles Bundles are pre-configured groups of scopes for common integrations: | Bundle | Scopes included | | ------------- | ---------------------------------------------------------------------------------- | | `full_access` | Every scope | | `read_only` | All `:read` scopes | | `crm` | Companies, deals, contacts, notes, tags, Company relationships (read/write/review) | | `automation` | Sequences, contacts, pipeline, enrichment, tasks | ## Company relationship scopes | Scope | Access | | ------------------------ | -------------------------------------------------------------------------------------------------------------------- | | `relationship:read` | Company summaries, sourced history, status and attention state, roles, identity links, next actions, and suggestions | | `relationship:write` | Company status/attention updates, contact roles, next actions, and preparation of reviewable suggestions | | `relationship:review` | Human approval or rejection after safeguards and history checkpoint validation | | `relationship:configure` | Admin-only external identity review | Relationship scopes never grant communication delivery. Approval returns data for the existing composer and records `approved_not_sent`; the normal human composer action remains separate. # Workflow Recipes Source: https://leonar.mintlify.app/guides/workflows Step-by-step API workflows for common recruiting operations. These recipes show how to chain API calls for complete recruiting workflows. Each recipe includes the exact endpoints, request bodies, and expected responses. ## Manage project pipeline entries Use this workflow when an integration needs to read candidates from a project, filter them by stage, add new leads to a project, or move existing leads through the pipeline. Pipeline entry filters use **stage IDs**, not stage names. Start by reading the project and storing the stage ID you need, for example the `Sourced` stage. ```bash theme={null} curl -X GET "https://app.leonar.app/api/v1/projects/project-uuid" \ -H "Authorization: Bearer leo_your_api_key" ``` Response excerpt: ```json theme={null} { "data": { "id": "project-uuid", "name": "Senior Frontend Engineers", "pipeline": { "stages": [ { "id": "sourced-stage-uuid", "name": "Sourced", "position": 0, "system_category": "sourced", "entries_count": 12 } ] } } } ``` The project is selected by the URL path (`/projects/{project_id}/entries`). Add `stage_id` as a query parameter to return only entries currently in that stage for the same project. Values like `Sourced` are not accepted directly; use the stage UUID returned by `GET /projects/{id}`. ```bash theme={null} curl -X GET "https://app.leonar.app/api/v1/projects/project-uuid/entries?stage_id=sourced-stage-uuid&limit=100&offset=0" \ -H "Authorization: Bearer leo_your_api_key" ``` If the lead is new, create a contact first: ```bash theme={null} curl -X POST "https://app.leonar.app/api/v1/contacts" \ -H "Authorization: Bearer leo_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "first_name": "Sophie", "last_name": "Martin", "title": "Senior Software Engineer", "current_company": "Doctolib", "linkedin_profile": "https://www.linkedin.com/in/sophie-martin" }' ``` If the lead already exists and you only need to update their profile, use: ```bash theme={null} curl -X PUT "https://app.leonar.app/api/v1/contacts/contact-uuid" \ -H "Authorization: Bearer leo_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "title": "Staff Software Engineer", "current_company": "Doctolib" }' ``` Add the contact to the project pipeline. If `stage_id` is omitted, Leonar adds the contact to the first stage of the project pipeline. Per-contact sequence values can be supplied under `custom_variables`. Project variables such as `project_variable_1` are shared by every entry in the project and must instead be set through `PUT /projects/{id}` under `project_variables`. ```bash theme={null} curl -X POST "https://app.leonar.app/api/v1/projects/project-uuid/entries" \ -H "Authorization: Bearer leo_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "contact_id": "contact-uuid", "stage_id": "sourced-stage-uuid", "custom_variables": { "custom_variable_1": "Per-contact value" } }' ``` Use the pipeline entry ID from `GET /projects/{id}/entries`, then pass the target stage UUID. ```bash theme={null} curl -X PATCH "https://app.leonar.app/api/v1/pipeline-entries/pipeline-entry-uuid" \ -H "Authorization: Bearer leo_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "stage_id": "target-stage-uuid" }' ``` *** ## Enrich a contact and find their email ```bash theme={null} curl -X POST "https://app.leonar.app/api/v1/contacts/contact-uuid/enrich" \ -H "Authorization: Bearer leo_your_api_key" \ -H "Content-Type: application/json" \ -d '{"type": "work_email"}' ``` Response: ```json theme={null} { "data": { "request_id": "enrich-request-uuid", "type": "work_email", "status": "pending" } } ``` Enrichment is asynchronous. Poll every 5 seconds: ```bash theme={null} curl -X GET "https://app.leonar.app/api/v1/enrichment/enrich-request-uuid" \ -H "Authorization: Bearer leo_your_api_key" ``` Response when completed: ```json theme={null} { "data": { "id": "enrich-request-uuid", "contact_id": "contact-uuid", "enrichment_type": "work_email", "status": "completed", "result": { "email": "sophie@doctolib.com", "confidence": 0.95 }, "created_at": "2025-02-10T10:00:00Z", "completed_at": "2025-02-10T10:00:08Z" } } ``` The email is automatically added to the contact record. No need to update the contact manually. *** ## Enroll contacts in a sequence ```bash theme={null} curl -X GET "https://app.leonar.app/api/v1/sequences?status=active&limit=10" \ -H "Authorization: Bearer leo_your_api_key" ``` ```bash theme={null} curl -X POST "https://app.leonar.app/api/v1/sequences/sequence-uuid/enroll" \ -H "Authorization: Bearer leo_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "contact_ids": [ "contact-uuid-1", "contact-uuid-2", "contact-uuid-3" ] }' ``` Sequence custom variables use fixed placeholder names: `{{custom_variable_1}}` through `{{custom_variable_5}}`. Add those placeholders in the sequence step content, then pass per-contact values in `custom_variables` when enrolling. Arbitrary names like `project_name` are rejected. Example sequence step: ```text theme={null} Hi {{first_name}}, I thought the {{custom_variable_1}} role could be a fit because of {{custom_variable_2}}. ``` Example enrollment payload: ```bash theme={null} curl -X POST "https://app.leonar.app/api/v1/sequences/sequence-uuid/enroll" \ -H "Authorization: Bearer leo_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "contacts": [ { "contact_id": "contact-uuid-1", "custom_variables": { "custom_variable_1": "Senior Frontend Engineer", "custom_variable_2": "your React component library work" } } ] }' ``` At send time, Leonar resolves the example step to something like: ```text theme={null} Hi Ada, I thought the Senior Frontend Engineer role could be a fit because of your React component library work. ``` Response: ```json theme={null} { "data": { "enrolled": 1, "skipped_blacklisted": 0, "skipped_already_enrolled": 0, "skipped_active_elsewhere": 0, "skipped_not_found": 0 } } ``` *** ## Create and manage a deal ```bash theme={null} curl -X GET "https://app.leonar.app/api/v1/deal-pipelines" \ -H "Authorization: Bearer leo_your_api_key" ``` ```bash theme={null} curl -X POST "https://app.leonar.app/api/v1/deals" \ -H "Authorization: Bearer leo_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "title": "Recruitment - 3 Senior Engineers", "company_id": "company-uuid", "pipeline_id": "pipeline-uuid", "amount": 45000, "currency": "EUR", "expected_close_date": "2025-03-15" }' ``` ```bash theme={null} curl -X POST "https://app.leonar.app/api/v1/deals/deal-uuid/contacts" \ -H "Authorization: Bearer leo_your_api_key" \ -H "Content-Type: application/json" \ -d '{"contact_id": "contact-uuid"}' ``` ```bash theme={null} curl -X PUT "https://app.leonar.app/api/v1/deals/deal-uuid/stage" \ -H "Authorization: Bearer leo_your_api_key" \ -H "Content-Type: application/json" \ -d '{"stage_id": "next-stage-uuid"}' ``` ```bash theme={null} curl -X POST "https://app.leonar.app/api/v1/deals/deal-uuid/close" \ -H "Authorization: Bearer leo_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "status": "won", "signed_amount": 45000, "actual_close_date": "2025-03-10" }' ``` *** ## Search and tag contacts ```bash theme={null} curl -X POST "https://app.leonar.app/api/v1/tags" \ -H "Authorization: Bearer leo_your_api_key" \ -H "Content-Type: application/json" \ -d '{"name": "ai-sourced", "color": "#6366F1", "scope": "contact"}' ``` ```bash theme={null} curl -X POST "https://app.leonar.app/api/v1/contacts/search" \ -H "Authorization: Bearer leo_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "query": "react typescript", "location": "Paris", "limit": 50 }' ``` For each matching contact: ```bash theme={null} curl -X POST "https://app.leonar.app/api/v1/contacts/contact-uuid/tags" \ -H "Authorization: Bearer leo_your_api_key" \ -H "Content-Type: application/json" \ -d '{"tag_id": "tag-uuid"}' ``` *** ## Send a message to a contact ```bash theme={null} curl -X POST "https://app.leonar.app/api/v1/messages" \ -H "Authorization: Bearer leo_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "contact_id": "contact-uuid", "channel": "email", "subject": "Exciting opportunity at Doctolib", "content": "Hi Sophie, I came across your profile..." }' ``` For first-time WhatsApp messages, provide an international phone number when the contact does not have an existing WhatsApp chat or provider ID: ```bash theme={null} curl -X POST "https://app.leonar.app/api/v1/messages" \ -H "Authorization: Bearer leo_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "contact_id": "contact-uuid", "channel": "whatsapp", "content": "Hi Sophie, I wanted to reach out on WhatsApp...", "recipient_phone": "+33612345678" }' ``` # Introduction Source: https://leonar.mintlify.app/introduction Build AI agents and integrations on top of Leonar CRM. Leonar is a recruiting CRM that helps teams manage contacts, companies, deals, projects, and outreach sequences. The Leonar API lets you programmatically access and manage all of this data. ## What you can do Create, search, update, and enrich contacts with emails and phone numbers. Enroll contacts in sequences, send messages via email or WhatsApp. Create and manage deals through pipeline stages, from qualification to close. ## Base URL All API requests use the following base URL: ``` https://app.leonar.app/api/v1 ``` ## Quick example ```bash theme={null} curl -X GET "https://app.leonar.app/api/v1/contacts?limit=10" \ -H "Authorization: Bearer leo_your_api_key" ``` ```json theme={null} { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "first_name": "Sophie", "last_name": "Martin", "title": "Senior Developer", "current_company": "Doctolib", "emails": [{"email": "sophie@example.com", "type": "work"}], "created_at": "2026-01-15T10:30:00Z" } ], "meta": { "total": 1250, "limit": 10, "offset": 0, "has_more": true } } ``` ## Next steps Set up your API key and understand scopes. Build your first integration in 5 minutes. # Pagination Source: https://leonar.mintlify.app/pagination Navigate through large datasets with offset or incremental cursor pagination. All list endpoints return paginated results using offset-based pagination. This page describes the REST API v1 response contract. MCP list tools use `pagination: { total, limit, offset }` without `has_more`; do not mix the REST and MCP response shapes. ## Parameters | Parameter | Type | Default | Description | | --------- | ------- | ------- | ---------------------- | | `limit` | integer | 50 | Items per page (1-100) | | `offset` | integer | 0 | Items to skip | ## Response format ```json theme={null} { "data": [...], "meta": { "total": 1250, "limit": 50, "offset": 0, "has_more": true } } ``` | Field | Description | | ---------- | ----------------------------------------- | | `total` | Total number of items matching the query | | `limit` | Page size used | | `offset` | Number of items skipped | | `has_more` | Whether more items exist beyond this page | ## Iterating through all results ```python theme={null} import requests BASE_URL = "https://app.leonar.app/api/v1" HEADERS = {"Authorization": "Bearer leo_your_api_key"} def get_all_contacts(): contacts = [] offset = 0 limit = 100 while True: response = requests.get( f"{BASE_URL}/contacts", headers=HEADERS, params={"limit": limit, "offset": offset}, ) result = response.json() contacts.extend(result["data"]) if not result["meta"]["has_more"]: break offset += limit return contacts ``` ## Filtering and sorting Most list endpoints support filtering and sorting via query parameters. Filters use operator-based syntax: | Operator | Example | Description | | --------------- | ----------------------------- | ---------------------- | | `eq.value` | `?global_status=eq.new` | Equals | | `neq.value` | `?global_status=neq.archived` | Not equals | | `gt.value` | `?created_at=gt.2026-01-01` | Greater than | | `gte.value` | `?created_at=gte.2026-01-01` | Greater than or equal | | `lt.value` | `?amount=lt.50000` | Less than | | `lte.value` | `?amount=lte.50000` | Less than or equal | | `like.%value%` | `?first_name=like.%Sophie%` | Case-sensitive match | | `ilike.%value%` | `?first_name=ilike.%sophie%` | Case-insensitive match | | `is.null` | `?archived_at=is.null` | Is null | | `is.not_null` | `?archived_at=is.not_null` | Is not null | Sorting uses a `sort` parameter with `-` prefix for descending order: ``` ?sort=-created_at # Newest first ?sort=last_name # Alphabetical ``` ## Incremental synchronization Mutable CRM collections support `updated_after` and, except for contacts, `updated_before`. These offset-paginated filters reduce full scans but are best-effort during concurrent writes; consumers that require an exact mirror should keep a lower-frequency reconciliation. Timestamps must be RFC 3339 values. The lower bound is strict and the upper bound is inclusive: ```text theme={null} updated_at > updated_after AND updated_at <= updated_before ``` The contacts collection may redeliver rows exactly equal to `updated_after`. This at-least-once behavior avoids gaps; consumers should upsert by resource ID. The workspace-level pipeline entry collection provides the stronger contract: keyset cursor pagination and a fixed checkpoint obtained from the database clock. ```http theme={null} GET /api/v1/pipeline-entries ?updated_after=2026-07-22T08:00:00Z &include=contact,project,stage &limit=100 ``` Follow `meta.next_cursor` until `meta.has_more` is false. Persist `meta.checkpoint` only after the final page succeeds, then use it as the next request's `updated_after`. Process entries idempotently by ID. ```json theme={null} { "data": [], "meta": { "limit": 100, "has_more": false, "next_cursor": null, "checkpoint": "2026-07-22T08:05:00.000Z" } } ``` Pipeline entry deletions are not yet emitted by this endpoint. Keep a lower-frequency full reconciliation for deletion detection. # Rate limiting Source: https://leonar.mintlify.app/rate-limiting Understand API rate limits and how to handle them. The Leonar API enforces rate limits to ensure fair usage and platform stability. ## Limits | Metric | Limit | | ----------------- | ----------------- | | Requests per hour | 2,000 per API key | ## Response headers Every API response includes rate limit headers: | Header | Description | | ----------------------- | ---------------------------------------- | | `X-RateLimit-Limit` | Maximum requests allowed per hour | | `X-RateLimit-Remaining` | Remaining requests in the current window | | `X-RateLimit-Reset` | Unix timestamp when the limit resets | ## Handling rate limits When you exceed the limit, the API returns a `429` status code: ```json theme={null} { "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded. Limit: 2000 requests per hour." } } ``` **Best practices:** 1. Check `X-RateLimit-Remaining` before making requests 2. Use exponential backoff when you receive a `429` 3. Cache responses when possible to reduce API calls 4. Use bulk endpoints (e.g., sequence enrollment accepts multiple contact IDs) ```python theme={null} import time import requests def api_request_with_retry(url, headers, max_retries=3): for attempt in range(max_retries): response = requests.get(url, headers=headers) if response.status_code == 429: reset_time = int(response.headers.get("X-RateLimit-Reset", 0)) wait = max(reset_time - time.time(), 2 ** attempt) time.sleep(wait) continue return response raise Exception("Rate limit exceeded after retries") ```