---
updatedAt: 2025-12-09T15:37:11.000Z
---

Fetch the complete documentation index at: https://developers.kommo.com/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# Contacts list

This method allows to get a list of contacts in the account

**Limitations**\
Method is available in correspondence to the user rights.

**“with” Parameters**

| Parameter         | Description                                                    |
| :---------------- | :------------------------------------------------------------- |
| leads             | Adds info on the leads linked to the contact into the response |
| catalog\_elements | Adds lists elements linked to the contact into the response    |

# Find contact by a phone number

<Callout icon="📘" theme="info">
  You can easily filter your contacts by `?query={CONTACT_PHONE}` parameter to get them by a phone number.
</Callout>

**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

**Response parameters**

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Parameter
      </th>

      <th>
        Data type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        id
      </td>

      <td>
        int
      </td>

      <td>
        Contact ID
      </td>
    </tr>

    <tr>
      <td>
        name
      </td>

      <td>
        string
      </td>

      <td>
        Contact fullname
      </td>
    </tr>

    <tr>
      <td>
        first_name
      </td>

      <td>
        string
      </td>

      <td>
        Contact first name
      </td>
    </tr>

    <tr>
      <td>
        last_name
      </td>

      <td>
        string
      </td>

      <td>
        Contact last name
      </td>
    </tr>

    <tr>
      <td>
        responsible_user_id
      </td>

      <td>
        int
      </td>

      <td>
        Contact responsible user ID
      </td>
    </tr>

    <tr>
      <td>
        group_id
      </td>

      <td>
        int
      </td>

      <td>
        Group ID of the contact responsible user
      </td>
    </tr>

    <tr>
      <td>
        created_by
      </td>

      <td>
        int
      </td>

      <td>
        ID of the user who created the contact
      </td>
    </tr>

    <tr>
      <td>
        updated_by
      </td>

      <td>
        int
      </td>

      <td>
        ID of the user who updated the contact last
      </td>
    </tr>

    <tr>
      <td>
        created_at
      </td>

      <td>
        int
      </td>

      <td>
        Contact creation date in the format of Unix Timestamp
      </td>
    </tr>

    <tr>
      <td>
        updated_at
      </td>

      <td>
        int
      </td>

      <td>
        Contact update date in the format of Unix Timestamp
      </td>
    </tr>

    <tr>
      <td>
        closest_task_at
      </td>

      <td>
        int
      </td>

      <td>
        Date of the closest open task in the format of Unix Timestamp
      </td>
    </tr>

    <tr>
      <td>
        custom_fields_values
      </td>

      <td>
        array|null
      </td>

      <td>
        An array of the current contact custom fields’ values
      </td>
    </tr>

    <tr>
      <td>
        account_id
      </td>

      <td>
        int
      </td>

      <td>
        Account ID where the contact is located in
      </td>
    </tr>

    <tr>
      <td>
        _embedded
      </td>

      <td>
        object
      </td>

      <td>
        Embedded entities data
      </td>
    </tr>

    <tr>
      <td>
        _embedded[tags]
      </td>

      <td>
        array
      </td>

      <td>
        Contact tags data array
      </td>
    </tr>

    <tr>
      <td>
        _embedded[tags][0]
      </td>

      <td>
        object
      </td>

      <td>
        Contact tag model
      </td>
    </tr>

    <tr>
      <td>
        _embedded[tags][0][id]
      </td>

      <td>
        int
      </td>

      <td>
        Tag ID
      </td>
    </tr>

    <tr>
      <td>
        _embedded[tags][0][name]
      </td>

      <td>
        string
      </td>

      <td>
        Tag name
      </td>
    </tr>

    <tr>
      <td>
        _embedded[tags][0][color]
      </td>

      <td>
        string/null
      </td>

      <td>
        Tag color
      </td>
    </tr>

    <tr>
      <td>
        _embedded[companies]
      </td>

      <td>
        array
      </td>

      <td>
        Contact tag model
      </td>
    </tr>

    <tr>
      <td>
        _embedded[companies][0]
      </td>

      <td>
        object
      </td>

      <td>
        Linked company data
      </td>
    </tr>

    <tr>
      <td>
        _embedded[companies][0][id]
      </td>

      <td>
        int
      </td>

      <td>
        Linked company ID
      </td>
    </tr>

    <tr>
      <td>
        _embedded[leads]
      </td>

      <td>
        array
      </td>

      <td>
        **GET parameter “with” is required.**  
        Linked leads data array
      </td>
    </tr>

    <tr>
      <td>
        _embedded[leads][0]
      </td>

      <td>
        object
      </td>

      <td>
        Linked lead data
      </td>
    </tr>

    <tr>
      <td>
        _embedded[leads][0][id]
      </td>

      <td>
        int
      </td>

      <td>
        Linked lead ID
      </td>
    </tr>

    <tr>
      <td>
        _embedded[catalog_elements][catalog_elements]
      </td>

      <td>
        array
      </td>

      <td>
        **GET parameter “with” is required.**  
        Linked lists’ elements data array
      </td>
    </tr>

    <tr>
      <td>
        _embedded[catalog_elements][0]
      </td>

      <td>
        object
      </td>

      <td>
        Linked list element data
      </td>
    </tr>

    <tr>
      <td>
        _embedded[catalog_elements][0][id]
      </td>

      <td>
        int
      </td>

      <td>
        Linked element ID
      </td>
    </tr>

    <tr>
      <td>
        _embedded[catalog_elements][0][metadata]
      </td>

      <td>
        object
      </td>

      <td>
        Meta-data of the element
      </td>
    </tr>

    <tr>
      <td>
        _embedded[catalog_elements][0][quantity]
      </td>

      <td>
        int
      </td>

      <td>
        Linked elements quantity
      </td>
    </tr>

    <tr>
      <td>
        _embedded[catalog_elements][0][catalog_id][catalog_id]
      </td>

      <td>
        int
      </td>

      <td>
        ID of the linked element’s list
      </td>
    </tr>
  </tbody>
</Table>

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "kommo-api-references",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://{subdomain}.kommo.com",
      "variables": {
        "subdomain": {
          "default": "subdomain"
        }
      }
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "oauth2",
        "flows": {}
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/api/v4/contacts": {
      "get": {
        "summary": "Contacts List",
        "description": "This method allows to get a list of contacts in the account",
        "operationId": "contacts-list",
        "parameters": [
          {
            "name": "with",
            "in": "query",
            "description": "This parameter takes a string which may consist of several values separated by commas.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Sample page",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "The number of the entities returned in the response of one request (limit – 250)",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "query",
            "in": "query",
            "description": "String or integer. Search query will perform a search by custom fields values.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "order[updated_at]",
            "in": "query",
            "description": "List elements sorting",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ]
            }
          },
          {
            "name": "order[id]",
            "in": "query",
            "description": "List elements sorting",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ]
            }
          },
          {
            "name": "filter[id][]",
            "in": "query",
            "description": "Filter by contact ID",
            "schema": {
              "type": "array",
              "items": {
                "type": "integer",
                "format": "int32"
              }
            }
          },
          {
            "name": "filter[name][]",
            "in": "query",
            "description": "Filter by contact name",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          {
            "name": "filter[created_by][]",
            "in": "query",
            "description": "Filter by ID of the user who added the contact(s).",
            "schema": {
              "type": "array",
              "items": {
                "type": "integer",
                "format": "int32"
              }
            }
          },
          {
            "name": "filter[updated_by][]",
            "in": "query",
            "description": "Filter by ID of the user who updated the contact last.",
            "schema": {
              "type": "array",
              "items": {
                "type": "integer",
                "format": "int32"
              }
            }
          },
          {
            "name": "filter[responsible_user_id][]",
            "in": "query",
            "description": "Filter by ID of the contact responsible user",
            "schema": {
              "type": "array",
              "items": {
                "type": "integer",
                "format": "int32"
              }
            }
          },
          {
            "name": "filter[updated_at][from]",
            "in": "query",
            "description": "Filter by the date in Unix Timestamp format when the contact was updated. As a response you will get all the contacts updated after the date.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "filter[updated_at][to]",
            "in": "query",
            "description": "Filter by the date in Unix Timestamp format when the contact was updated. As a response you will get all the contacts updated before the date.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "filter[closest_task_at][from]",
            "in": "query",
            "description": "Filter contacts by the date in Unix Timestamp format of the task closest to completion.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "filter[closest_task_at][to]",
            "in": "query",
            "description": "Filter contacts by the date in Unix Timestamp format of the task closest to completion.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Request successful": {
                    "value": "{\n    \"_page\": 1,\n    \"_links\": {\n        \"self\": {\n            \"href\": \"https://devteam.kommo.com/api/v4/contacts\"\n        }\n    },\n    \"_embedded\": {\n        \"contacts\": [\n            {\n                \"id\": 406322,\n                \"name\": \"Sam\",\n                \"first_name\": \"Sam\",\n                \"last_name\": \"\",\n                \"responsible_user_id\": 8375357,\n                \"group_id\": 0,\n                \"created_by\": 8375357,\n                \"updated_by\": 8375357,\n                \"created_at\": 1686670710,\n                \"updated_at\": 1686670710,\n                \"closest_task_at\": null,\n                \"is_deleted\": false,\n                \"is_unsorted\": false,\n                \"custom_fields_values\": [\n                    {\n                        \"field_id\": 178382,\n                        \"field_name\": \"Phone\",\n                        \"field_code\": \"PHONE\",\n                        \"field_type\": \"multitext\",\n                        \"values\": [\n                            {\n                                \"value\": \"19651796212\",\n                                \"enum_id\": 126290,\n                                \"enum_code\": \"WORK\"\n                            }\n                        ]\n                    }\n                ],\n                \"account_id\": 31361463,\n                \"_links\": {\n                    \"self\": {\n                        \"href\": \"https://devteam.kommo.com/api/v4/contacts/406322\"\n                    }\n                },\n                \"_embedded\": {\n                    \"tags\": [],\n                    \"companies\": [\n                        {\n                            \"id\": 406320,\n                            \"_links\": {\n                                \"self\": {\n                                    \"href\": \"https://devteam.kommo.com/api/v4/companies/406320\"\n                                }\n                            }\n                        }\n                    ]\n                }\n            },\n            {\n                \"id\": 510866,\n                \"name\": \"Adam\",\n                \"first_name\": \"Adam\",\n                \"last_name\": \"\",\n                \"responsible_user_id\": 8375357,\n                \"group_id\": 0,\n                \"created_by\": 0,\n                \"updated_by\": 0,\n                \"created_at\": 1668784888,\n                \"updated_at\": 1686754687,\n                \"closest_task_at\": null,\n                \"is_deleted\": false,\n                \"is_unsorted\": false,\n                \"custom_fields_values\": null,\n                \"account_id\": 31361463,\n                \"_links\": {\n                    \"self\": {\n                        \"href\": \"https://devteam.kommo.com/api/v4/contacts/510866\"\n                    }\n                },\n                \"_embedded\": {\n                    \"tags\": [],\n                    \"companies\": [\n                        {\n                            \"id\": 510864,\n                            \"_links\": {\n                                \"self\": {\n                                    \"href\": \"https://devteam.kommo.com/api/v4/companies/510864\"\n                                }\n                            }\n                        }\n                    ]\n                }\n            }\n        ]\n    }\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "_page": {
                      "type": "integer",
                      "example": 1,
                      "default": 0
                    },
                    "_links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "object",
                          "properties": {
                            "href": {
                              "type": "string",
                              "example": "https://devteam.kommo.com/api/v4/contacts"
                            }
                          }
                        }
                      }
                    },
                    "_embedded": {
                      "type": "object",
                      "properties": {
                        "contacts": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "integer",
                                "example": 406322,
                                "default": 0
                              },
                              "name": {
                                "type": "string",
                                "example": "Sam"
                              },
                              "first_name": {
                                "type": "string",
                                "example": "Sam"
                              },
                              "last_name": {
                                "type": "string",
                                "example": ""
                              },
                              "responsible_user_id": {
                                "type": "integer",
                                "example": 8375357,
                                "default": 0
                              },
                              "group_id": {
                                "type": "integer",
                                "example": 0,
                                "default": 0
                              },
                              "created_by": {
                                "type": "integer",
                                "example": 8375357,
                                "default": 0
                              },
                              "updated_by": {
                                "type": "integer",
                                "example": 8375357,
                                "default": 0
                              },
                              "created_at": {
                                "type": "integer",
                                "example": 1686670710,
                                "default": 0
                              },
                              "updated_at": {
                                "type": "integer",
                                "example": 1686670710,
                                "default": 0
                              },
                              "closest_task_at": {},
                              "is_deleted": {
                                "type": "boolean",
                                "example": false,
                                "default": true
                              },
                              "is_unsorted": {
                                "type": "boolean",
                                "example": false,
                                "default": true
                              },
                              "custom_fields_values": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "field_id": {
                                      "type": "integer",
                                      "example": 178382,
                                      "default": 0
                                    },
                                    "field_name": {
                                      "type": "string",
                                      "example": "Phone"
                                    },
                                    "field_code": {
                                      "type": "string",
                                      "example": "PHONE"
                                    },
                                    "field_type": {
                                      "type": "string",
                                      "example": "multitext"
                                    },
                                    "values": {
                                      "type": "array",
                                      "items": {
                                        "type": "object",
                                        "properties": {
                                          "value": {
                                            "type": "string",
                                            "example": "19651796212"
                                          },
                                          "enum_id": {
                                            "type": "integer",
                                            "example": 126290,
                                            "default": 0
                                          },
                                          "enum_code": {
                                            "type": "string",
                                            "example": "WORK"
                                          }
                                        }
                                      }
                                    }
                                  }
                                }
                              },
                              "account_id": {
                                "type": "integer",
                                "example": 31361463,
                                "default": 0
                              },
                              "_links": {
                                "type": "object",
                                "properties": {
                                  "self": {
                                    "type": "object",
                                    "properties": {
                                      "href": {
                                        "type": "string",
                                        "example": "https://devteam.kommo.com/api/v4/contacts/406322"
                                      }
                                    }
                                  }
                                }
                              },
                              "_embedded": {
                                "type": "object",
                                "properties": {
                                  "tags": {
                                    "type": "array"
                                  },
                                  "companies": {
                                    "type": "array",
                                    "items": {
                                      "type": "object",
                                      "properties": {
                                        "id": {
                                          "type": "integer",
                                          "example": 406320,
                                          "default": 0
                                        },
                                        "_links": {
                                          "type": "object",
                                          "properties": {
                                            "self": {
                                              "type": "object",
                                              "properties": {
                                                "href": {
                                                  "type": "string",
                                                  "example": "https://devteam.kommo.com/api/v4/companies/406320"
                                                }
                                              }
                                            }
                                          }
                                        }
                                      }
                                    }
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "401",
            "content": {
              "application/json": {
                "examples": {
                  "User is not authorized": {
                    "value": "{}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```