LovelioDocs
Sign in
Last updated 22 July 2026

Top 10 tasks

The ten things an agency consultant's agent does 95% of the time, with minimal runnable examples. Every example assumes you have set:

export LOVELIO_API_KEY=sk_trial_...
export LOVELIO_HOST=https://www.lovelio.ai

A note on two headers you will use throughout:

  • Authorization: Bearer $LOVELIO_API_KEY on every request.
  • Idempotency-Key on every POST that writes a record. Send a fresh UUID per logical action ($(uuidgen)); retrying with the same key returns the first result instead of creating a duplicate. The API rejects a write POST with no key.

IDs are typed and prefixed: cli_ client, cct_ client contact, job_ job, jad_ job ad, cnd_ candidate, app_ application, sub_ submission, ivw_ interview, pla_ placement, tsk_ task, whk_ webhook. Pass them back exactly as you received them.

1. Create a client

Every job belongs to a client, so the client comes first. Give a name, or just a website and Lovelio enriches the rest (and starts the Client DNA first pass).

curl -X POST $LOVELIO_HOST/api/v1/clients \
  -H "Authorization: Bearer $LOVELIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Northwind Payments",
    "website": "https://northwind.example",
    "industry": "Fintech"
  }'

Returns HTTP 201 with the client:

{
  "success": true,
  "data": { "id": "cli_...", "name": "Northwind Payments", "enrichment_status": "pending", "dna_status": "pending" },
  "meta": { "request_id": "req_..." }
}

Already have the client? Find it by name with GET /api/v1/clients?search=northwind.

2. Create a job for that client

A job cannot exist without a client. Pass the cli_ id from step 1 (for the agency's own internal hiring, pass the agency self-client's id). The job is created immediately and an async task fills in the spec, assessment criteria, and interview plan.

curl -X POST $LOVELIO_HOST/api/v1/jobs \
  -H "Authorization: Bearer $LOVELIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "title": "Senior Backend Engineer",
    "client_id": "cli_...",
    "location": { "type": "remote", "country": "United Kingdom" },
    "employment_type": "full_time",
    "compensation": { "base_min": 120000, "base_max": 140000, "currency": "GBP" }
  }'

Response (HTTP 202 with a task_id):

{
  "success": true,
  "data": { "task_id": "tsk_...", "job_id": "job_...", "poll_url": "/api/v1/tasks/tsk_..." },
  "meta": { "request_id": "req_..." }
}

The job_id is live immediately. Poll GET /api/v1/tasks/{task_id} to know when the AI spec is ready, or subscribe to job.created webhooks.

Prefer natural language? POST /api/v1/jobs/from-description takes a plain-English brief (and an optional client_id) and streams a draft back over Server-Sent Events; you then confirm it with POST /api/v1/jobs/from-description/{review_token}/confirm. The structured POST /api/v1/jobs above is the simpler door for an agent.

3. Add a candidate and log their application

Candidates belong to the agency, not the client. Create the candidate, then attach them to the job as an application.

# a) create the candidate
curl -X POST $LOVELIO_HOST/api/v1/candidates \
  -H "Authorization: Bearer $LOVELIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Priya Nair",
    "email": "priya@example.com",
    "resume_url": "https://example.com/priya-cv.pdf",
    "skills": ["Go", "Rust", "payments"]
  }'
# -> { "data": { "id": "cnd_...", ... } }

# b) log their application to the job
curl -X POST $LOVELIO_HOST/api/v1/applications \
  -H "Authorization: Bearer $LOVELIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "candidate_id": "cnd_...", "job_id": "job_..." }'

The application returns HTTP 202 with an app_ id and an assessment task_id. On arrival Lovelio runs automatically, no human action required:

  • CV text extraction (PDF/DOCX) and a structured parse via Claude Haiku.
  • An assessment against the job's criteria.
  • A suggested triage stage.

Applications also arrive on their own via the careers page and embed widget. Subscribe to application.received and application.scored webhooks to observe either path.

4. Review the pipeline

List applications for a job. Filter by stage to pull just the ones you care about.

curl "$LOVELIO_HOST/api/v1/applications?job_id=job_...&stage=yes&limit=20" \
  -H "Authorization: Bearer $LOVELIO_API_KEY"

Each row carries the candidate's contact details, parsed profile, and the AI assessment (with job_fit_score and per-criterion scores). Sort by assessment.job_fit_score descending to triage fast.

The stages are the agency pipeline: maybe (awaiting triage, where new applications land), yes (shortlisted), no (parked), submitted (sent to the client), client_interview, offer, then the terminal placed, rejected, withdrew. Omit stage to see everything.

5. Move a candidate to a new stage

curl -X POST $LOVELIO_HOST/api/v1/applications/app_.../stage \
  -H "Authorization: Bearer $LOVELIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "stage": "yes", "source": "api" }'

stage must be one of the canonical stages listed above. source must be one of slack, whatsapp, web, api. Response echoes the new state:

{
  "success": true,
  "data": { "application": { "id": "app_...", "stage": "yes", "stage_changed_at": "2026-07-21T09:30:00Z" } }
}

Most stage moves happen on their own: sending a submission moves candidates to submitted, booking a client interview moves them to client_interview, logging an offer moves them to offer, and recording a placement moves them to placed. Use this endpoint for the manual moves (shortlisting, parking, rejecting). Add an override_reason if you are forcing a non-standard jump.

6. Submit a shortlist to the client

The core agency move: send a shortlist of candidates to the client contact as a tokenised review link. This drafts a per-candidate summary (edit summary to override), emails the contact, and moves each candidate to submitted.

curl -X POST $LOVELIO_HOST/api/v1/submissions \
  -H "Authorization: Bearer $LOVELIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "job_id": "job_...",
    "client_contact_id": "cct_...",
    "title": "Three for the Backend Engineer role",
    "items": [
      { "application_id": "app_...", "summary": "Led the payments rewrite at Northwind." },
      { "application_id": "app_..." }
    ]
  }'

Returns HTTP 201 with the sub_ id, an email_sent flag, and a client-facing url. Anyone with that link can request an interview, pass with a reason, or ask a question; each response updates the pipeline and notifies you. Track responses with GET /api/v1/submissions?job_id=job_....

7. Schedule a client interview

When the client asks to meet a candidate, book it. Set flavour: "client" so the application moves to client_interview automatically; leave it internal for your own screens.

curl -X POST $LOVELIO_HOST/api/v1/interviews \
  -H "Authorization: Bearer $LOVELIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "application_id": "app_...",
    "flavour": "client",
    "format": "video",
    "scheduled_at": "2026-08-03T14:00:00Z",
    "duration_minutes": 45,
    "interviewer_ids": ["usr_..."],
    "submission_id": "sub_..."
  }'

Returns HTTP 201 with the ivw_ id. Video interviews get a Lovelio call room and the invitation email fires when a scheduled_at is set. After the interview, drop feedback with POST /api/v1/interviews/{id}/scorecard (body: recommendation one of strong_hire/hire/no_hire/strong_no_hire, plus optional scores and notes).

8. Log an offer

Offers are the client's to make and sign in the agency model, so there is no offer-letter endpoint. log_offer is a lightweight marker that records the client made an offer and moves the application to the offer stage. It has no dedicated route, so run it through the batch endpoint (no top-level idempotency header; each op carries its own key):

curl -X POST $LOVELIO_HOST/api/v1/batch \
  -H "Authorization: Bearer $LOVELIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {
        "op": "log_offer",
        "idempotency_key": "'"$(uuidgen)"'",
        "payload": { "application_id": "app_...", "offered_salary": 135000, "offered_currency": "GBP" }
      }
    ]
  }'

Returns HTTP 200 with a per-op status array. When the offer is accepted, record it as a placement (next).

9. Record the placement (the win)

The placement is the record of the win: candidate, client, job, salary, fee, start date, and the guarantee. Creating one against an application moves it to placed. The fee percent and guarantee default off the client's standard terms when you omit them.

curl -X POST $LOVELIO_HOST/api/v1/placements \
  -H "Authorization: Bearer $LOVELIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "application_id": "app_...",
    "salary": 135000,
    "currency": "GBP",
    "fee_type": "percent",
    "fee_percent": 20,
    "start_date": "2026-09-01"
  }'

Returns HTTP 201 with the pla_ id and the computed fee.amount. If you do not have an application to anchor to, pass candidate_id + client_id instead. Review the trophy cabinet with GET /api/v1/placements.

10. Pull the numbers

Three read-only analytics endpoints, no charts, just numbers an agent can forward to Slack or paste into a summary.

# Headline KPIs over a window (default 30 days)
curl "$LOVELIO_HOST/api/v1/analytics/metrics?days=7" \
  -H "Authorization: Bearer $LOVELIO_API_KEY"

metrics returns applications_received, placements_made, interviews_conducted, offers_extended, offer_acceptance_rate, interview_to_hire_ratio, and a source_breakdown. For the funnel with stage-by-stage conversion use GET /api/v1/analytics/pipeline (optionally ?job_id=job_...); for a live snapshot of active jobs, upcoming interviews, and recent placements use GET /api/v1/analytics/dashboard.

Hand this to Claude

Paste into a Claude session with Lovelio MCP or the API key in env:

Create a client called Northwind Payments (website northwind.example),
then create a Senior Backend Engineer job for them: remote in the UK,
GBP 120-140k. Add candidate Priya Nair (priya@example.com) and log her
application. Once her assessment is back, shortlist her, and if she
scores well, submit her plus the top two others to the client contact
as a shortlist. Post a summary to Slack when done.