Inbounds

An inbound is one message received from any source — an email, a form submission or an API call. Leadveyor queues it, filters junk, extracts the leads and scores them. Use these endpoints to send messages and to follow the processing queue and history.

The Inbound object

Properties

  • Name
    object
    Type
    'inbound'
    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
    channel
    Type
    string
    Description

     

  • Name
    status
    Type
    'received' | 'processing' | 'processed' | 'failed' | 'quota_exceeded'
    Description

    quota_exceeded: kept, waits for the plan's allowance and is then processed automatically

  • Name
    classification
    Type
    'lead' | 'junk' | 'not_lead' | null or null
    Description

     

  • Name
    junk
    Type
    object or null
    Description

     

  • Name
    leadIds
    Type
    array of string
    Description

    Leads extracted from this message.

  • Name
    profile
    Type
    object or null
    Description

     

  • Name
    error
    Type
    object or null
    Description

    Why processing failed (after all retries)

  • Name
    externalId
    Type
    string or null
    Description

     

  • Name
    metadata
    Type
    object
    Description

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

  • Name
    content
    Type
    object
    Description

    The message, normalized

  • Name
    receivedAt
    Type
    string
    Description

     

  • Name
    processedAt
    Type
    string or null
    Description

     

  • Name
    jobs
    Type
    array of Job
    Description

    Processing runs, newest first (single inbound only)


POST/v1/inbounds

Send a message for processing

Stores the message and queues it (202). It is filtered for junk, its leads are extracted and scored, and failures are retried. With wait=true the request waits up to 30 s and returns the result (200), or 202 if still processing. Repeating a request with the same externalId returns the original inbound (200) without processing it again.

Query parameters

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

     

Optional attributes

  • Name
    text
    Type
    string
    Description

    Free text: an email body, a chat message, a transcript…

  • Name
    email
    Type
    object
    Description

     

  • Name
    fields
    Type
    object
    Description

    Form fields exactly as received; no mapping needed

  • Name
    channel
    Type
    string
    Description

    email, form, chat, … Inferred when omitted

  • Name
    sourceId
    Type
    string
    Description

    Default: the workspace's API source

  • Name
    profileId
    Type
    string
    Description

    Override the source's / workspace's profile for this message

  • Name
    externalId
    Type
    string
    Description

    Your ID for this message; sending it again returns the same inbound (no double processing)

  • Name
    metadata
    Type
    object
    Description

    Your key-values, copied to the leads (e.g. a CRM id)

Request

POST
/v1/inbounds
curl -X POST https://core.leadveyor.com/v1/inbounds \
  -H "Authorization: Bearer {api_key}" \
  -H "Leadveyor-Workspace: {workspace_id}"  # account-wide keys only \
  -H "Content-Type: application/json" \
  -d '{
    "text": "text",
    "email": {
      "from": "from",
      "subject": "subject",
      "text": "text",
      "html": "html"
    },
    "fields": {
      "name": "Sarah",
      "message": "Wedding for 120 guests"
    },
    "channel": "channel"
  }'

Response 200

{
  "object": "inbound",
  "id": "inb_IBXuDL7DxtpYlSXpfKtHF4vU",
  "workspaceId": "ws_Bd0Kh8oOOL8dKLzdocJ2isAj",
  "livemode": true,
  "sourceId": "src_IhKtJ0RlgLKOmxgJTeKdNnFR",
  "channel": "form",
  "status": "processed",
  "classification": "lead",
  "junk": null,
  "leadIds": [
    "lead_u8jzPde0IgxLd6GncfBAepfJ"
  ],
  "profile": {
    "id": "prof_R0CsTy4Qwb8DwkNhFdnXsiVp",
    "version": 1
  },
  "error": null,
  "externalId": null,
  "metadata": {},
  "content": {
    "channel": "form",
    "fields": {
      "name": "Tom Baker",
      "email": "tom.baker@example.com",
      "phone": "0412 555 777",
      "message": "Need a bathroom renovation in Queens, budget 15k, start next month. We own the apartment."
    }
  },
  "receivedAt": "2026-10-23T15:07:21.291Z",
  "processedAt": "2026-10-23T15:07:26.416Z",
  "jobs": [
    {
      "object": "job",
      "id": "job_9ojfljoQoaF1LlqsajAIxNKu",
      "inboundId": "inb_IBXuDL7DxtpYlSXpfKtHF4vU",
      "trigger": "initial",
      "options": {
        "notJunk": false,
        "profileId": null
      },
      "status": "completed",
      "attempts": 1,
      "steps": [
        {
          "name": "junk",
          "ms": 1825,
          "detail": "lead (high)"
        },
        {
          "name": "extract",
          "ms": 3227,
          "detail": "1 lead(s)"
        }
      ],
      "usage": {
        "costUsd": 0.00488,
        "inputTokens": 4255,
        "outputTokens": 451,
        "models": [
          "claude-haiku-5-5",
          "claude-sonnet-5-5"
        ]
      },
      "pipelineVersion": "classify-2026-10-21+extract-2026-10-22d",
      "error": null,
      "createdAt": "2026-10-23T15:07:21.298Z",
      "startedAt": "2026-10-23T15:07:21.308Z",
      "finishedAt": "2026-10-23T15:07:26.416Z"
    }
  ]
}

GET/v1/inbounds

Messages received, newest first: the processing queue and history

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
    status
    Type
    'received' | 'processing' | 'processed' | 'failed'
    Description

    Current status.

  • Name
    classification
    Type
    'lead' | 'junk' | 'not_lead'
    Description

     

  • Name
    sourceId
    Type
    string
    Description

    The source the message came through.

Request

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

Response 200

{
  "object": "list",
  "data": [
    {
      "object": "inbound",
      "id": "inb_IBXuDL7DxtpYlSXpfKtHF4vU",
      "workspaceId": "ws_Bd0Kh8oOOL8dKLzdocJ2isAj",
      "livemode": true,
      "sourceId": "src_IhKtJ0RlgLKOmxgJTeKdNnFR",
      "channel": "form",
      "status": "processed",
      "classification": "lead",
      "junk": null,
      "leadIds": [
        "lead_u8jzPde0IgxLd6GncfBAepfJ"
      ],
      "profile": {
        "id": "prof_R0CsTy4Qwb8DwkNhFdnXsiVp",
        "version": 1
      },
      "error": null,
      "externalId": null,
      "metadata": {},
      "content": {
        "channel": "form",
        "fields": {
          "name": "Tom Baker",
          "email": "tom.baker@example.com",
          "phone": "0412 555 777",
          "message": "Need a bathroom renovation in Queens, budget 15k, start next month. We own the apartment."
        }
      },
      "receivedAt": "2026-10-23T15:07:21.291Z",
      "processedAt": "2026-10-23T15:07:26.416Z",
      "jobs": [
        {
          "object": "job",
          "id": "job_9ojfljoQoaF1LlqsajAIxNKu",
          "inboundId": "inb_IBXuDL7DxtpYlSXpfKtHF4vU",
          "trigger": "initial",
          "options": {
            "notJunk": false,
            "profileId": null
          },
          "status": "completed",
          "attempts": 1,
          "steps": [
            {
              "name": "junk",
              "ms": 1825,
              "detail": "lead (high)"
            },
            {
              "name": "extract",
              "ms": 3227,
              "detail": "1 lead(s)"
            }
          ],
          "usage": {
            "costUsd": 0.00488,
            "inputTokens": 4255,
            "outputTokens": 451,
            "models": [
              "claude-haiku-5-5",
              "claude-sonnet-5-5"
            ]
          },
          "pipelineVersion": "classify-2026-10-21+extract-2026-10-22d",
          "error": null,
          "createdAt": "2026-10-23T15:07:21.298Z",
          "startedAt": "2026-10-23T15:07:21.308Z",
          "finishedAt": "2026-10-23T15:07:26.416Z"
        }
      ]
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET/v1/inbounds/{id}

One message with its processing runs (steps, errors, cost)

Path parameters

  • Name
    id
    Type
    string
    Description

    Unique identifier, prefixed by the object type.

Request

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

Response 200

{
  "object": "inbound",
  "id": "inb_IBXuDL7DxtpYlSXpfKtHF4vU",
  "workspaceId": "ws_Bd0Kh8oOOL8dKLzdocJ2isAj",
  "livemode": true,
  "sourceId": "src_IhKtJ0RlgLKOmxgJTeKdNnFR",
  "channel": "form",
  "status": "processed",
  "classification": "lead",
  "junk": null,
  "leadIds": [
    "lead_u8jzPde0IgxLd6GncfBAepfJ"
  ],
  "profile": {
    "id": "prof_R0CsTy4Qwb8DwkNhFdnXsiVp",
    "version": 1
  },
  "error": null,
  "externalId": null,
  "metadata": {},
  "content": {
    "channel": "form",
    "fields": {
      "name": "Tom Baker",
      "email": "tom.baker@example.com",
      "phone": "0412 555 777",
      "message": "Need a bathroom renovation in Queens, budget 15k, start next month. We own the apartment."
    }
  },
  "receivedAt": "2026-10-23T15:07:21.291Z",
  "processedAt": "2026-10-23T15:07:26.416Z",
  "jobs": [
    {
      "object": "job",
      "id": "job_9ojfljoQoaF1LlqsajAIxNKu",
      "inboundId": "inb_IBXuDL7DxtpYlSXpfKtHF4vU",
      "trigger": "initial",
      "options": {
        "notJunk": false,
        "profileId": null
      },
      "status": "completed",
      "attempts": 1,
      "steps": [
        {
          "name": "junk",
          "ms": 1825,
          "detail": "lead (high)"
        },
        {
          "name": "extract",
          "ms": 3227,
          "detail": "1 lead(s)"
        }
      ],
      "usage": {
        "costUsd": 0.00488,
        "inputTokens": 4255,
        "outputTokens": 451,
        "models": [
          "claude-haiku-5-5",
          "claude-sonnet-5-5"
        ]
      },
      "pipelineVersion": "classify-2026-10-21+extract-2026-10-22d",
      "error": null,
      "createdAt": "2026-10-23T15:07:21.298Z",
      "startedAt": "2026-10-23T15:07:21.308Z",
      "finishedAt": "2026-10-23T15:07:26.416Z"
    }
  ]
}

POST/v1/inbounds/{id}/reprocess

Process a message again (e.g. it was wrongly marked junk, or with another profile)

Path parameters

  • Name
    id
    Type
    string
    Description

    Unique identifier, prefixed by the object type.

Optional attributes

  • Name
    notJunk
    Type
    boolean
    Description

    Skip the junk filter (the message was wrongly marked junk)

  • Name
    profileId
    Type
    string
    Description

     

Request

POST
/v1/inbounds/{id}/reprocess
curl -X POST https://core.leadveyor.com/v1/inbounds/inb_9Qe3Wn7Kd2Lp5Xr8Vt1Mz4Bh/reprocess \
  -H "Authorization: Bearer {api_key}" \
  -H "Leadveyor-Workspace: {workspace_id}"  # account-wide keys only \
  -H "Content-Type: application/json" \
  -d '{
    "notJunk": false,
    "profileId": "prof_9Kx2Lq7Vt4Wz8Nb3Pc6Rd1Hm"
  }'

Response 202

{
  "object": "job",
  "id": "id",
  "inboundId": "inbo_9Kx2Lq7Vt4Wz8Nb3Pc6Rd1Hm",
  "trigger": "initial",
  "options": {
    "notJunk": false,
    "profileId": null
  },
  "status": "queued",
  "attempts": 0,
  "steps": [
    {
      "name": "name",
      "ms": 0,
      "detail": "detail"
    }
  ],
  "usage": {
    "costUsd": 0,
    "inputTokens": 0,
    "outputTokens": 0,
    "models": [
      "models"
    ]
  },
  "pipelineVersion": null,
  "error": {
    "code": "code",
    "message": "message"
  },
  "createdAt": "2026-11-02T09:30:00.000Z",
  "startedAt": null,
  "finishedAt": null
}

Was this page helpful?