Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.auditynow.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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 Growth-tier 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:
FieldWhere you see itValues
surveyStatus (on each lead)Per-row statepending, completed, converted, archived
?status= query paramThe GET /api/lead-generation/leads filteractive (= 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. POST /api/projects/{auditId}/audit-analysis, kicks off synthesis, synchronous, blocks 60–300 seconds. Tell the agent to set its HTTP timeout high (360s+).
  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 (sequential, not parallel, write rate limit is 30/min, audit triggers are 5/min)
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. If you want leads from one specific ReadyLink, pass staticSlugId={uuid} in the query. You need to know the slug ID up front, listing ReadyLinks isn’t exposed in v1. 
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.

​
Edge cases

POST .../convert returns 400 (not 409) on a re-conversion attempt. The agent should check surveyStatus first and skip rather than retry.
POST .../convert returns 402 with an error body when you’re out of credits. Always check GET /api/user/credits before a batch.
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 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