Leads

A lead is a customer enquiry extracted from a message: who it is, what they want, where, the profile fields and the current evaluation (score, tier and the reason for every criterion). Repeat messages from the same person are merged into their lead.

The Lead object

Properties

  • Name
    object
    Type
    'lead'
    Description

    The object type.

  • Name
    id
    Type
    string
    Description

    Unique identifier, prefixed by the object type.

  • Name
    workspaceId
    Type
    string
    Description

    The workspace this object belongs to.

  • Name
    livemode
    Type
    boolean
    Description

    true for live data, false for data created with a test key.

  • Name
    sourceId
    Type
    string
    Description

    The source the message came through.

  • Name
    inboundIds
    Type
    array of string
    Description

    The messages this lead was built from (the first one and merged repeats).

  • Name
    contactId
    Type
    string or null
    Description

    The person (same email or phone); null without email and phone

  • Name
    contact
    Type
    object
    Description

    Who: name, first and last name, emails, phones, other contact methods, company.

  • Name
    request
    Type
    object
    Description

    What the customer wants: a one-or-two-sentence summary in the workspace language, and the service.

  • Name
    location
    Type
    object
    Description

    Where: address, city, postcode, country; with coordinates, distance (km) and drive time (minutes) from the business when known.

  • Name
    language
    Type
    string or null
    Description

    Language of the message (ISO 639-1).

  • Name
    fields
    Type
    object
    Description

    Values of the profile fields, typed: numbers, { amount, currency } for money, { value, asWritten } for dates; ranges keep min and max.

  • Name
    evaluation
    Type
    Evaluation
    Description

    Current evaluation: score (0–100), tier, confidence, the result and evidence of every criterion, dimensions, and what decided the tier.

  • Name
    outcome
    Type
    Outcome or null
    Description

    What happened to the lead, as reported by you

  • Name
    state
    Type
    'active' | 'archived'
    Description

    active, or archived.

  • Name
    metadata
    Type
    object
    Description

    Your own key-value pairs (strings), e.g. an ID in your CRM.

  • Name
    legacy
    Type
    object or null
    Description

    Original ID and number, for records imported from another system

  • Name
    createdAt
    Type
    string
    Description

    When it was created (ISO 8601).

  • Name
    updatedAt
    Type
    string
    Description

    When it was last changed (ISO 8601).


GET/v1/leads

Scored leads, newest first

Query parameters

  • Name
    limit
    Type
    integer
    Description

    1–100, default 20

  • Name
    starting_after
    Type
    string
    Description

    ID of the last item of the previous page

  • Name
    tier
    Type
    string
    Description

    e.g. hot, critical, disqualified, unscored

  • Name
    min_score
    Type
    number or null
    Description

     

  • Name
    source_id
    Type
    string
    Description

     

  • Name
    state
    Type
    'active' | 'archived'
    Description

    active, or archived.

  • Name
    contact_id
    Type
    string
    Description

     

  • Name
    outcome
    Type
    'won' | 'lost' | 'no_response' | 'disqualified' | 'other' | 'none'
    Description

    none = no outcome yet

  • Name
    legacy_id
    Type
    string
    Description

    Original lead ID, for leads imported from another system (any state)

Request

GET
/v1/leads
curl https://core.leadveyor.com/v1/leads \
  -H "Authorization: Bearer {api_key}" \
  -H "Leadveyor-Workspace: {workspace_id}"  # account-wide keys only

Response 200

{
  "object": "list",
  "data": [
    {
      "object": "lead",
      "id": "lead_u8jzPde0IgxLd6GncfBAepfJ",
      "workspaceId": "ws_Bd0Kh8oOOL8dKLzdocJ2isAj",
      "livemode": true,
      "sourceId": "src_IhKtJ0RlgLKOmxgJTeKdNnFR",
      "inboundIds": [
        "inb_IBXuDL7DxtpYlSXpfKtHF4vU"
      ],
      "contactId": "ctc_CsMehGAkWvj7FAc9QeWJKY40",
      "contact": {
        "name": "Tom Baker",
        "firstName": "Tom",
        "lastName": "Baker",
        "emails": [
          "tom.baker@example.com"
        ],
        "phones": [
          "0412555777"
        ],
        "other": [],
        "company": null
      },
      "request": {
        "summary": "Customer wants a bathroom renovation in their apartment in Queens, with a budget of about $15k, starting next month.",
        "service": "Bathroom renovation"
      },
      "location": {
        "address": null,
        "city": "Queens",
        "postcode": null,
        "country": null
      },
      "language": "en",
      "fields": {
        "budget": {
          "amount": 15000,
          "currency": "USD"
        },
        "start_date": {
          "value": "2026-12-01",
          "min": "2026-12-01",
          "max": "2026-12-31",
          "asWritten": "next month"
        },
        "property_type": "apartment",
        "project_type": "bathroom"
      },
      "evaluation": {
        "confidence": 0.8,
        "criteria": [
          {
            "id": "budget_15k",
            "label": "Budget from $15k",
            "type": "rule",
            "result": "met",
            "grade": null,
            "points": 30,
            "evidence": null,
            "dimension": "what"
          },
          {
            "id": "big_project",
            "label": "Kitchen, full home or extension",
            "type": "rule",
            "result": "not_met",
            "grade": null,
            "points": 0,
            "evidence": null,
            "dimension": "what"
          }
        ],
        "dimensions": [
          {
            "id": "what",
            "label": "What",
            "score": 69,
            "confidence": 1,
            "known": [
              "budget_15k",
              "big_project"
            ],
            "unknown": []
          },
          {
            "id": "when",
            "label": "When",
            "score": null,
            "confidence": 0,
            "known": [],
            "unknown": [
              "start_soon"
            ]
          }
        ],
        "decidedBy": null,
        "score": 60,
        "tier": "warm",
        "id": "eval_uvSwMFLZDe1f8rESQedUStPK",
        "profileId": "prof_R0CsTy4Qwb8DwkNhFdnXsiVp",
        "profileVersion": 1,
        "evaluatedAt": "2026-10-23T15:07:26.371Z"
      },
      "outcome": {
        "status": "won",
        "value": {
          "amount": 14800,
          "currency": "USD"
        },
        "reason": null,
        "occurredAt": "2026-11-02T09:30:00.000Z",
        "recordedAt": "2026-10-23T15:38:00.591Z",
        "recordedBy": {
          "type": "api_key",
          "id": "key_zz63FfkCzJr4i0B3JrTAwR4y"
        }
      },
      "state": "active",
      "metadata": {},
      "legacy": null,
      "createdAt": "2026-10-23T15:07:26.371Z",
      "updatedAt": "2026-10-23T15:38:00.591Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET/v1/leads/{id}

One lead with its current evaluation

Path parameters

  • Name
    id
    Type
    string
    Description

    Unique identifier, prefixed by the object type.

Request

GET
/v1/leads/{id}
curl https://core.leadveyor.com/v1/leads/lead_2Ph6Tc9Ks4Wm1Lx7Qv3Nb8Dr \
  -H "Authorization: Bearer {api_key}" \
  -H "Leadveyor-Workspace: {workspace_id}"  # account-wide keys only

Response 200

{
  "object": "lead",
  "id": "lead_u8jzPde0IgxLd6GncfBAepfJ",
  "workspaceId": "ws_Bd0Kh8oOOL8dKLzdocJ2isAj",
  "livemode": true,
  "sourceId": "src_IhKtJ0RlgLKOmxgJTeKdNnFR",
  "inboundIds": [
    "inb_IBXuDL7DxtpYlSXpfKtHF4vU"
  ],
  "contactId": "ctc_CsMehGAkWvj7FAc9QeWJKY40",
  "contact": {
    "name": "Tom Baker",
    "firstName": "Tom",
    "lastName": "Baker",
    "emails": [
      "tom.baker@example.com"
    ],
    "phones": [
      "0412555777"
    ],
    "other": [],
    "company": null
  },
  "request": {
    "summary": "Customer wants a bathroom renovation in their apartment in Queens, with a budget of about $15k, starting next month.",
    "service": "Bathroom renovation"
  },
  "location": {
    "address": null,
    "city": "Queens",
    "postcode": null,
    "country": null
  },
  "language": "en",
  "fields": {
    "budget": {
      "amount": 15000,
      "currency": "USD"
    },
    "start_date": {
      "value": "2026-12-01",
      "min": "2026-12-01",
      "max": "2026-12-31",
      "asWritten": "next month"
    },
    "property_type": "apartment",
    "project_type": "bathroom"
  },
  "evaluation": {
    "confidence": 0.8,
    "criteria": [
      {
        "id": "budget_15k",
        "label": "Budget from $15k",
        "type": "rule",
        "result": "met",
        "grade": null,
        "points": 30,
        "evidence": null,
        "dimension": "what"
      },
      {
        "id": "big_project",
        "label": "Kitchen, full home or extension",
        "type": "rule",
        "result": "not_met",
        "grade": null,
        "points": 0,
        "evidence": null,
        "dimension": "what"
      }
    ],
    "dimensions": [
      {
        "id": "what",
        "label": "What",
        "score": 69,
        "confidence": 1,
        "known": [
          "budget_15k",
          "big_project"
        ],
        "unknown": []
      },
      {
        "id": "when",
        "label": "When",
        "score": null,
        "confidence": 0,
        "known": [],
        "unknown": [
          "start_soon"
        ]
      }
    ],
    "decidedBy": null,
    "score": 60,
    "tier": "warm",
    "id": "eval_uvSwMFLZDe1f8rESQedUStPK",
    "profileId": "prof_R0CsTy4Qwb8DwkNhFdnXsiVp",
    "profileVersion": 1,
    "evaluatedAt": "2026-10-23T15:07:26.371Z"
  },
  "outcome": {
    "status": "won",
    "value": {
      "amount": 14800,
      "currency": "USD"
    },
    "reason": null,
    "occurredAt": "2026-11-02T09:30:00.000Z",
    "recordedAt": "2026-10-23T15:38:00.591Z",
    "recordedBy": {
      "type": "api_key",
      "id": "key_zz63FfkCzJr4i0B3JrTAwR4y"
    }
  },
  "state": "active",
  "metadata": {},
  "legacy": null,
  "createdAt": "2026-10-23T15:07:26.371Z",
  "updatedAt": "2026-10-23T15:38:00.591Z"
}

GET/v1/leads/{id}/evaluations

Evaluation history of a lead, newest first

Path parameters

  • Name
    id
    Type
    string
    Description

    Unique identifier, prefixed by the object type.

Query parameters

  • Name
    limit
    Type
    integer
    Description

    1–100, default 20

  • Name
    starting_after
    Type
    string
    Description

    ID of the last item of the previous page

Request

GET
/v1/leads/{id}/evaluations
curl https://core.leadveyor.com/v1/leads/lead_2Ph6Tc9Ks4Wm1Lx7Qv3Nb8Dr/evaluations \
  -H "Authorization: Bearer {api_key}" \
  -H "Leadveyor-Workspace: {workspace_id}"  # account-wide keys only

Response 200

{
  "object": "list",
  "data": [
    {
      "score": null,
      "tier": "tier",
      "confidence": 0,
      "decidedBy": {
        "id": "id",
        "type": "disqualify",
        "reason": "reason"
      },
      "dimensions": [
        {
          "id": "id",
          "label": "label",
          "score": null,
          "confidence": 0,
          "known": [
            "known"
          ],
          "unknown": [
            "unknown"
          ]
        }
      ],
      "criteria": [
        {
          "id": "id",
          "label": "label",
          "type": "rule",
          "result": "met",
          "grade": null,
          "points": 0,
          "evidence": null,
          "dimension": null
        }
      ],
      "object": "evaluation",
      "id": "id",
      "leadId": "lead_9Kx2Lq7Vt4Wz8Nb3Pc6Rd1Hm",
      "inboundId": "inbo_9Kx2Lq7Vt4Wz8Nb3Pc6Rd1Hm",
      "jobId": "job_9Kx2Lq7Vt4Wz8Nb3Pc6Rd1Hm",
      "profileId": "prof_9Kx2Lq7Vt4Wz8Nb3Pc6Rd1Hm",
      "profileVersion": 0,
      "pipelineVersion": "pipelineVersion",
      "createdAt": "2026-11-02T09:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

POST/v1/leads/{id}/outcome

Record what happened to the lead: won, lost, … (replaces an earlier outcome)

Path parameters

  • Name
    id
    Type
    string
    Description

    Unique identifier, prefixed by the object type.

Required attributes

  • Name
    status
    Type
    'won' | 'lost' | 'no_response' | 'disqualified' | 'other'
    Description

    Current status.

Optional attributes

  • Name
    amount
    Type
    number
    Description

    Deal value

  • Name
    currency
    Type
    string
    Description

    ISO 4217; default: the workspace currency

  • Name
    reason
    Type
    string or null
    Description

    Why, especially for lost

  • Name
    occurredAt
    Type
    string
    Description

    When it happened; default: now

Request

POST
/v1/leads/{id}/outcome
curl -X POST https://core.leadveyor.com/v1/leads/lead_2Ph6Tc9Ks4Wm1Lx7Qv3Nb8Dr/outcome \
  -H "Authorization: Bearer {api_key}" \
  -H "Leadveyor-Workspace: {workspace_id}"  # account-wide keys only \
  -H "Content-Type: application/json" \
  -d '{
    "status": "won",
    "amount": 0,
    "currency": "currency",
    "reason": null
  }'

Response 200

{
  "object": "lead",
  "id": "lead_u8jzPde0IgxLd6GncfBAepfJ",
  "workspaceId": "ws_Bd0Kh8oOOL8dKLzdocJ2isAj",
  "livemode": true,
  "sourceId": "src_IhKtJ0RlgLKOmxgJTeKdNnFR",
  "inboundIds": [
    "inb_IBXuDL7DxtpYlSXpfKtHF4vU"
  ],
  "contactId": "ctc_CsMehGAkWvj7FAc9QeWJKY40",
  "contact": {
    "name": "Tom Baker",
    "firstName": "Tom",
    "lastName": "Baker",
    "emails": [
      "tom.baker@example.com"
    ],
    "phones": [
      "0412555777"
    ],
    "other": [],
    "company": null
  },
  "request": {
    "summary": "Customer wants a bathroom renovation in their apartment in Queens, with a budget of about $15k, starting next month.",
    "service": "Bathroom renovation"
  },
  "location": {
    "address": null,
    "city": "Queens",
    "postcode": null,
    "country": null
  },
  "language": "en",
  "fields": {
    "budget": {
      "amount": 15000,
      "currency": "USD"
    },
    "start_date": {
      "value": "2026-12-01",
      "min": "2026-12-01",
      "max": "2026-12-31",
      "asWritten": "next month"
    },
    "property_type": "apartment",
    "project_type": "bathroom"
  },
  "evaluation": {
    "confidence": 0.8,
    "criteria": [
      {
        "id": "budget_15k",
        "label": "Budget from $15k",
        "type": "rule",
        "result": "met",
        "grade": null,
        "points": 30,
        "evidence": null,
        "dimension": "what"
      },
      {
        "id": "big_project",
        "label": "Kitchen, full home or extension",
        "type": "rule",
        "result": "not_met",
        "grade": null,
        "points": 0,
        "evidence": null,
        "dimension": "what"
      }
    ],
    "dimensions": [
      {
        "id": "what",
        "label": "What",
        "score": 69,
        "confidence": 1,
        "known": [
          "budget_15k",
          "big_project"
        ],
        "unknown": []
      },
      {
        "id": "when",
        "label": "When",
        "score": null,
        "confidence": 0,
        "known": [],
        "unknown": [
          "start_soon"
        ]
      }
    ],
    "decidedBy": null,
    "score": 60,
    "tier": "warm",
    "id": "eval_uvSwMFLZDe1f8rESQedUStPK",
    "profileId": "prof_R0CsTy4Qwb8DwkNhFdnXsiVp",
    "profileVersion": 1,
    "evaluatedAt": "2026-10-23T15:07:26.371Z"
  },
  "outcome": {
    "status": "won",
    "value": {
      "amount": 14800,
      "currency": "USD"
    },
    "reason": null,
    "occurredAt": "2026-11-02T09:30:00.000Z",
    "recordedAt": "2026-10-23T15:38:00.591Z",
    "recordedBy": {
      "type": "api_key",
      "id": "key_zz63FfkCzJr4i0B3JrTAwR4y"
    }
  },
  "state": "active",
  "metadata": {},
  "legacy": null,
  "createdAt": "2026-10-23T15:07:26.371Z",
  "updatedAt": "2026-10-23T15:38:00.591Z"
}

DELETE/v1/leads/{id}/outcome

Remove the outcome (the deal was reopened)

Path parameters

  • Name
    id
    Type
    string
    Description

    Unique identifier, prefixed by the object type.

Request

DELETE
/v1/leads/{id}/outcome
curl -X DELETE https://core.leadveyor.com/v1/leads/lead_2Ph6Tc9Ks4Wm1Lx7Qv3Nb8Dr/outcome \
  -H "Authorization: Bearer {api_key}" \
  -H "Leadveyor-Workspace: {workspace_id}"  # account-wide keys only

Response 200

{
  "object": "lead",
  "id": "lead_u8jzPde0IgxLd6GncfBAepfJ",
  "workspaceId": "ws_Bd0Kh8oOOL8dKLzdocJ2isAj",
  "livemode": true,
  "sourceId": "src_IhKtJ0RlgLKOmxgJTeKdNnFR",
  "inboundIds": [
    "inb_IBXuDL7DxtpYlSXpfKtHF4vU"
  ],
  "contactId": "ctc_CsMehGAkWvj7FAc9QeWJKY40",
  "contact": {
    "name": "Tom Baker",
    "firstName": "Tom",
    "lastName": "Baker",
    "emails": [
      "tom.baker@example.com"
    ],
    "phones": [
      "0412555777"
    ],
    "other": [],
    "company": null
  },
  "request": {
    "summary": "Customer wants a bathroom renovation in their apartment in Queens, with a budget of about $15k, starting next month.",
    "service": "Bathroom renovation"
  },
  "location": {
    "address": null,
    "city": "Queens",
    "postcode": null,
    "country": null
  },
  "language": "en",
  "fields": {
    "budget": {
      "amount": 15000,
      "currency": "USD"
    },
    "start_date": {
      "value": "2026-12-01",
      "min": "2026-12-01",
      "max": "2026-12-31",
      "asWritten": "next month"
    },
    "property_type": "apartment",
    "project_type": "bathroom"
  },
  "evaluation": {
    "confidence": 0.8,
    "criteria": [
      {
        "id": "budget_15k",
        "label": "Budget from $15k",
        "type": "rule",
        "result": "met",
        "grade": null,
        "points": 30,
        "evidence": null,
        "dimension": "what"
      },
      {
        "id": "big_project",
        "label": "Kitchen, full home or extension",
        "type": "rule",
        "result": "not_met",
        "grade": null,
        "points": 0,
        "evidence": null,
        "dimension": "what"
      }
    ],
    "dimensions": [
      {
        "id": "what",
        "label": "What",
        "score": 69,
        "confidence": 1,
        "known": [
          "budget_15k",
          "big_project"
        ],
        "unknown": []
      },
      {
        "id": "when",
        "label": "When",
        "score": null,
        "confidence": 0,
        "known": [],
        "unknown": [
          "start_soon"
        ]
      }
    ],
    "decidedBy": null,
    "score": 60,
    "tier": "warm",
    "id": "eval_uvSwMFLZDe1f8rESQedUStPK",
    "profileId": "prof_R0CsTy4Qwb8DwkNhFdnXsiVp",
    "profileVersion": 1,
    "evaluatedAt": "2026-10-23T15:07:26.371Z"
  },
  "outcome": {
    "status": "won",
    "value": {
      "amount": 14800,
      "currency": "USD"
    },
    "reason": null,
    "occurredAt": "2026-11-02T09:30:00.000Z",
    "recordedAt": "2026-10-23T15:38:00.591Z",
    "recordedBy": {
      "type": "api_key",
      "id": "key_zz63FfkCzJr4i0B3JrTAwR4y"
    }
  },
  "state": "active",
  "metadata": {},
  "legacy": null,
  "createdAt": "2026-10-23T15:07:26.371Z",
  "updatedAt": "2026-10-23T15:38:00.591Z"
}

Was this page helpful?