# 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")
```