LeadVault API

Send leads to LeadVault from any system, and read and work them from your own.

Keys

An account admin makes keys in LeadVault, under API keys. There are two kinds:

• Posting key (lv_post_…): belongs to one lead source, like a vendor or your website, and can only add leads to it, and answer the returns of the leads it sold. It can't read leads. Give each vendor their own, and revoke one to stop that vendor alone.
• Full key (lv_full_…): for your own systems, like Zapier or reports. It reads and changes every lead in the account, so keep it on your servers.

Send the key in a header with every call. X-Api-Key: lv_… works too, and a vendor whose system can only post form fields may send it as a field named api_key. Never put a key in a URL: LeadVault refuses those calls, because URLs end up in logs.

Authorization: Bearer lv_post_…

Adding a lead

Post JSON to https://leadvault.com/api/v1/leads:

curl https://leadvault.com/api/v1/leads \
  -H "Authorization: Bearer lv_post_…" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "mortgage",
    "first_name": "Ana", "last_name": "Rivera",
    "email": "ana.rivera@example.com", "phone": "(310) 555-0123",
    "state": "CA", "zip": "90025",
    "answers": { "loan_purpose": "refinance", "loan_amount": "$350,000", "credit_rating": "good" },
    "consent": { "text": "By clicking Get my quote, I agree…", "checked": true,
                 "at": "2026-10-29T14:05:00Z", "certificate_id": "https://cert.trustedform.com/…" },
    "ip": "203.0.113.7", "page_url": "https://example.com/refinance", "utm_source": "google"
  }'

Or send the same names as a plain form post, the way many lead systems do:

curl https://leadvault.com/api/v1/leads \
  -d api_key=lv_post_… -d type=mortgage -d first_name=Ana -d phone=3105550123 \
  -d loan_purpose=refinance -d loan_amount=350000 \
  -d consent_text="By clicking…" -d consent_checked=yes \
  -d trustedform_cert_url=https://cert.trustedform.com/…

• type: the lead type, like mortgage, debt or insurance. Needed when the account has more than one.
• Contact details: first_name, last_name, email, phone, phone_2, address, city, state, zip, best_time_to_call. A phone or an email is needed. Any 10-digit US phone format is fine, and a number from another country starts with + and its country code (+52 55 1234 5678); states as two letters or the full name. A whole name in one field can come as full_name (or name): "Ana Maria Rivera" becomes Ana Maria, Rivera.
• answers: by the lead type's field keys, which GET /lead-types lists (a posting key may call it). They may be at the top level too. "$350,000", "350k", yes or no, a choice's label or value, and dates as 2026-06-15 or 6/15/2026 all work.
• consent: the wording the consumer saw (text), checked, at, and a TrustedForm or Jornaya certificate_id. On a form post: consent_text, consent_checked, consent_at, trustedform_cert_url. It's kept with the lead and can't be changed.
• ip, user_agent, page_url: the consumer's, from the form. Campaign tags: utm_source, utm_medium, utm_campaign, utm_term, utm_content.
• reference_id: your own ID for the lead, kept with it, so you can find it again with GET /leads?reference_id=. submitted_at: when the person filled in your form, if that was before you sent it.
• With a full key only: source (by name), assigned_to (an email or user id) and stage (by name or id) to start in. Without assigned_to, the account's lead distribution rules give the lead to someone (or leave it unassigned).

The answer, with status 201:

{ "id": 612345, "status": "active", "consent": "recorded" }

status is active, duplicate (the same phone or email asked for the same type recently) or do_not_contact (on the account's do-not-contact list). Either way the lead is kept and marked. ignored lists any names LeadVault didn't use, so you can fix your mapping. A lead with a problem isn't added: the answer names each field and what's wrong.

Errors

Every answer is JSON, errors too:

{
  "error": {
    "code": "invalid",
    "message": "Some of what was sent can't be used; see fields.",
    "fields": {
      "phone": "Send a 10-digit US phone number, or another country's number starting with + and its country code.",
      "answers.loan_amount": "Send a number, like 350000."
    }
  }
}

Limits

• 120 calls a minute for each key.
• 64 KB a call.
• After 20 calls with a wrong key in 10 minutes, the address they came from waits 10 minutes.

Webhooks

LeadVault can post to your systems when something happens, instead of them asking. An account admin adds a webhook in LeadVault under API, Webhooks: an https address (a Zapier “Catch Hook” address works) and what to send: new leads, stage changes, appointments booked, appointments cancelled, or any mix. Within seconds of the change, LeadVault posts JSON like this:

{
  "id": 81234,
  "event": "lead.stage_changed",
  "created_at": "2026-10-29T15:04:05Z",
  "account": "Acme Mortgage",
  "lead": { "id": 612345, "type": "mortgage", "first_name": "Ana", … },
  "stage_change": { "from": { "id": 11, "name": "New" }, "to": { "id": 12, "name": "Contacted" } }
}

• event is lead.created (every new lead except those on the do-not-contact list), lead.stage_changed, appointment.booked, appointment.cancelled, or ping from the Send test button, which has no lead.
• An appointment post also has appointment, as GET /leads/{id}/appointments shows it. It's sent however the appointment was booked or cancelled: in LeadVault, by the lead on a booking link, or through the API. Moving a booking cancels the old appointment and books a new one, so it sends both.
• lead is the lead as GET /leads/{id} shows it, without the consent record, as it is when the post goes out.
• Headers: LeadVault-Event, LeadVault-Delivery (the same on every try, so a repeat can be spotted) and LeadVault-Signature.
• Answer with any 2xx within 10 seconds. Otherwise LeadVault tries again after 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours and 24 hours. Redirects aren't followed. After 20 posts in a row fail, the webhook is turned off and the Webhooks page says why.
• The address has to be https on the usual port, on the internet.

To know a post came from LeadVault, check its signature. LeadVault-Signature is t=<unix time>,v1=<hex>, where v1 is the HMAC-SHA256 of the time, a dot and the raw body, keyed with the webhook's secret (whsec_…, shown once when the webhook is added). In Node:

const crypto = require('crypto');

// rawBody: the body exactly as it arrived, before parsing it.
function fromLeadVault(rawBody, signature, secret) {
  const { t, v1 } = Object.fromEntries(signature.split(',').map(p => p.split('=')));
  const want = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return v1?.length === want.length &&
         crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(want)) &&
         Math.abs(Date.now() / 1000 - Number(t)) < 300; // and not an old post sent again
}

Returns

For lead vendors. An account gives back a lead it bought from you, with a reason, while you take bad leads back. Its returns reach you the way it sets up for you: a spreadsheet it sends, a daily email with the spreadsheet, your LeadByte, or your own system. For your own system, LeadVault posts each return to the address you give the account, as it's made:

{
  "event": "lead.returned",
  "account": "Acme Mortgage",
  "return": {
    "id": 5521, "lead_id": 612345, "your_lead_id": "LT-88231", "source": "Your company",
    "first_name": "Ana", "last_name": "Rivera", "phone": "+13105550123", "email": "ana.rivera@example.com",
    "received_at": "2026-11-02T16:20:00Z", "cost": 40,
    "reason": "wrong_number", "reason_text": "Wrong or disconnected number", "note": "Number not in service",
    "returned_at": "2026-11-03T15:02:11Z", "status": "requested"
  },
  "answer_url": "https://leadvault.com/api/v1/returns/5521"
}

• your_lead_id is the reference_id you sent with the lead. reason is duplicate, wrong_number, fake, did_not_ask, out_of_area or other (with a note saying why).
• Headers: LeadVault-Event (lead.returned), LeadVault-Return (the return's id, the same on every try) and LeadVault-Signature, signed with the secret the account gives you (rtsec_…), checked as for webhooks.
• Answer with any 2xx within 10 seconds. Otherwise LeadVault tries again after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours, then the account sends it another way.
• To settle it at once, answer with {"status": "credited", "credit": 25, "note": "…"} (credit only when less than the cost) or {"status": "refused", "note": "…"}. Anything else just means it arrived.

To answer later, or however the return reached you, use the posting key the account gave you for your leads. GET /returns lists the ones waiting on you, and POST /returns/{id} answers one:

curl https://leadvault.com/api/v1/returns/5521 \
  -H "Authorization: Bearer lv_post_…" \
  -H "Content-Type: application/json" \
  -d '{ "status": "refused", "note": "We reached them on 11/2. Valid lead." }'

A refused lead goes back on the account's lists, and your note shows with it. A return is settled once: answering again changes nothing.

Postman and other tools

The OpenAPI file is at https://leadvault.com/api/v1/openapi.json. In Postman, choose Import, paste that link, then set the collection's authorization to Bearer token with your key. Insomnia, Swagger Editor and most other API tools take the same link.

All calls

Paths are under https://leadvault.com/api/v1.

{
  "phone": "310-555-0199",
  "answers": {
    "loan_amount": 400000
  },
  "source": "Live chat",
  "stage": "Contacted",
  "assigned_to": "joe@example.com"
}

{
  "stage": "Contacted"
}

{
  "user": "marcus@example.com"
}

{
  "kind": "call",
  "outcome": "voicemail",
  "text": "Asked them to call back after 5."
}

{
  "due_at": "2026-10-30T14:00:00-07:00",
  "note": "Wants rates after 2pm"
}

{
  "starts_at": "2026-10-30T14:00:00-07:00",
  "minutes": 30,
  "how": "video",
  "place": "https://meet.example.com/ana",
  "note": "Go over the rate quote"
}

{
  "status": "refused",
  "note": "We reached them on 11/2. Valid lead."
}