Sonny API

REST API overview

Sonny exposes a single REST surface for the full agency workflow: sourcing, screening, CV reformat, outreach, headhunt, pipeline, and placement billing. One Bearer key, one rate budget, one audit log.

What you can do

  • SourceFind 10-100 candidates from a role brief, LLM scored.
  • ScreenDeep-screen a CV (URL, JSON, or file upload) against a JD.
  • ReformatStandardise or anonymise a CV with redaction reporting.
  • OutreachSend consent-first SMS + email sequences with reply tracking.
  • HeadhuntVoice-agent calls after explicit candidate consent (Pro+).
  • Pipeline + PlaceManage candidates and report placements for billing.

Authentication

Every request uses a Bearer key issued at signup:

Authorization: Bearer sk_live_…

Keys are SHA-256 hashed at rest. Free tier issues an sk_live_ key on signup; Pro+ keys carry the same prefix. Rotate or revoke from the dashboard at any time.

Endpoints

Full request / response schemas, error codes, idempotency rules, and rate limits live in the signed-in reference.

MethodPathPurpose
POST/api/v1/sonny/sourceSource candidates from a role brief.
POST/api/v1/sonny/screenDeep-screen one candidate against a role.
POST/api/v1/sonny/screen-attachmentScore a CV file (PDF/DOCX/DOC/TXT).
POST/api/v1/sonny/cv-reformatStandardise or anonymise a CV.
POST/api/v1/sonny/placeReport a placement and trigger billing.
GET/api/v1/sonny/candidatesList your pipeline.
POST/api/v1/sonny/candidatesAdd a candidate to the pipeline.
POST/api/v1/sonny/headhuntConsent-first SMS → voice headhunt (Pro+).
POST/api/v1/sonny/outreachSend a candidate outreach email/SMS.
GET/api/v1/sonny/outreach/sendsList sent outreach with reply status.
POST/api/v1/sonny/brain/notesAttach a note to a candidate.
POST/api/v1/sonny/brain/documentsUpload a brain document.
POST/api/v1/sonny/brain/searchSemantic search across your brain.
GET/api/v1/sonny/templatesList your outreach templates.
GET/api/v1/sonny/auditAudit log of API calls + actions.
GET/api/v1/sonny/usageUsage + credit balance + monthly grant.
GET/api/v1/sonny/key-infoInspect your key — tier, features, limits.

One example — score a candidate

The full set of curl examples, SDK source, and error catalogue is in the signed-in reference. Here is one call to prove the surface is real:

curl https://9mil.io/api/v1/sonny/screen \
  -H "Authorization: Bearer $SONNY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "candidate": { "full_name": "…", "linkedin_url": "…" },
    "role":      { "role_title": "Senior Backend Engineer" }
  }'

Returns a structured screening report — fit_score 0–100, summary, tenure_pattern, key_strengths, potential_concerns, fit_rationale.

Top-ups & auto top-up

Out of credits before the monthly grant resets? Two ways to refill:

  • ▸ Credit top-ups — buy 80 / 230 / 500 / 1,400 credits ($20 / $50 / $100 / $250). Credits never expire. Bigger packs get a better per-credit rate.
  • ▸ Voice minute top-ups — separate currency for Vapi calls (35 / 100 / 225 / 625 min at the same price tiers). Used before credits on each call, so a pack stretches further than burning credits at 6/min.
  • ▸ Auto top-up— opt-in: pick a pack and a monthly safety ceiling, and Sonny auto-charges your saved card when your balance dips below your threshold. Ceiling caps total monthly auto-spend so a runaway loop can’t drain you.

All three live in the Billing tab of your workspace dashboard.

Next steps