Quickstart

From zero to your first scored lead in five minutes: create an account, get an API key, describe what a good lead is, and send a message.

1. Create an account

Signing up creates your user, an account and its first workspace, and returns a session token.

curl -X POST https://core.leadveyor.com/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@company.com",
    "password": "a-long-password",
    "accountName": "Acme Renovations"
  }'

Response

{
  "user": { "object": "user", "id": "usr_3fK9aQ2LmZp8VxR1cT0bYw7e", "email": "you@company.com" },
  "account": { "object": "account", "id": "acc_8Hc2Qe5VnLx0TzJ4uM1rWk6a", "name": "Acme Renovations" },
  "workspace": { "object": "workspace", "id": "ws_1Bq7Xn4KpRz9Lc2Vt6Hy0Mde", "name": "Acme Renovations" },
  "session": { "object": "session", "token": "lvs_…", "expiresAt": "2026-12-02T09:30:00.000Z" }
}

2. Create an API key

Use the session token once to create an API key for the workspace. The key is shown only in this response — store it in your secrets.

curl -X POST https://core.leadveyor.com/v1/api-keys \
  -H "Authorization: Bearer lvs_…" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production", "permission": "admin", "workspaceId": "ws_1Bq7Xn4KpRz9Lc2Vt6Hy0Mde" }'

Response

{ "object": "api_key", "id": "key_5Tn8Wq2Lx7Kd4Rz1Vc9Hm3Pb", "secret": "lv_live_…", "permission": "admin" }

From here on, every request uses Authorization: Bearer lv_live_…. See Authentication for test keys and permissions.

3. Describe a good lead

A profile says which fields to extract and how to score. This one is for a renovation company: big budgets, big projects and owners who want to start soon score high; commercial jobs are disqualified.

curl -X POST "https://core.leadveyor.com/v1/profiles?publish=true" \
  -H "Authorization: Bearer lv_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Home renovation",
    "brief": "Residential renovation company. Best customers are home owners with a budget from $15,000 who want to start within three months.",
    "extract": [
      { "key": "budget", "type": "money", "description": "Project budget" },
      { "key": "start_date", "type": "date", "description": "When work should start" },
      { "key": "property_type", "type": "enum", "values": ["house", "apartment", "commercial"] }
    ],
    "criteria": [
      { "id": "budget_15k", "type": "rule", "label": "Budget from $15k",
        "condition": { "field": "fields.budget", "op": "gte", "value": 15000 }, "points": 40 },
      { "id": "start_soon", "type": "rule", "label": "Starts within 3 months",
        "condition": { "field": "fields.start_date", "op": "within", "value": "P90D" }, "points": 30 },
      { "id": "owner", "type": "ai", "label": "Home owner",
        "question": "Is the customer the owner of the property?", "points": 30 },
      { "id": "commercial", "type": "disqualify", "label": "Commercial property",
        "condition": { "field": "fields.property_type", "op": "eq", "value": "commercial" },
        "reason": "We do not take commercial projects" }
    ],
    "tiers": [ { "name": "hot", "minScore": 70 }, { "name": "warm", "minScore": 40 }, { "name": "cold", "minScore": 0 } ]
  }'

The first published profile becomes the workspace default.

4. Send a message

Send any text — here, an email body. wait=true holds the request until processing finishes (usually 5–10 seconds) and returns the leads.

curl -X POST "https://core.leadveyor.com/v1/inbounds?wait=true" \
  -H "Authorization: Bearer lv_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": {
      "from": "Anna Smith <anna@example.com>",
      "subject": "Kitchen renovation quote",
      "text": "Hi, I would like a quote to renovate my kitchen in Brooklyn. Budget around $25,000, we would like to start in March. I own the house. Anna, 555-123-4567"
    }
  }'

Response (shortened)

{
  "object": "inbound",
  "id": "inb_9Qe3Wn7Kd2Lp5Xr8Vt1Mz4Bh",
  "status": "processed",
  "classification": "lead",
  "leads": [
    {
      "object": "lead",
      "id": "lead_2Ph6Tc9Ks4Wm1Lx7Qv3Nb8Dr",
      "contact": { "name": "Anna Smith", "emails": ["anna@example.com"], "phones": ["555-123-4567"] },
      "request": { "summary": "Customer wants a quote to renovate their kitchen in Brooklyn, budget around $25,000, starting in March." },
      "fields": {
        "budget": { "amount": 25000, "currency": "USD" },
        "start_date": { "value": "2027-03-01", "min": "2027-03-01", "max": "2027-03-31", "asWritten": "March" },
        "property_type": "house"
      },
      "evaluation": {
        "score": 100,
        "tier": "hot",
        "criteria": [
          { "id": "budget_15k", "result": "met", "points": 40 },
          { "id": "start_soon", "result": "met", "points": 30 },
          { "id": "owner", "result": "met", "points": 30, "evidence": "I own the house" }
        ]
      }
    }
  ]
}

What's next?

Was this page helpful?