Events and Notes

In this section we will describe how to work with events and notes via API

Table of Contents

Events common information

Events list is a data set of events on the account. Using the events list API you can get the information on different events on the account.

Events list

Method

GET /api/v4/events

Description

This method allows to get the events list.

Limitations

Method is available for all account users. The returned data depends on the user’s rights for the entity.

GET parameters

Parameter Data type Description
with string This parameter takes a string which may consist of several values separated by commas. This method supports the following parameters.
page int Sample page
limit int The number of the entities returned in the response of one request (limit – 250)
filter object Filter
filter[id] string|array Filter by the event ID. Either a single ID or an array of IDs can be passed
filter[created_at] int|array Filter by the event creation date (when it occured).
A timestamp can be passed, in that case, events created after the timestamp value will be returned.
Otherwise, the array of the following structure can be passed to filter between FROM and TO values: filter[created_at][from]=… and filter[created_at][to]=…
filter[created_by] int|array Filter by users. An array of up to 10 users on the account can be passed.
For example, filter[created_by][]=956328&filter[created_by][]=504141
filter[entity] string|array Filter by the entity type passed as an array of entities. Available parameters – lead, contact, company,
customer, task, catalog_{CATALOG_ID}. For example, filter[entity][]=lead&filter[entity][]=contact&filter[entity][]=catalog_1075
filter[entity_id] int|array Filter by the entity ID. An array of up to 10 ID can be passed. The filter filter[entity] with no more than one entity should be passed to use this filter.
For example, filter[entity]=lead&filter[entity_id][]=648533
filter[type] string|array Filter by the event type. Types are passed as an array. More on the event types
filter[value_before] string|array Filter by the value “before”. More on the available values and restrictions here
filter[value_after] string|array Filter by the value “after”. More on the available values and restrictions here

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code Case
200 Request successful
401 User is not authorized
402 Account is not paid

Response parameters

Method returns a collection of event models. The properties of the model are listed below.

Parameter Data type Description
id string Event ID
type string Event type
entity_id int ID of the entity the event belongs to
entity_type string Type of the entity the event belongs to
created_by int ID of the user who created the event
created_at int Event creation date in the format of Unix Timestamp
value_after array An array of the event changes. Event change properties are described here
value_before array An array of the event changes. Event change properties are described here
account_id int Account ID where the event is located in

Response example


{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/events?page=1&limit=250"
        },
        "next": {
            "href": "https://example.kommo.com/api/v4/events?page=2&limit=250"
        }
    },
    "_embedded": {
        "events": [
            {
                "id": "01geps58bpemnfacdx3r5hjjsr",
                "type": "lead_status_changed",
                "entity_id": 6107360,
                "entity_type": "lead",
                "created_by": 8375357,
                "created_at": 1665064411,
                "value_after": [
                    {
                        "lead_status": {
                            "id": 49366082,
                            "pipeline_id": 5597036
                        }
                    }
                ],
                "value_before": [
                    {
                        "lead_status": {
                            "id": 49366079,
                            "pipeline_id": 5597036
                        }
                    }
                ],
                "account_id": 30285908,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/events/01geps58bpemnfacdx3r5hjjsr"
                    }
                },
                "_embedded": {
                    "entity": {
                        "id": 6107360,
                        "_links": {
                            "self": {
                                "href": "https://example.kommo.com/api/v4/leads/6107360"
                            }
                        }
                    }
                }
            }
        ]
    }
}

Parameters for GET-parameters “with”

Parameter Description
contact_name If event belongs to a contact, you will receive the contact’s name as well as the ID in the response
lead_name If event belongs to a lead, you will receive the lead’s name as well as the ID in the response
company_name If event belongs to a company, you will receive the company’s name as well as the ID in the response
catalog_element_name If event belongs to a catalog element, you will receive the element’s name as well as the ID in the response
customer_name If event belongs to a customer, you will receive the customers’s name as well as the ID in the response
catalog_name If event belongs to a catalog element, you will receive the catalog’s name as well as the ID in the response

Getting an event by its ID

Method

GET /api/v4/events/{id}

Description

This method allows to get a particular event data by its ID.

Limitations

Method is available for all account users. The returned data depends on the user’s rights for the entity.

GET parameters

Parameter Data type Description
with string This parameter takes a string which may consist of several values separated by commas. This method supports the following parameters.

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code Case
200 Request successful
401 User is not authorized
402 Account is not paid

Response parameters

Method returns an event model. The properties of the model are listed below.

Parameter Data type Description
id string Event ID
type string Event type
entity_id int ID of the entity the event belongs to
entity_type string Type of the entity the event belongs to
created_by int ID of the user who created the event
created_at int Event creation date in the format of Unix Timestamp
value_after array An array of the event changes. Event change properties are described here
value_before array An array of the event changes. Event change properties are described here
account_id int Account ID where the event is located in

Response example


{
    "id": "01pz58t6p04ymgsgfbmfyfy1mf",
    "type": "lead_added",
    "entity_id": 26060763,
    "entity_type": "lead",
    "created_by": 939801,
    "created_at": 1888888888,
    "value_after": [
        {
            "note": {
                "id": 42743871
            }
        }
    ],
    "value_before": [],
    "account_id": 17079858,
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/events/01pz58t6p04ymgsgfbmfyfy1mf"
        }
    },
    "_embedded": {
        "entity": {
            "id": 26060763,
            "_links": {
                "self": {
                    "href": "https://example.kommo.com/api/v4/leads/26060763"
                }
            }
        }
    }
}

Parameters for GET-parameters “with”

Parameter Description
contact_name If event belongs to a contact, you will receive the contact’s name as well as the ID in the response
lead_name If event belongs to a lead, you will receive the lead’s name as well as the ID in the response
company_name If event belongs to a company, you will receive the company’s name as well as the ID in the response
catalog_element_name If event belongs to a catalog element, you will receive the element’s name as well as the ID in the response
customer_name If event belongs to a customer, you will receive the customers’s name as well as the ID in the response
catalog_name If event belongs to a catalog element, you will receive the catalog’s name as well as the ID in the response

Values for the before/after filter

The following values are available for the filter by before/after values at the moment:

  1. leads_statuses – filter by the lead status, available for the lead_status_changed event
  2. customers_statuses – filter by the customer status, available for the customer_status_changed event
  3. responsible_user_id – filter by the responsible user, available for the entity_responsible_changed event
  4. custom_field_values – filter by the enum field value,
    available for the custom_field_{FIELD_ID}_value_changed event, no more than 1 event type should be passed.
  5. value – filter by the exact value, available for the
    nps_rate_added, sale_field_changed, name_field_changed, ltv_field_changed, custom_field_value_changed events

Description of the filter by before/after values – leads_statuses

This filter allows to pass status and pipeline IDs to get only required lead status change events.

The request should be of the following composition:


filter[value_after][leads_statuses][0][pipeline_id]=13513&filter[value_after][leads_statuses][0][status_id]=17079863

In the following example we’ll get all lead status change events where the lead was moved to the status 17079863 of the pipeline 13513.

You can pass several values into the filter. Below, the example of composing such a filter using PHP is listed:



$filter = [
    'filter' => [
        'value_after' => [
            'leads_statuses' => [
                [
                    'pipeline_id' => 13513,
                    'status_id' => 17079863,
                ],
                [
                    'pipeline_id' => 13513,
                    'status_id' => 17079860,
                ],
            ],
        ],
    ],
];

$filterUri = http_build_query($filter);

//filter%5Bvalue_after%5D%5Bleads_statuses%5D%5B0%5D%5Bpipeline_id%5D=13513&filter%5Bvalue_after%5D%5Bleads_statuses%5D%5B0%5D%5Bstatus_id%5D=17079863&filter%5Bvalue_after%5D%5Bleads_statuses%5D%5B1%5D%5Bpipeline_id%5D=13513&filter%5Bvalue_after%5D%5Bleads_statuses%5D%5B1%5D%5Bstatus_id%5D=17079860

Description of the filter by before/after values – customers_statuses

This filter allows to pass status IDs to get only required customer status change events.

The request should be of the following composition:


filter[value_after][customers_statuses][0][status_id]=135751

In the following example we’ll get all customer status change events where customer was moved to the status 135751.

You can pass several values into the filter. Below, the example of composing such a filter using PHP is listed:



$filter = [
    'filter' => [
        'value_after' => [
            'customers_statuses' => [
                [
                    'status_id' => 135751,
                ],
                [
                    'status_id' => 135754,
                ],
            ],
        ],
    ],
];

$filterUri = http_build_query($filter);

//filter%5Bvalue_after%5D%5Bcustomers_statuses%5D%5B0%5D%5Bstatus_id%5D=135751&filter%5Bvalue_after%5D%5Bcustomers_statuses%5D%5B1%5D%5Bstatus_id%5D=135754

Description of the filter by before/after values – responsible_user_id

This filter allows to pass user IDs separated with commas to get only the required responsible user change events.

The request should be of the following composition:


filter[value_after][responsible_user_id]=448292

In the following example we’ll get all responsible user change events for the user ID 448292.

You can pass several values into the filter. Below, the example of composing such a filter using PHP is listed:



$filter = [
    'filter' => [
        'value_after' => [
            'responsible_user_id' => '3231,412314',
        ],
    ],
];

$filterUri = http_build_query($filter);

//filter%5Bvalue_after%5D%5Bresponsible_user_id%5D=3221%2C412314

Description of the filter by before/after values – custom_field_values

Filter by the enum field value, available for the custom_field_{FIELD_ID}_value_changed event, no more than 1 event type should be passed.

This filter allows to pass enum field values to get only required field values change events.

The request should be of the following composition:


filter[value_after][custom_field_values]=145&filter[type]=custom_field_57832_value_changed

In the following example we’ll get all field value change events for the field ID 57832 with enum ID 145.

You can pass several values into the filter. Below, the example of composing such a filter using PHP is listed:



$filter = [
    'filter' => [
        'value_after' => [
            'custom_field_values' => '145,157,202',
        ],
        'type' => 'custom_field_57832_value_changed',
    ],
];

$filterUri = http_build_query($filter);

filter%5Bvalue_after%5D%5Bcustom_field_values%5D=145%2C157%2C202&filter%5Btype%5D=custom_field_57832_value_changed

Description of the filter by before/after values – value

This filter allows to pass before/after values. It is only available for the following event types: nps_rate_added,
sale_field_changed, name_field_changed, ltv_field_changed, custom_field_value_changed.

The request should be of the following composition:


filter[value_after][value]=155&filter[type]=sale_field_changed&filter[entity]=lead

In the following example we’ll get all lead sale change events where lead sale became equal to 155.

Below, the example of composing such a filter using PHP is listed:



$filter = [
    'filter' => [
        'value_after' => [
            'value' => '155',
        ],
        'type' => 'sale_field_changed',
        'entity' => 'lead',
    ],
];

$filterUri = http_build_query($filter);

//filter%5Bvalue_after%5D%5Bvalue%5D=155&filter%5Btype%5D=sale_field_changed&filter%5Bentity%5D=lead

Data structures in the value_after and value_before fields

Data structure for the value_after and value_before fields depends on the event type and can have different values.

  • Event types: lead_deleted, lead_restored, contact_deleted, contact_restored, company_deleted, company_restored, customer_deleted, entity_merged, task_added, task_deleted, task_completed
    Parameter Type Description
    value_after|value_before array Empty array 
    
{
    "value_after": [],
    "value_before": []
}
  • Event type: task_text_changed
    Parameter Type Description
    value_after|value_before array Array of event changes (this event type always has one change in the array)
    value_after|value_before/0 object Change data object
    value_after|value_before/0/task object Task change data object
    value_after|value_before/0/task/text string Task text 
    
{
    "value_after": [
          {
            "task": {
              "text": "new task text"
            }
          }
        ],
    "value_before": [
          {
            "task": {
              "text": "old task text"
            }
          }
        ],
}
  • Event types: robot_replied and intent_identified
    Parameter Type Description
    value_after array Array of event changes (this event type always has one change in the array)
    value_after/0 object Change data object
    value_after/0/helpbot object Triggered intent data object
    value_after/0/helpbot/id int Intent ID 
    
{
    "value_after": [
          {
            "helpbot": {
              "id": 145
            }
          }
        ]
}
  • Event type: transaction_added
    Parameter Type Description
    value_after array Array of event changes (this event type always has one change in the array)
    value_after/0 object Change data object
    value_after/0/transaction object Transaction data object
    value_after/0/transaction/id int Transaction ID 
    
{
    "value_after": [
          {
            "transaction": {
              "id": 33675
            }
          }
        ]
}
  • Event types: lead_added, contact_added, company_added, customer_added, common_note_added, common_note_deleted, attachment_note_added, targeting_in_note_added, targeting_out_note_added, geo_note_added, service_note_added, site_visit_note_added, message_to_cashier_note_added, incoming_call, outgoing_call, incoming_sms, outgoing_sms, link_followed, task_result_added
    Parameter Type Description
    value_after array Array of event changes (this event type always has one change in the array)
    value_after/0 object Change data object
    value_after/0/note object Note data object
    value_after/0/note/id int Note ID 
    
{
    "value_after": [
          {
            "note": {
              "id": 7422564
            }
          }
        ]
}
  • Event type: nps_rate_added
    Parameter Type Description
    value_after array Array of event changes (this event type always has one change in the array)
    value_after/0 object Change data object
    value_after/0/nps object NPS rate data object
    value_after/0/nps/rate int Rate from 1 to 10 
    
{
    "value_after": [
          {
            "nps": {
              "rate": 7
            }
          }
        ]
}
  • Event types: incoming_chat_message and outgoing_chat_message
    Parameter Type Description
    value_after array Array of event changes (this event type always has one change in the array)
    value_after/0 object Change data object
    value_after/0/message object Message data object
    value_after/0/message/id string Message ID 
    
{
    "value_after": [
          {
            "message": {
              "id": "1508b51c-aab0-428e-9322-611d847ae747"
            }
          }
        ]
}
  • Event types: entity_tag_added and entity_tag_deleted
    Parameter Type Description
    value_after|value_before array Array of event changes
    value_after|value_before/0 object Change data object
    value_after|value_before/0/tag object Tag data object
    value_after|value_before/0/tag/name string Tag name 
    
{
    "value_after": [
          {
            "tag": {
              "name": "tag 1"
            }
          }
        ],
    "value_before": [
          {
            "tag": {
              "name": "tag2"
            }
          },
          {
            "tag": {
              "name": "tag2"
            }
          }
        ]
}
  • Event type: lead_status_changed
    Parameter Type Description
    value_after|value_before array Array of event changes
    value_after|value_before/0 object Change data object
    value_after|value_before/0/lead_status object Status data object
    value_after|value_before/0/lead_status/id int Status ID
    value_after|value_before/0/lead_status/pipeline_id int Pipeline ID 
    
{
    "value_after": [
          {
            "lead_status": {
              "id": 5233224,
              "pipeline_id": 437642,
            }
          }
        ],
    "value_before": [
          {
            "lead_status": {
              "id": 5233224,
              "pipeline_id": 437642,
            }
          }
        ]
}
  • Event type: customer_status_changed
    Parameter Type Description
    value_after|value_before array Array of event changes
    value_after|value_before/0 object Change data object
    value_after|value_before/0/customer_status object Status data object
    value_after|value_before/0/customer_status/id int Status ID 
    
{
    "value_after": [
          {
            "customer_status": {
              "id": 43832
            }
          }
        ],
    "value_before": [
          {
            "customer_status": {
              "id": 53791
            }
          }
        ]
}
  • Event types: customer_linked, customer_unlinked, company_linked, company_unlinked, contact_linked, contact_unlinked, lead_linked, lead_unlinked, entity_linked, entity_unlinked
    Parameter Type Description
    value_after|value_before array Array of event changes (this event type always has one change in the array)
    value_after|value_before/0 object Change data object
    value_after|value_before/0/link|unlink object Event data object
    value_after|value_before/0/link|unlink/entity object Entity object
    value_after|value_before/0/link|unlink/entity/type string Entity type
    value_after|value_before/0/link|unlink/entity/id int Entity ID 
    
{
    "value_after": [
          {
            "link": {
              "entity": {
                "type": "lead",
                "id": 6232965
              }
            }
          }
        ],
    "value_before": []
}
  • Event type: entity_responsible_changed
    Parameter Type Description
    value_after|value_before array Array of event changes
    value_after|value_before/0 object Change data object
    value_after|value_before/0/responsible_user object User data object
    value_after|value_before/0/responsible_user/id int User ID 
    
{
    "value_after": [
          {
            "responsible_user": {
              "id": 504329
            }
          }
        ],
    "value_before": [
          {
            "responsible_user": {
              "id": 37268
            }
          }
        ]
}
  • Event type: task_deadline_changed
    Parameter Type Description
    value_after|value_before array Array of event changes
    value_after|value_before/0 object Change data object
    value_after|value_before/0/task_deadline object Task deadline data object
    value_after|value_before/0/task_deadline/timestamp int Deadline timestamp 
    
{
    "value_after": [
          {
            "task_deadline": {
              "timestamp": 1573595900
            }
          }
        ],
    "value_before": [
          {
            "task_deadline": {
              "timestamp": 1573578700
            }
          }
        ]
}
  • Event type: task_type_changed
    Parameter Type Description
    value_after|value_before array Array of event changes
    value_after|value_before/0 object Change data object
    value_after|value_before/0/task_type object Task type data object
    value_after|value_before/0/task_type/id int Task type ID 
    
{
    "value_after": [
          {
            "task_type": {
              "id": 504329
            }
          }
        ],
    "value_before": [
          {
            "task_type": {
              "id": 37268
            }
          }
        ]
}
  • Event type: custom_field_value_changed
    Parameter Type Description
    value_after|value_before array Array of event changes
    value_after|value_before/0 object Change data object
    value_after|value_before/0/custom_field_value object Field change data object
    value_after|value_before/0/custom_field_value/field_id int Field ID
    value_after|value_before/0/custom_field_value/field_type int Field type
    value_after|value_before/0/custom_field_value/enum_id int|null enum value ID or null if the field doesn’t have enum values
    value_after|value_before/0/custom_field_value/text string Field value text 
    
{
  "value_after": [
    {
      "custom_field_value": {
        "field_id": 53728,
        "field_type": 8,
        "enum_id": 2352876,
        "text": "example1@test.com"
      }
    },
    {
      "custom_field_value": {
        "field_id": 53728,
        "field_type": 8,
        "enum_id": 2352876,
        "text": "example@test.com"
      }
    }
  ],
  "value_before": [
    {
      "custom_field_value": {
        "field_id": 53728,
        "field_type": 8,
        "enum_id": 193200,
        "text": "example@test.com"
      }
    }
  ]
}

Events types

Available event types

Value Description
lead_added New lead
lead_deleted Lead deleted
lead_restored Lead restored
lead_status_changed Lead stage changed
lead_linked Lead linking
lead_unlinked Lead unlinking
contact_added New contact
contact_deleted Contact deleted
contact_restored Contact restored
contact_linked Contact linking
contact_unlinked Contact unlinking
company_added New company
company_deleted Company deleted
company_restored Company restored
company_linked Company linking
company_unlinked Company unlinking
customer_added New customer
customer_deleted Customer deleted
customer_status_changed Customer stage changed
customer_linked Customer linking
customer_unlinked Customer unlinking
task_added New task
task_deleted Task deleted
task_completed Task completed
task_type_changed Task type change
task_text_changed Task text change
task_deadline_changed Task deadline change
task_result_added Task result
incoming_call Incoming call
outgoing_call Outgoing call
incoming_chat_message Incoming chat message
outgoing_chat_message Outgoing chat message
incoming_sms Incoming SMS
outgoing_sms Outgoing SMS
entity_tag_added Tags added
entity_tag_deleted Tags deleted
entity_linked Entity linking
entity_unlinked Entity unlinking
sale_field_changed “Sale” field change
name_field_changed “Name” field change
ltv_field_changed Total purchase value change
custom_field_value_changed Custom field change
entity_responsible_changed Responsible user change
robot_replied Robot’s reply
intent_identified Intent identified
nps_rate_added New NPS rate
link_followed Link followed
transaction_added Trasnaction added
common_note_added New note
common_note_deleted Note deleted
attachment_note_added New file attached to a note
targeting_in_note_added Adding to targeting
targeting_out_note_added Removed from targeting
geo_note_added New geo-tag note
service_note_added New service note
site_visit_note_added Site visit
message_to_cashier_note_added LifePay: message to cashier
entity_merged Enitiy merge completed
custom_field_{FIELD_ID}_value_changed Field change with passed field ID. If this type is passed, other types can’t be passed.

Getting events types

Method

GET /api/v4/events/types

Description

This method allows to get all available events types for the account.

Limitations

Method is available for all account users. The returned data depends on the user’s rights for the entity.

GET parameters

Parameter Data type Description
language_code string Language code that defines the language of the returned types. If none passed, the types will be returned in the language of the user performing the request. Available parameters – en, es, ru, pt.

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code Case
200 Request successful
401 User is not authorized
402 Account is not paid

Response parameters

Method returns a collection of event models. The properties of the model are listed below

Parameter Data type Description
key string Event type code
type int Event type ID
lang string Localized event name

Response example


{
    "_total_items": 35,
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/events/types?limit=6"
        }
    },
    "_embedded": {
        "events_types": [
            {
                "key": "lead_added",
                "type": 1,
                "lang": "New lead"
            },
            {
                "key": "lead_deleted",
                "type": 7,
                "lang": "Lead deleted"
            },
            ...
        ]
    }
}

Notes common information

Notes provide an ability to store additional structured or non-structured information in an entity.
Notes are displayed as events in the entity card. They can de added to: leads, contacts, companies, and customers.
Most of the times, notes are used by widgets to create additional time-based information.
They are always displayed chronologically in the card feed, so, if you need to add time-based information, we recommend using notes.
There are several note types: system notes (incoming/outgoing SMS, incoming/outgoing call, invoice is paid, contact created, etc.), created by the user (text and attachment notes).
In Kommo, there are 10 note types that can be edited.

Notes types

Available note types

Type Name
common Text note
call_in Incoming call
call_out Outgoing call
service_message Service message (created by the integration)
message_cashier Message to cashier
invoice_paid Invoice is paid
geolocation Text note with the geo-tag (added via Kommo mobile app)
sms_in Incoming SMS
sms_out Outgoing SMS
extended_service_message Extended service message (supports extended text length and can be minimized in the interface)

Note types that require the “params” array


Note type - common

"params": {
   "text": "Common note"
}

Note type - call_in

"params": {
   "uniq": "8f52d38a-5fb3-406d-93a3-a4832dc28f8b",
   "duration": 60,
   "source": "Twilio",
   "link": "https://example.com",
   "phone": "+14155551234"
}

Note type - call_out

"params": {
   "uniq": "8f52d38a-5fb3-406d-93a3-a4832dc28f8b",
   "duration": 60,
   "source": "Twilio",
   "link": "https://example.com",
   "phone": "+14155551234"
}

Note type - service_message and extended_service_message

"params": {
   "service": "Example service",
   "text": "Note text"
}

Note type - message_cashier

"params": {
    // Can have one of the following statuses:
    // - created
    // - shown
    // - canceled
    "status": "created",
    "text": "Note text"
}

Note type - invoice_paid

"params": {
   "icon_url": "https://example.com/icon.png",
   "service": "Netflix",
   "text": "Invoice is paid"
}

Note type - geolocation

"params": {
   "text": "Geolocation",
   "address": "222 Columbus Ave Ste 407",
   "longitude": "-13",
   "latitude": "32"
}

Note type - sms_in

"params": {
  "text": "New incoming SMS",
  "phone": "+14155551234"
}

Note type - sms_out

"params": {
   "text": "New outgoing SMS",
   "phone": "+14155551234"
}

Notes list by the entity type

Method

GET /api/v4/{entity_type}/notes

Description

This method allows to get a list of notes by the entity type.

Limitations

Method is available for all account users. The returned data depends on the user’s rights for the entity.

GET parameters

Parameter Data type Description
page int Sample page
limit int The number of the entities returned in the response of one request (limit – 250)
filter object Filter
filter[id] int|array Filter by the note ID. Either a single ID or an array of IDs can be passed
filter[note_type] string|array Filter by the note type
filter[updated_at] int|object Filter by the note edit date.
A timestamp can be passed, in that case, notes edited after the timestamp value will be returned.
Otherwise, the array of the following structure can be passed to filter between FROM and TO values filter[updated_at][from]=… and filter[updated_at][to]=…
order object List elements sorting.
Fields available to sort by: updated_at, id.
Values available to sort by: asc, desc.
Example: /api/v4/leads/notes?order[updated_at]=asc

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code Case
200 Request successful
401 User is not authorized
402 Account is not paid

Response parameters

Method returns a collection of note models. The properties of the model are listed below.

Parameter Data type Description
id int Note ID
entity_id int Note’s parent entity ID
created_by int ID of the user who created the note
updated_by int ID of the user who edited the note last
created_at int Note creation date in the format of Unix Timestamp
updated_at int Note edit date in the format of Unix Timestamp
responsible_user_id int Note responsible user ID
group_id int Group ID of the note responsible user
note_type string Note type
params object Note properties depending on the note type. Note properties are described here
account_id int Account ID where the note is located in

Response example


{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/leads/notes?filter%5Bid%5D%5B0%5D=42709325&filter%5Bid%5D%5B1%5D=42709842&page=1&limit=250"
        },
        "next": {
            "href": "https://example.kommo.com/api/v4/leads/notes?filter%5Bid%5D%5B0%5D=42709325&filter%5Bid%5D%5B1%5D=42709842&page=2&limit=250"
        }
    },
    "_embedded": {
        "notes": [
            {
                "id": 42709325,
                "entity_id": 26050861,
                "created_by": 940088,
                "updated_by": 940088,
                "created_at": 1540407495,
                "updated_at": 1540408317,
                "responsible_user_id": 939801,
                "group_id": 0,
                "note_type": "common",
                "params": {
                    "text": "Note text"
                },
                "account_id": 17079858,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/leads/26050861/notes/42709325"
                    }
                }
            },
            {
                "id": 42709842,
                "entity_id": 26053794,
                "created_by": 939801,
                "updated_by": 939801,
                "created_at": 1548280113,
                "updated_at": 1548280115,
                "responsible_user_id": 939801,
                "group_id": 0,
                "note_type": "attachment",
                "params": {
                    "original_name": "Screenshot 2020-05-16 at 13.12.20.png",
                    "attachment": "gijy_Screenshot_2020-05-16_v_13.12.20.png"
                },
                "account_id": 17079858,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/leads/26053794/notes/42709842"
                    }
                }
            }
        ]
    }
}

Getting a particular entity’s notes list by the entity ID

Method

GET /api/v4/{entity_type}/{entity_id}/notes

Description

This method allows to get a notes list by the ID of the parent entity.

Limitations

Method is available for all account users. The returned data depends on the user’s rights for the entity.

GET parameters

Parameter Data type Description
page int Sample page
limit int The number of the entities returned in the response of one request (limit – 250)
filter object Filter
filter[id] int|array Filter by the note ID. Either a single ID or an array of IDs can be passed
filter[note_type] string|array Filter by the note type
filter[updated_at] int|object Filter by the note edit date.
A timestamp can be passed, in that case, notes edited after the timestamp value will be returned.
Otherwise, the array of the following structure can be passed to filter between FROM and TO values filter[updated_at][from]=… and filter[updated_at][to]=…
order object List elements sorting.
Fields available to sort by: updated_at, id.
Values available to sort by: asc, desc.
Example: /api/v4/leads/notes?order[updated_at]=asc

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code Case
200 Request successful
401 User is not authorized
402 Account is not paid

Response parameters

Method returns a collection of note models. The properties of the model are listed below.

Parameter Data type Description
id int Note ID
entity_id int Note’s parent entity ID
created_by int ID of the user who created the note
updated_by int ID of the user who edited the note last
created_at int Note creation date in the format of Unix Timestamp
updated_at int Note edit date in the format of Unix Timestamp
responsible_user_id int Note responsible user ID
group_id int Group ID of the note responsible user
note_type string Note type
params object Note properties depending on the note type. Note properties are described here
account_id int Account ID where the note is located in

Response example


{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/leads/26050861/notes?limit=2&page=1"
        },
        "next": {
            "href": "https://example.kommo.com/api/v4/leads/26050861/notes?limit=2&page=2"
        }
    },
    "_embedded": {
        "notes": [
            {
                "id": 42709325,
                "entity_id": 26050861,
                "created_by": 940088,
                "updated_by": 940088,
                "created_at": 1540407495,
                "updated_at": 1540408317,
                "responsible_user_id": 939801,
                "group_id": 0,
                "note_type": "common",
                "params": {
                    "text": "Note text 2"
                },
                "account_id": 17079858,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/leads/26050861/notes/42709325"
                    }
                }
            },
            {
                "id": 42736075,
                "entity_id": 26050861,
                "created_by": 939801,
                "updated_by": 939801,
                "created_at": 1587555198,
                "updated_at": 1587555199,
                "responsible_user_id": 939801,
                "group_id": 0,
                "note_type": "common",
                "params": {
                    "text": "Note text"
                },
                "account_id": 17079858,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/leads/26050861/notes/42736075"
                    }
                }
            }
        ]
    }
}

Getting a note by its ID

Method

GET /api/v4/{entity_type}/notes/{id}

GET /api/v4/{entity_type}/{entity_id}/notes/{id}

Description

This method allows to get a particular note data by its ID.

Limitations

Method is available for all account users. The returned data depends on the user’s rights for the entity.

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code Case
200 Request successful
401 User is not authorized
402 Account is not paid

Response parameters

Method returns a note model. The properties of the model are listed below.

Parameter Data type Description
id int Note ID
entity_id int Note’s parent entity ID
created_by int ID of the user who created the note
updated_by int ID of the user who edited the note last
created_at int Note creation date in the format of Unix Timestamp
updated_at int Note edit date in the format of Unix Timestamp
responsible_user_id int Note responsible user ID
group_id int Group ID of the note responsible user
note_type string Note type
params object Note properties depending on the note type. Note properties are described here
account_id int Account ID where the note is located in

Response example


{
    "id": 42709325,
    "entity_id": 26050861,
    "created_by": 940088,
    "updated_by": 940088,
    "created_at": 1540407495,
    "updated_at": 1540408317,
    "responsible_user_id": 939801,
    "group_id": 0,
    "note_type": "common",
    "params": {
        "text": "Note text"
    },
    "account_id": 17079858,
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/leads/26050861/notes/42709325"
        }
    }
}

Adding notes

Method

POST /api/v4/{entity_type}/notes

POST /api/v4/{entity_type}/{entity_id}/notes

Description

This method allows to add multiple notes into the account.

Limitations

Method is available for all account users. The request success depends on the user’s rights for the entity.

Request header

Content-Type: application/json

Request parameters

Parameter Data type Description
entity_id int ID of the entity the note is added to. Is a mandatory parameter when adding a note to the entity. Not required if the method /api/v4/{entity_type}/{entity_id}/notes is used to add a note
note_type string Note type. Available note types
params object Note properties depending on the note type. Note properties are described here
request_id string Field that will be returned unchanged in the response and will not be saved. Is not a mandatory parameter

An example of the request


[
    {
        "entity_id": 167353,
        "note_type": "invoice_paid",
        "params": {
            "icon_url": "https://example.com/icon.png",
            "service": "Netflix",
            "text": "Subscription paid"
        }
    },
    {
        "entity_id": 167353,
        "note_type": "call_in",
        "params": {
            "uniq": "8f52d38a-5fb3-406d-93a3-a4832dc28f8b",
            "duration": 60,
            "source": "onlinePBX",
            "link": "https://example.com",
            "phone": "+14155551234"
        }
    },
    {
        "entity_id": 167353,
        "note_type": "call_out",
        "params": {
            "uniq": "8f52d38a-5fb3-406d-93a3-a4832dc28f8b",
            "duration": 60,
            "source": "onlinePBX",
            "link": "https://example.com",
            "phone": "+14155551234"
        }
    },
    {
        "entity_id": 167353,
        "note_type": "geolocation",
        "params": {
            "text": "Geo-tag note",
            "address": "222 Columbus Ave Ste 407",
            "longitude": "53.714816",
            "latitude": "91.423146"
        }
    }
]

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code Case
200 Notes added successfully
403 Insufficient rights to call this method
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method returns a collection of added notes.

Response example


{
    "_links": {
        "self": {
            "href": "http://example.kommo.com/api/v4/leads/notes"
        }
    },
    "_embedded": {
        "notes": [
            {
                "id": 76787983,
                "entity_id": 167353,
                "request_id": "0",
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/leads/167353/notes/76787983"
                    }
                }
            },
            {
                "id": 76787985,
                "entity_id": 167353,
                "request_id": "1",
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/leads/167353/notes/76787985"
                    }
                }
            },
            {
                "id": 76787987,
                "entity_id": 167353,
                "request_id": "2",
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/leads/167353/notes/76787987"
                    }
                }
            },
            {
                "id": 76787989,
                "entity_id": 167353,
                "request_id": "3",
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/leads/167353/notes/76787989"
                    }
                }
            }
        ]
    }
}

Editing notes

Method

PATCH /api/v4/{entity_type}/notes

PATCH /api/v4/{entity_type}/{entity_id}/notes

PATCH /api/v4/{entity_type}/{entity_id}/notes/{id}

Description

This method allows to edit multiple notes.
To edit a singular note, you can add the note ID into the method URL (/api/v4/{entity_type}/{entity_id}/notes/{id}).
When updating multiple notes, an array of note objects is passed. In case with a singular note, the note model is passed.

Limitations

Method is available for all account users. The request success depends on the user’s rights for the entity.

Request header

Content-Type: application/json

Request parameters

Parameter Data type Description
entity_id int ID of the entity the note is added to. Is a mandatory parameter when editing an entity note. Not required if the method /api/v4/{entity_type}/{entity_id}/notes is used to edit a note
note_type string Note type. Available note types
params object Note properties depending on the note type. Note properties are described here

An example of the request


[
    {
        "id": 76610421,
        "note_type": "sms_in",
        "params": {
            "text": "New incoming SMS",
            "phone": "+14155551234"
        }
    },
    {
        "id": 76610423,
        "note_type": "sms_out",
        "params": {
            "text": "New outbound SMS",
            "phone": "+14155551234"
        }
    }
]

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code Case
200 Notes edited successfully
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method returns a collection of edited notes or a note model. The parameters are similar to the add note request parameters.

Response example


{
    "_links": {
        "self": {
            "href": "https://example.kommo.com/api/v4/leads/notes"
        }
    },
    "_embedded": {
        "notes": [
            {
                "id": 76610421,
                "entity_id": 167353,
                "updated_at": 1588841241,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/leads/167353/notes/76610421"
                    }
                }
            },
            {
                "id": 76610423,
                "entity_id": 167353,
                "updated_at": 1588841241,
                "_links": {
                    "self": {
                        "href": "https://example.kommo.com/api/v4/leads/167353/notes/76610423"
                    }
                }
            }
        ]
    }
}