Lead Conversion Playbook

Triage ReadyLink leads and convert the best ones into full audits, from your AI assistant.

What a lead is

A lead in Audity is a survey response from a ReadyLink. When a prospect fills out your survey, a row lands in lead_surveys with their answers, optional web research, and a computed aiReadinessScore.

Each lead has:

• Survey responses (industry, size, pain points, etc.)
• Optional web research (webResearchStatus, populated by eligible accounts via the web app)
• Two scores: aiReadinessScore (from the survey logic) and compositeScore (which factors web research in)
• A surveyStatus field, pending, completed, converted, or archived

The agent API exposes lead listing, lead detail, and lead conversion. Lead creation is not exposed, leads are created when a prospect submits your public survey, not via PAT.

The status vocabulary, two of them

There are two related-but-different status fields. This catches people out:

Field	Where you see it	Values
surveyStatus (on each lead)	Per-row state	pending, completed, converted, archived
?status= query param	The GET /api/lead-generation/leads filter	active (= pending + completed + converted), archived, all

When you ask the agent to “list active leads,” it should pass ?status=active, which returns everything that isn’t archived. To find leads that haven’t been converted yet, filter the response client-side for surveyStatus !== 'converted'.

Recipe 1: Triage the inbox

List my Audity leads from the last 14 days that haven't been converted yet.
Sort by AI readiness score, descending. Show me the top 10 with company name,
industry, and a one-line summary of their primary pain point.

What runs:

1. GET /api/lead-generation/leads?status=active&sortBy=ai_readiness_score&sortOrder=desc&limit=50 (response wrapped: { data: [...], pagination, filters })
2. The agent filters client-side for surveyStatus !== 'converted' and createdAt within the last 14 days
3. The agent formats the top 10 from the filtered set

The list endpoint doesn’t take a since parameter, the date filter is client-side.

Recipe 2: Inspect one lead in depth

Pull lead {id} and tell me everything you can about them. What were their
survey answers? What's their composite score? Have they been researched?

What runs:

1. GET /api/lead-generation/leads/{id} returns { lead: LeadDetail } with the full survey response payload and tracking URL metadata
2. The agent reads surveyResponses, aiReadinessScore, compositeScore, webResearchStatus, and any tracking URL data
3. The agent synthesizes a profile

Note: web research is triggered from the web app, not via the agent API in v1. The agent can read whatever research has already been completed.

Recipe 3: Convert and audit in one shot

Convert lead {id} into a full Audity project. Use the survey responses as the
intake context. Then trigger the audit analysis. Tell me the project ID and
when to expect the analysis.

What runs:

1. POST /api/lead-generation/leads/{id}/convert, creates a project, deducts 1,000 credits, marks the lead as converted, dispatches Inngest events. Response: { success: true, data: { auditId, creditsUsed, pdfAttached } }.
2. Trigger audit analysis. Synthesis runs ~10-15 minutes, so avoid the synchronous POST /api/projects/{auditId}/audit-analysis (it blocks the whole time and risks gateway timeouts). Once the converted project has current document and interview analyses, use POST /api/agent/projects/{auditId}/audit-analysis/async, then poll GET /api/agent/jobs/{jobId}.
3. The agent reports auditId and the expected completion time.

Recipe 4: Bulk triage and convert

Get my Audity leads with composite score above 70 that aren't converted yet.
Tell me how many credits the conversions would cost. Wait for my OK before
running anything.

What runs:

1. GET /api/user/credits, show available headroom
2. GET /api/lead-generation/leads?status=active&sortBy=composite_score&sortOrder=desc&limit=50
3. Filter client-side for compositeScore > 70 and surveyStatus !== 'converted'
4. Multiply count × 1,000 credits, surface the math
5. Wait for explicit approval before any POST .../convert calls
6. After approval, loop through and convert sequentially. If the converted projects already have the prerequisite analyses, use the async audit endpoint for batch analysis so the agent can poll jobs instead of keeping long requests open.

The agent should never silently spend 5,000+ credits. Always math-then-confirm for batch operations.

Recipe 5: Stale lead nudge

Show me leads that completed the survey 7+ days ago, scored above 60, and
still haven't been converted. Suggest a nudge approach for the top 3 based
on their survey responses.

This is read-only. The agent assembles the list from GET /api/lead-generation/leads?status=active&sortBy=created_at&sortOrder=desc, filters for surveyStatus === 'completed' (not yet converted), age > 7 days, and score > 60, then composes nudge suggestions client-side. You send the actual outreach yourself.

Filtering by ReadyLink

If you want leads from one specific ReadyLink, pass staticSlugId={uuid} in the query. You can copy a slug ID from the web app or fetch your ReadyLinks through the API reference’s ReadyLinks endpoints.

GET /api/lead-generation/leads?staticSlugId=550e8400-e29b-41d4-a716-446655440000&status=active

Manage and copy slug IDs from the web app’s ReadyLinks dashboard, or use GET /api/agent/readylinks from a PAT-backed agent.

Edge cases

Lead is already converted

POST .../convert returns 400 (not 409) on a re-conversion attempt. The agent should check surveyStatus first and skip rather than retry.

Insufficient credits

POST .../convert returns 402 with an error body when you’re out of credits. Always check GET /api/user/credits before a batch.

Partial batch failure

The convert endpoint isn’t transactional across leads. If you’re converting 5 leads and the third fails, the first two are converted and the last two never started. The agent should report what succeeded vs. what didn’t.

Web research takes a while

Web research happens in the web app, not via the agent API. If the agent surfaces a lead with webResearchStatus: 'pending' or null, that means a human needs to trigger research from the dashboard.

What’s next

• Connect Claude →
• Connect ChatGPT →
• Working with Nucleus →