Skip to main content

LeadCreateRequestDTO

Lead create / update request body. The endpoint serves both create and update, distinguished by the id field:

  • id omitted (or null) → a new lead is created.
  • id provided → the existing lead is updated.

Partial update (tri-state) semantics. On update, every updatable field is interpreted by its presence in the JSON body:

  • absent (key not sent) → the current value is left unchanged.
  • present with a value → the field is updated.
  • present and explicitly null → the field is cleared.

Nested tri-state. The same presence-based semantics apply to the keys inside each contacts[] and fields[] item. Within an item, an omitted key leaves that attribute's current value untouched, a key with a value updates it, and an explicit null clears it. The write-variants ContactRequestDTO and FieldValueRequestDTO describe these per-key rules in detail.

Example: \{"id": 26801, "pipeStatusId": 603, "contacts": [\{"id": 1001, "phones": ["+998991112233"], "username": null\}]\} updates only contact 1001's phone and clears its username; its name, type and fields are left unchanged.

Warning — lists are replaced as a whole. The nested tri-state above applies to the keys inside an item, but each list itself is taken as the complete set when its key is present:

  • fields — the list is treated as the lead's full set of custom field values. Any existing field value not named in the list is DELETED (send 3 of 10 and the other 7 are removed).
  • contacts — likewise, any existing contact not present in the list is UNLINKED from the lead.

To leave fields or contacts untouched, omit the key entirely — do not send an empty array [] (its behaviour is not guaranteed). To change only some of a lead's field values without deleting the rest, use POST /v1/open-api/lead/{leadId}/field/list instead of the fields key here.

Exception — pipeStatusId is always required on every request (create and update); missing it returns 400 (pipeStatusId / NOT_NULL).

idint64

Lead ID. Omit to create, provide to update.

Example: 1001
namestring

Lead name

Example: New apartment buyer
balancenumber

Lead balance

Example: 100
currencyIdint32

Currency ID

Example: 24
pipeStatusIdint64required

Pipeline status ID. Required on every request (create and update).

Example: 979
responsibleByIdint32

Responsible user ID

Example: 101
tagIdsint32[]

Tag IDs attached to the lead.

Example: [3,7]
contacts object[]

Contacts attached to the lead. Replace-all: when this key is present the list is the complete set of contacts — any existing contact not in it is unlinked from the lead. Omit the key entirely to leave contacts untouched.

  • Array [
    • idint64

    Contact ID. Omit to create a new contact, provide to update an existing one.

    Example: 1001
    namestringnullable

    Contact name. Required when creating.

    Example: John Doe
    fields object[]nullable

    Contact custom field values.

  • Array [
    • idint64required

    CRM field identifier this value belongs to. Always required.

    Example: 1
    valuestringnullable

    Simple value (as text)

    Example: VIP
    valueListstring[]nullable

    Multiple values (for multi-select fields).

    Example: ["VIP","New"]
    valueTypeValueType

    Field value type enum.

    Possible values: [STREET, DISTRICT, DEFAULT]

    Default value: DEFAULT
    Example: DEFAULT
    typestringnullable

    Field type (lowercased, e.g. text, select)

    Example: select
    infoTypeInfoType

    Which entity a field/value belongs to.

    • LED — the lead
    • CONTACT — the contact

    Possible values: [LED, CONTACT]

    Example: LED
    longitudedoublenullable

    Geo coordinate: longitude (for location fields)

    Example: 69.2401
    latitudedoublenullable

    Geo coordinate: latitude (for location fields)

    Example: 41.2995
    numbernumbernullable

    Value for NUMBER fields. Required (directly or via the value fallback) when the field's type is NUMBER.

    Example: 1500.5
    currencyIdint64nullable

    Currency ID. Required when the NUMBER field's format is CURRENCY.

    Example: 24
  • ]
    • typeContactType

    Contact type enum.

    Possible values: [SIMPLE, TELEGRAM, INSTAGRAM, WEBSITE, FACEBOOK, OTHER, CALL_PBX, MARKETPLACE, GOOGLE_SHEETS, WEB_FORM, WAZZUP, AMO_CRM, TELEGRAM_BUSINESS]

    Default value: SIMPLE
    Example: TELEGRAM
    accountIdstringnullable

    Account ID (if available)

    Example: acc123
    usernamestringnullable

    Username

    Example: johndoe
    phonesstring[]nullable

    Phone numbers. Required (non-empty) when creating.

    Example: ["+998901234567"]
    receiverIdstringnullable

    Receiver ID (if available)

    Example: rec123
  • ]
    • fields object[]

    Additional field values. Replace-all: when this key is present the list is the complete set of the lead's custom field values — any existing value not in it is deleted. Omit the key entirely to leave fields untouched. To update only some fields without deleting the rest, use POST /v1/open-api/lead/{leadId}/field/list instead.

  • Array [
    • idint64required

    CRM field identifier this value belongs to. Always required.

    Example: 1
    valuestringnullable

    Simple value (as text)

    Example: VIP
    valueListstring[]nullable

    Multiple values (for multi-select fields).

    Example: ["VIP","New"]
    valueTypeValueType

    Field value type enum.

    Possible values: [STREET, DISTRICT, DEFAULT]

    Default value: DEFAULT
    Example: DEFAULT
    typestringnullable

    Field type (lowercased, e.g. text, select)

    Example: select
    infoTypeInfoType

    Which entity a field/value belongs to.

    • LED — the lead
    • CONTACT — the contact

    Possible values: [LED, CONTACT]

    Example: LED
    longitudedoublenullable

    Geo coordinate: longitude (for location fields)

    Example: 69.2401
    latitudedoublenullable

    Geo coordinate: latitude (for location fields)

    Example: 41.2995
    numbernumbernullable

    Value for NUMBER fields. Required (directly or via the value fallback) when the field's type is NUMBER.

    Example: 1500.5
    currencyIdint64nullable

    Currency ID. Required when the NUMBER field's format is CURRENCY.

    Example: 24
  • ]
    • notestring

    Free-text note

    Example: Called, will visit Friday
    sourceLeadChannelSource

    Channel a lead originated from. Serialized by name.

    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]

    Example: INSTAGRAM
    sourceChannelstring

    Free-text channel identifier

    Example: ig-promo-2026
    utmData object

    UTM / tracking attribution data attached to a lead.

    utmSourcestring

    UTM source

    Example: instagram
    utmMediumstring

    UTM medium

    Example: cpc
    utmCampaignstring

    UTM campaign

    Example: spring_sale
    utmTermstring

    UTM term

    Example: apartment
    utmContentstring

    UTM content

    Example: banner_a
    fbcLidstring

    Facebook click ID (fbclid)

    Example: IwAR0...
    fbClientIpAddressstring

    Client IP address (Facebook CAPI)

    Example: 203.0.113.5
    fbClientUserAgentstring

    Client user agent (Facebook CAPI)

    Example: Mozilla/5.0 ...
    fbpstring

    Facebook browser ID (_fbp cookie)

    Example: fb.1.1672531200.1234567890
    LeadCreateRequestDTO
    {
      "id": 1001,
      "name": "New apartment buyer",
      "balance": 100,
      "currencyId": 24,
      "pipeStatusId": 979,
      "responsibleById": 101,
      "tagIds": [
        3,
        7
      ],
      "contacts": [
        {
          "id": 1001,
          "name": "John Doe",
          "fields": [
            {
              "id": 1,
              "value": "VIP",
              "valueList": [
                "VIP",
                "New"
              ],
              "valueType": "DEFAULT",
              "type": "select",
              "infoType": "LED",
              "longitude": 69.2401,
              "latitude": 41.2995,
              "number": 1500.5,
              "currencyId": 24
            }
          ],
          "type": "TELEGRAM",
          "accountId": "acc123",
          "username": "johndoe",
          "phones": [
            "+998901234567"
          ],
          "receiverId": "rec123"
        }
      ],
      "fields": [
        {
          "id": 1,
          "value": "VIP",
          "valueList": [
            "VIP",
            "New"
          ],
          "valueType": "DEFAULT",
          "type": "select",
          "infoType": "LED",
          "longitude": 69.2401,
          "latitude": 41.2995,
          "number": 1500.5,
          "currencyId": 24
        }
      ],
      "note": "Called, will visit Friday",
      "source": "INSTAGRAM",
      "sourceChannel": "ig-promo-2026",
      "utmData": {
        "utmSource": "instagram",
        "utmMedium": "cpc",
        "utmCampaign": "spring_sale",
        "utmTerm": "apartment",
        "utmContent": "banner_a",
        "fbcLid": "IwAR0...",
        "fbClientIpAddress": "203.0.113.5",
        "fbClientUserAgent": "Mozilla/5.0 ...",
        "fbp": "fb.1.1672531200.1234567890"
      }
    }