Skip to main content

LeadFilterDTO

Lead filter request body. Pagination plus optional filters. The channel / UTM filters (sources, channels, utmSource, utmMedium, utmContent, utmCampaign, utmTerm) are matched against a single attribution per lead, selected by attributionOrder.

pageint32

Page number, 1-based. Min 1.

Possible values: >= 1

Default value: 1
Example: 1
sizeint32

Page size. Min 1, max 100.

Possible values: >= 1 and <= 100

Default value: 10
Example: 10
orders object

Sort order. Each key is a sort field — see LeadOrderField — and each value a direction. Keys are applied in the order they appear in the JSON object, so {"UPDATED_TIMESTAMP": "DESC", "ID": "ASC"} sorts by update time first and breaks ties by ID. Unless ID is one of the keys, a trailing ID DESC tie-breaker is appended so paging stays stable across requests. Omit (or send {}) to keep the default — newest ID first.

property name*string

Possible values: [ASC, DESC]

idsint64[]

Filter by exact lead IDs — for bulk re-sync (optional).

Example: [1001,1002]
pipeStatusIdsint64[]

Filter by pipeline status IDs (optional).

Example: [979]
pipeIdsint64[]

Filter by pipe (funnel) IDs — matches leads whose pipeline status belongs to one of these pipes (optional).

Example: [12]
currencyIdsint32[]

Filter by the lead's balance currency IDs (optional).

Example: [1]
searchstringnullable

Free-text search across lead name and contact name (optional).

Example: Odil
phonestring

Filter by contact phone. The server matches on the last 9 digits (phone.takeLast(9)) against each contact phone's 9-digit suffix, so send digits only (no spaces or symbols). Optional.

Example: 901234567
createdTimestampFromint64

Lower bound (inclusive) for the response's createdTimestamp (epoch seconds, optional)

Example: 1730419200
createdTimestampToint64

Upper bound (inclusive) for the response's createdTimestamp (epoch seconds, optional)

Example: 1733011200
updatedTimestampFromint64

Lower bound (inclusive) for the response's updatedTimestamp (epoch seconds, optional)

Example: 1730419200
updatedTimestampToint64

Upper bound (inclusive) for the response's updatedTimestamp (epoch seconds, optional)

Example: 1733011200
startint64deprecated

Deprecated alias of createdTimestampFrom. Ignored when createdTimestampFrom is sent.

Example: 1730419200
finishint64deprecated

Deprecated alias of createdTimestampTo. Ignored when createdTimestampTo is sent.

Example: 1733011200
includeDeletedboolean

When true, soft-deleted leads are returned as well — each one carrying deleted: true and a deletedTimestamp. Defaults to false (active leads only). Note that leads whose pipeline or pipeline status was deleted are excluded regardless of this flag.

Default value: false
Example: true
deletedOnlyboolean

true — return only soft-deleted leads. Takes precedence over includeDeleted.

Default value: false
Example: false
createdByIdsint32[]

Filter by creator employee IDs (optional).

Example: [95]
responsibleByIdsint32[]

Filter by responsible employee IDs (optional).

Example: [101]
reasonsForRefusalIdsint64[]

Filter by refusal (lost) reason IDs (optional) — only leads whose reasonsForRefusal is one of these are returned. See GET /v1/open-api/reason-for-refusal/all for the company's reasons. An empty array is ignored.

Example: [14]
tagIdsint64[]

Filter by tag IDs (optional).

Example: [3,7]
customFields object[]

Filter by CRM custom field values (optional). Every item is applied as a separate condition and all of them must match (AND between items); within a single item values are matched as OR. See CustomFieldFilter.

  • Array [
    • customFieldIdint64required

    CRM custom field ID to filter on. Required.

    Example: 42
    typeCustomFieldType

    Field type, decides how the condition is interpreted. Defaults to TEXT.

    Possible values: [TEXT, EXTENDED_TEXT, DATE, SELECT, MULTI_SELECT, RADIO, TOGGLE_SWITCH, URL, TAG, LOCATION, COUNTER, ADDRESS, EMPLOYEE, FILE, NUMBER]

    Default value: TEXT
    Example: SELECT
    valuesstring[]

    Values to match (OR between them). Used for every type except NUMBER, and ignored when hasValue is sent. For ADDRESS send comma-separated Uzbek place names (see the description above).

    Example: ["VIP"]
    numberStartnumber

    Lower bound for NUMBER fields (inclusive). Defaults to 0 when omitted.

    Example: 1000
    numberFinishnumber

    Upper bound for NUMBER fields (inclusive). Unbounded when omitted.

    Example: 5000
    currencyIdint64

    Restrict a NUMBER condition to one currency (optional). When omitted, any currency matches.

    Example: 24
    hasValueboolean

    Presence check. true → the lead has any value for this field, false → it has none. Overrides values / numberStart / numberFinish / currencyId.

    Example: true
  • ]
    • attributionOrderAttributionOrder

    Selects which of a lead's attributions the channel / UTM filters are matched against.

    • FIRST — the lead's first (earliest) attribution
    • LAST — the lead's most recent attribution

    Possible values: [FIRST, LAST]

    Default value: FIRST
    Example: LAST
    sourcesLeadChannelSource[]

    Filter by channel source of the selected attribution (optional).

    Possible values: [INSTAGRAM, FACEBOOK, FACEBOOK_FORM, TELEGRAM, TELEGRAM_BUSINESS, TELEGRAM_BOT, WHATSAPP, WABA, VK, VIBER, AVITO, WEBSITE, AMO_CRM, ONLINE_PBX, UTEL, SIPUNI, ASTERISK, MOI_ZVONKI, WEB_FORM, EMPLOYEE, UNKNOWN]

    channelsint64[]

    Filter by channel IDs of the selected attribution (optional).

    Example: [12]
    utmSourcestring

    Filter by UTM source of the selected attribution (optional)

    Example: instagram
    utmMediumstring

    Filter by UTM medium of the selected attribution (optional)

    Example: cpc
    utmContentstring

    Filter by UTM content of the selected attribution (optional)

    Example: banner_a
    utmCampaignstring

    Filter by UTM campaign of the selected attribution (optional)

    Example: spring_sale
    utmTermstring

    Filter by UTM term of the selected attribution (optional)

    Example: apartment
    LeadFilterDTO
    {
      "page": 1,
      "size": 10,
      "orders": {
        "UPDATED_TIMESTAMP": "DESC",
        "ID": "ASC"
      },
      "ids": [
        1001,
        1002
      ],
      "pipeStatusIds": [
        979
      ],
      "pipeIds": [
        12
      ],
      "currencyIds": [
        1
      ],
      "search": "Odil",
      "phone": "901234567",
      "createdTimestampFrom": 1730419200,
      "createdTimestampTo": 1733011200,
      "updatedTimestampFrom": 1730419200,
      "updatedTimestampTo": 1733011200,
      "includeDeleted": true,
      "deletedOnly": false,
      "createdByIds": [
        95
      ],
      "responsibleByIds": [
        101
      ],
      "reasonsForRefusalIds": [
        14
      ],
      "tagIds": [
        3,
        7
      ],
      "customFields": [
        {
          "customFieldId": 42,
          "type": "SELECT",
          "values": [
            "VIP"
          ],
          "numberStart": 1000,
          "numberFinish": 5000,
          "currencyId": 24,
          "hasValue": true
        }
      ],
      "attributionOrder": "LAST",
      "sources": [
        "INSTAGRAM"
      ],
      "channels": [
        12
      ],
      "utmSource": "instagram",
      "utmMedium": "cpc",
      "utmContent": "banner_a",
      "utmCampaign": "spring_sale",
      "utmTerm": "apartment"
    }