Contacts

A contact is a person, matched by email or phone across all their leads with no time limit. Mark VIP or blocked people, and see how many of their leads were won or lost.

The Contact object

Properties

  • Name
    object
    Type
    'contact'
    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
    name
    Type
    string or null
    Description

    Display name.

  • Name
    firstName
    Type
    string or null
    Description

     

  • Name
    lastName
    Type
    string or null
    Description

     

  • Name
    company
    Type
    string or null
    Description

     

  • Name
    emails
    Type
    array of string
    Description

     

  • Name
    phones
    Type
    array of string
    Description

     

  • Name
    vip
    Type
    boolean
    Description

     

  • Name
    blocked
    Type
    boolean
    Description

     

  • Name
    metadata
    Type
    object
    Description

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

  • Name
    stats
    Type
    object
    Description

     

  • 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/contacts

People who sent 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
    email
    Type
    string
    Description

     

  • Name
    phone
    Type
    string
    Description

    Any format; matched by the last 9 digits

  • Name
    vip
    Type
    'true' | 'false'
    Description

     

  • Name
    blocked
    Type
    'true' | 'false'
    Description

     

  • Name
    legacy_id
    Type
    string
    Description

    Original contact ID, for contacts imported from another system

Request

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

Response 200

{
  "object": "list",
  "data": [
    {
      "object": "contact",
      "id": "ctc_CsMehGAkWvj7FAc9QeWJKY40",
      "workspaceId": "ws_Bd0Kh8oOOL8dKLzdocJ2isAj",
      "livemode": true,
      "name": "Tom Baker",
      "firstName": "Tom",
      "lastName": "Baker",
      "company": null,
      "emails": [
        "tom.baker@example.com"
      ],
      "phones": [
        "0412555777"
      ],
      "vip": false,
      "blocked": false,
      "metadata": {},
      "stats": {
        "leads": 1,
        "won": 1,
        "lost": 0,
        "lastLeadAt": "2026-10-23T15:07:26.371Z"
      },
      "legacy": null,
      "createdAt": "2026-10-23T15:07:26.390Z",
      "updatedAt": "2026-10-23T15:07:26.390Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET/v1/contacts/{id}

One contact with lead and outcome counts

Path parameters

  • Name
    id
    Type
    string
    Description

    Unique identifier, prefixed by the object type.

Request

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

Response 200

{
  "object": "contact",
  "id": "ctc_CsMehGAkWvj7FAc9QeWJKY40",
  "workspaceId": "ws_Bd0Kh8oOOL8dKLzdocJ2isAj",
  "livemode": true,
  "name": "Tom Baker",
  "firstName": "Tom",
  "lastName": "Baker",
  "company": null,
  "emails": [
    "tom.baker@example.com"
  ],
  "phones": [
    "0412555777"
  ],
  "vip": false,
  "blocked": false,
  "metadata": {},
  "stats": {
    "leads": 1,
    "won": 1,
    "lost": 0,
    "lastLeadAt": "2026-10-23T15:07:26.371Z"
  },
  "legacy": null,
  "createdAt": "2026-10-23T15:07:26.390Z",
  "updatedAt": "2026-10-23T15:07:26.390Z"
}

PATCH/v1/contacts/{id}

Mark VIP or blocked, fix name or company, set your metadata

Path parameters

  • Name
    id
    Type
    string
    Description

    Unique identifier, prefixed by the object type.

Optional attributes

  • Name
    name
    Type
    string or null
    Description

    Display name.

  • Name
    company
    Type
    string or null
    Description

     

  • Name
    vip
    Type
    boolean
    Description

     

  • Name
    blocked
    Type
    boolean
    Description

    Mark as never-a-customer (spam, competitor)

  • Name
    metadata
    Type
    object
    Description

    Replaces your key-values, e.g. a CRM id

Request

PATCH
/v1/contacts/{id}
curl -X PATCH https://core.leadveyor.com/v1/contacts/ctc_7Rm2Kx9Pq4Lz1Wv6Tn3Hb8Dc \
  -H "Authorization: Bearer {api_key}" \
  -H "Leadveyor-Workspace: {workspace_id}"  # account-wide keys only \
  -H "Content-Type: application/json" \
  -d '{
    "name": null,
    "company": null,
    "vip": false,
    "blocked": false
  }'

Response 200

{
  "object": "contact",
  "id": "ctc_CsMehGAkWvj7FAc9QeWJKY40",
  "workspaceId": "ws_Bd0Kh8oOOL8dKLzdocJ2isAj",
  "livemode": true,
  "name": "Tom Baker",
  "firstName": "Tom",
  "lastName": "Baker",
  "company": null,
  "emails": [
    "tom.baker@example.com"
  ],
  "phones": [
    "0412555777"
  ],
  "vip": false,
  "blocked": false,
  "metadata": {},
  "stats": {
    "leads": 1,
    "won": 1,
    "lost": 0,
    "lastLeadAt": "2026-10-23T15:07:26.371Z"
  },
  "legacy": null,
  "createdAt": "2026-10-23T15:07:26.390Z",
  "updatedAt": "2026-10-23T15:07:26.390Z"
}

GET/v1/contacts/{id}/leads

All leads of this person, 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/contacts/{id}/leads
curl https://core.leadveyor.com/v1/contacts/ctc_7Rm2Kx9Pq4Lz1Wv6Tn3Hb8Dc/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
}

Was this page helpful?