Workflow Recipes

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.

1. Get the project stages

   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.

   curl -X GET "https://app.leonar.app/api/v1/projects/project-uuid" \
     -H "Authorization: Bearer leo_your_api_key"
   

   Response excerpt:

   {
     "data": {
       "id": "project-uuid",
       "name": "Senior Frontend Engineers",
       "pipeline": {
         "stages": [
           {
             "id": "sourced-stage-uuid",
             "name": "Sourced",
             "position": 0,
             "system_category": "sourced",
             "entries_count": 12
           }
         ]
       }
     }
   }
   
2. List only entries in a given stage

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

   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"
   
3. Create or update the contact

   If the lead is new, create a contact first:

   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:

   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"
     }'
   
4. Add the contact to the project

   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.

   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"
       }
     }'
   
5. Move an existing project lead to another stage

   Use the pipeline entry ID from GET /projects/{id}/entries, then pass the target stage UUID.

   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

1. Trigger enrichment

   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:

   {
     "data": {
       "request_id": "enrich-request-uuid",
       "type": "work_email",
       "status": "pending"
     }
   }
   
2. Poll until completed

   Enrichment is asynchronous. Poll every 5 seconds:

   curl -X GET "https://app.leonar.app/api/v1/enrichment/enrich-request-uuid" \
     -H "Authorization: Bearer leo_your_api_key"
   

   Response when completed:

   {
     "data": {
       "id": "enrich-request-uuid",
       "contact_id": "contact-uuid",
       "enrichment_type": "work_email",
       "status": "completed",
       "result": {
         "email": "[e-mail]",
         "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

1. List available sequences

   curl -X GET "https://app.leonar.app/api/v1/sequences?status=active&limit=10" \
     -H "Authorization: Bearer leo_your_api_key"
   
2. Enroll contacts (simple format)

   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"
       ]
     }'
   
3. Or enroll with custom variables

   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:

   Hi {{first_name}}, I thought the {{custom_variable_1}} role could be a fit because of {{custom_variable_2}}.
   

   Example enrollment payload:

   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:

   Hi Ada, I thought the Senior Frontend Engineer role could be a fit because of your React component library work.
   

   Response:

   {
     "data": {
       "enrolled": 1,
       "skipped_blacklisted": 0,
       "skipped_already_enrolled": 0,
       "skipped_active_elsewhere": 0,
       "skipped_not_found": 0
     }
   }
   

---

Create and manage a deal

1. Get pipeline stages

   curl -X GET "https://app.leonar.app/api/v1/deal-pipelines" \
     -H "Authorization: Bearer leo_your_api_key"
   
2. Create a deal

   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"
     }'
   
3. Link a contact to the deal

   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"}'
   
4. Move deal through stages

   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"}'
   
5. Close the deal

   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

1. Create a tag

   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"}'
   
2. Search contacts

   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
     }'
   
3. Tag matching contacts

   For each matching contact:

   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

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:

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": "[phone]"
  }'