Get a List of CRM Items v 3.0 crm.[type].list

Scope: crm

Who can execute the method: a user with permission to view items of this CRM object type. For my company, a CRM administrator

The crm.<type>.list method returns a list of CRM items with filtering, sorting, and pagination. The object type is set by the <type> segment of the method name.

The list includes only the items the user can view. The method skips items the user has no access to without returning an error.

Method Name for the Object TypeMethod Name for the Object Type

For an SPA, the method name includes the type ID entityTypeId. SPA type IDs are returned by the crm.type.list method in the entityTypeId field.

The method name is written in lowercase: crm.smartinvoice.list, not crm.smartInvoice.list. If the name is written in a different case or contains a nonexistent entityTypeId, the method returns the "Method Not Found" error.

The number of items matching the same filter, without retrieving the list, is returned by the crm.<type>.aggregate method.

Method ParametersMethod Parameters

Required parameters are marked with *

The select ParameterThe select Parameter

Field names are written in camelCase: title, stageId, assignedById. Each object type has its own set of fields, which are described on these pages:

• deal fields
• lead fields
• contact fields
• company fields
• estimate fields
• invoice fields
• my company fields
• SPA fields

The list of fields is returned by the crm.<type>.field.list method.

Items in the response contain only the fields from select. The id field is not added automatically: include it in the list if you need it in the response. An empty array [] returns items as empty arrays. The asterisk * is not supported.

Related objects are requested by the field name without the Id suffix: assignedBy, stage, category, company. There are two ways:

• the whole related object name, for example, assignedBy, returns all fields of the object
• a dot-notation path, for example, assignedBy.firstName, stage.name, or company.title, returns only the selected fields

A path can contain only one dot: company.assignedBy.firstName causes an unknown field error. For employees — assignedBy, createdBy, and others — the name is stored in the firstName and lastName fields; there is no name field. For more information about related fields, see the REST 3.0 overview.

Custom fields are passed by name, for example, UF_CRM_1687529546. Their list is returned by the crm.<type>.field.custom.list method.

An unknown field in select — of the item itself or of a related object — causes the BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION error. The method does not silently skip such a field.

The filter ParameterThe filter Parameter

A filter is an array of conditions. The conditions in the array are combined with AND logic. A condition is written in one of these ways:

• ["field", "operator", value] — for example, ["opportunity", ">=", 10000]
• ["field", value] — the = operator, or in for an array value: ["id", [17, 19]]

Operators: =, !=, >, >=, <, <=, in, between. They are described in the REST 3.0 overview. There are no other operators: like and partial string search are not supported, and ["title", "=", "Supply"] finds only items with exactly this title.

You can filter by fields whose filterable attribute is true in the crm.<type>.field.list response. The value must match the field type:

Condition GroupsCondition Groups

To combine conditions with OR logic, pass a group — an object with these keys:

• type — the value filter. Inside the filter array, the key is required: a group without it causes the BITRIX_REST_V3_EXCEPTION_INVALIDFILTEREXCEPTION error
• logic — and or or, and by default
• negative — true inverts the group: items that do not meet the group condition match
• conditions — an array of conditions and nested groups

Example: items of pipeline 69 with an amount of 10,000 or more whose stage is DT1038_69:CLIENT or whose responsible person is user 1.

{
            "filter": [
                ["categoryId", "=", 69],
                ["opportunity", ">=", 10000],
                {
                    "type": "filter",
                    "logic": "or",
                    "conditions": [
                        ["stageId", "=", "DT1038_69:CLIENT"],
                        ["assignedById", "=", 1]
                    ]
                }
            ]
        }
        

If the whole filter is a single group, you can pass it as an object instead of an array: "filter": {"logic": "or", "conditions": [...]}. In this case, type can be omitted.

Filter limits:

• group nesting — up to 8 levels
• conditions and groups in a filter — up to 100
• values in all in lists of a filter — up to 1000

Related Fields in the FilterRelated Fields in the Filter

A condition can be set on a field of a related object using dot notation:

• a field of a linked CRM item — ["company.title", "=", "Müller GmbH"], ["myCompany.title", "=", "My company"], ["contact.name", "=", "Klaus"]
• a phone, email, website, or messenger value — ["phone.value", "=", "+49300000000"], for a deal — ["contact.phone.value", "=", "+49300000000"]. Only the = and in operators are available for these fields
• a UTM tag — ["utm.source", "=", "google"], the fields source, medium, campaign, content, term
• the time of the last communication — ["lastCommunication.callTime", ">", "2026-11-01T00:00:00+03:00"]

Fields of employees, stages, pipelines, and other reference lists cannot be filtered using dot notation: ["assignedBy.lastName", "=", "Schmidt"] causes the BITRIX_REST_V3_EXCEPTION_INVALIDFILTEREXCEPTION error. Filter by ID instead: assignedById, stageId, categoryId.

Empty Values and Multiple FieldsEmpty Values and Multiple Fields

The null value can be passed only with the = and != operators and only for fields that can be empty, for example, companyId, contactId, myCompanyId. For other fields, null causes a type validation error.

An empty link to a CRM item is stored in different ways: in the response, companyId is null, but the database may contain 0. To find all items without a company, check both values:

{
            "filter": [
                {
                    "type": "filter",
                    "logic": "or",
                    "conditions": [
                        ["companyId", "=", 0],
                        ["companyId", "=", null]
                    ]
                }
            ]
        }
        

For the multiple fields contactsId and observersId, only the =, !=, and in operators are available. The condition ["contactsId", "in", [5, 7]] finds items linked to at least one of the contacts. For ID fields of linked items, for example, contactId, the between operator is not supported.

The order ParameterThe order Parameter

An object where the key is a field name and the value is the sort direction. You can sort by fields whose sortable attribute is true in the crm.<type>.field.list response. Dot-notation fields of related objects and multiple fields, for example, contactsId, do not support sorting.

Possible direction values:

• ASC — ascending
• DESC — descending

The direction is case-insensitive: asc and ASC work the same way.

If several fields are passed, items are sorted by them in the listed order: {"stageId": "ASC", "opportunity": "DESC"}. If id is not in order, the method adds it as the last key with the ASC direction. As a result, the order of items with equal values does not change between pages.

String fields are sorted by value. For example, stageId is sorted by the stage code, not by the stage position in the pipeline.

Default: {"id": "ASC"}

The pagination ParameterThe pagination Parameter

Other keys in pagination cause an error. The method ignores the start parameter from the previous REST version.

Differences Between Object TypesDifferences Between Object Types

• crm.company.list does not return companies from the "My companies" list. Retrieve them with the crm.mycompany.list method
• crm.deal.list does not return recurring deal templates. The method also skips templates of recurring invoices and of SPAs with recurrence enabled
• for an SPA, the set of fields depends on the type settings: for example, without stages there is no stageId, and without client linking there are no companyId and contactId. For details, see the SPA fields page

Code ExamplesCode Examples

How to Use Examples in Documentation

The examples retrieve SPA items with the type ID 1038 from pipeline 69 with an amount of 10,000 or more — the first page of two items, sorted by amount in descending order. For a different object type, replace the method name according to the table above.

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"select":["id","title","stageId","opportunity","assignedBy.firstName"],"filter":[["categoryId","=",69],["opportunity",">=",10000]],"order":{"opportunity":"DESC"},"pagination":{"limit":2,"page":1}}' \
        https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/crm.smartprocess1038.list
        

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"select":["id","title","stageId","opportunity","assignedBy.firstName"],"filter":[["categoryId","=",69],["opportunity",">=",10000]],"order":{"opportunity":"DESC"},"pagination":{"limit":2,"page":1},"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/api/crm.smartprocess1038.list
        

import { ApiVersion, Text } from '@bitrix24/b24jssdk'
        import type { B24Frame } from '@bitrix24/b24jssdk'
        
        declare const $b24: B24Frame
        
        type ItemListResult = {
          items: {
            id: number
            title: string
            stageId: string
            opportunity: number
            assignedBy: {
              firstName: string
            }
          }[]
        }
        
        try {
          const response = await $b24.getHttpClient(ApiVersion.v3).call<ItemListResult>(
            'crm.smartprocess1038.list',
            {
              select: ['id', 'title', 'stageId', 'opportunity', 'assignedBy.firstName'],
              filter: [
                ['categoryId', '=', 69],
                ['opportunity', '>=', 10000],
              ],
              order: {
                opportunity: 'DESC',
              },
              pagination: {
                limit: 2,
                page: 1,
              },
            },
            Text.getUuidRfc4122()
          )
        
          if (!response.isSuccess) {
            console.error(response.getErrorMessages().join('; '))
          } else {
            const result = response.getData()!.result
            console.info('Items:', result.items)
          }
        } catch (error) {
          // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
          console.error(error)
        }
        

<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
        <script>
          async function listItems() {
            try {
              const $b24 = await B24Js.initializeB24Frame()
        
              const response = await $b24.getHttpClient(B24Js.ApiVersion.v3).call(
                'crm.smartprocess1038.list',
                {
                  select: ['id', 'title', 'stageId', 'opportunity', 'assignedBy.firstName'],
                  filter: [
                    ['categoryId', '=', 69],
                    ['opportunity', '>=', 10000],
                  ],
                  order: {
                    opportunity: 'DESC',
                  },
                  pagination: {
                    limit: 2,
                    page: 1,
                  },
                },
                B24Js.Text.getUuidRfc4122()
              )
        
              if (!response.isSuccess) {
                console.error(response.getErrorMessages().join('; '))
                return
              }
        
              const result = response.getData().result
              console.info('Items:', result.items)
            } catch (error) {
              // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
              console.error(error)
            }
          }
        
          document.addEventListener('DOMContentLoaded', listItems)
        </script>
        

from b24pysdk import Config
        from b24pysdk.errors import BitrixSDKException
        from b24pysdk.errors.v3 import BitrixAPIError
        
        method = "crm.smartprocess1038.list"
        Config().configure(api_v3_methods=Config().api_v3_methods | {method})
        
        try:
            response = bitrix_token.call_method(
                api_method=method,
                params={
                    "select": ["id", "title", "stageId", "opportunity", "assignedBy.firstName"],
                    "filter": [
                        ["categoryId", "=", 69],
                        ["opportunity", ">=", 10000],
                    ],
                    "order": {"opportunity": "DESC"},
                    "pagination": {"limit": 2, "page": 1},
                },
                prefer_version=3,
            )
            for item in response["result"]["items"]:
                print(item["id"], item["title"], item["opportunity"])
        except BitrixAPIError as error:
            print(
                "Bitrix API error",
                f"code: {error.code}",
                f"message: {error.error.message}",
                sep="\n",
            )
        except BitrixSDKException as error:
            print(f"Bitrix SDK error: {error.message}")
        except Exception as error:
            print(f"Unexpected error: {error}")
        

try {
            $response = $b24Service
                ->core
                ->call(
                    'crm.smartprocess1038.list',
                    [
                        'select' => ['id', 'title', 'stageId', 'opportunity', 'assignedBy.firstName'],
                        'filter' => [
                            ['categoryId', '=', 69],
                            ['opportunity', '>=', 10000],
                        ],
                        'order' => [
                            'opportunity' => 'DESC',
                        ],
                        'pagination' => [
                            'limit' => 2,
                            'page' => 1,
                        ],
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            print_r($result);
        } catch (Throwable $e) {
            echo $e->getMessage();
        }
        

BX24.callMethod(
            'crm.smartprocess1038.list',
            {
                select: ['id', 'title', 'stageId', 'opportunity', 'assignedBy.firstName'],
                filter: [
                    ['categoryId', '=', 69],
                    ['opportunity', '>=', 10000],
                ],
                order: {
                    opportunity: 'DESC',
                },
                pagination: {
                    limit: 2,
                    page: 1,
                },
            },
            result => {
                if (result.error())
                    console.error(result.error());
                else
                    console.dir(result.data());
            }
        );
        

require_once('crest.php');
        
        $result = CRest::call(
            'crm.smartprocess1038.list',
            [
                'select' => ['id', 'title', 'stageId', 'opportunity', 'assignedBy.firstName'],
                'filter' => [
                    ['categoryId', '=', 69],
                    ['opportunity', '>=', 10000],
                ],
                'order' => [
                    'opportunity' => 'DESC',
                ],
                'pagination' => [
                    'limit' => 2,
                    'page' => 1,
                ],
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';
        

// client and ctx are already created — see the Go SDK section
        res, err := client.Core().Call(ctx, "crm.smartprocess1038.list", b24.Params{
        	"select": []string{"id", "title", "stageId", "opportunity", "assignedBy.firstName"},
        	"filter": []any{
        		[]any{"categoryId", "=", 69},
        		[]any{"opportunity", ">=", 10000},
        	},
        	"order": b24.Params{
        		"opportunity": "DESC",
        	},
        	"pagination": b24.Params{
        		"limit": 2,
        		"page":  1,
        	},
        }, b24.WithIdempotent())
        if err != nil {
        	return fmt.Errorf("crm.smartprocess1038.list: %w", err)
        }
        
        raw, ok := b24.Unwrap(res.Result, "items")
        if !ok {
        	return fmt.Errorf("response has no items key")
        }
        
        var items []struct {
        	ID          int     `json:"id"`
        	Title       string  `json:"title"`
        	StageID     string  `json:"stageId"`
        	Opportunity float64 `json:"opportunity"`
        	AssignedBy  struct {
        		FirstName string `json:"firstName"`
        	} `json:"assignedBy"`
        }
        if err := json.Unmarshal(raw, &items); err != nil {
        	return fmt.Errorf("parse response: %w", err)
        }
        for _, it := range items {
        	fmt.Println(it.ID, it.Title, it.Opportunity)
        }
        

Response HandlingResponse Handling

HTTP status: 200

{
            "result": {
                "items": [
                    {
                        "id": 21,
                        "title": "Office equipment repair",
                        "stageId": "DT1038_69:CLIENT",
                        "opportunity": 95000,
                        "assignedBy": {
                            "firstName": "Anna"
                        }
                    },
                    {
                        "id": 19,
                        "title": "Cartridge supply",
                        "stageId": "DT1038_69:PREPARATION",
                        "opportunity": 48000,
                        "assignedBy": {
                            "firstName": "Anna"
                        }
                    }
                ]
            },
            "time": {
                "start": 1793706441,
                "finish": 1793706441.814752,
                "duration": 0.8147521018981934,
                "processing": 0,
                "date_start": "2026-11-03T14:47:21+03:00",
                "date_finish": "2026-11-03T14:47:21+03:00",
                "operating_reset_at": 1793706780,
                "operating": 0.14652299880981445
            }
        }
        

Returned DataReturned Data

Error HandlingError Handling

HTTP status: 400

{
            "error": {
                "code": "BITRIX_REST_V3_EXCEPTION_INVALIDFILTEREXCEPTION",
                "message": "Invalid filter \"{\"logic\":\"or\",\"conditions\":[[\"id\",17],[\"id\",\"in\",[21,23]]]}\"."
            }
        }
        

Possible Error CodesPossible Error Codes

Request Validation ErrorsRequest Validation Errors

Error Code: BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION

Filter ErrorsFilter Errors

Error Code: BITRIX_REST_V3_EXCEPTION_INVALIDFILTEREXCEPTION

Unknown Filter OperatorUnknown Filter Operator

Error Code: BITRIX_REST_V3_EXCEPTION_UNKNOWNFILTEROPERATOREXCEPTION

Unknown Field ErrorUnknown Field Error

Error Code: BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION

Select Format ErrorSelect Format Error

Error Code: BITRIX_REST_V3_EXCEPTION_INVALIDSELECTEXCEPTION

Sort ErrorSort Error

Error Code: BITRIX_REST_V3_EXCEPTION_INVALIDORDEREXCEPTION

Pagination ErrorPagination Error

Error Code: BITRIX_REST_V3_EXCEPTION_INVALIDPAGINATIONEXCEPTION

Method Not FoundMethod Not Found

Error Code: BITRIX_REST_V3_EXCEPTION_METHODNOTFOUNDEXCEPTION, HTTP status: 404

Statuses and System Error CodesStatuses and System Error Codes

HTTP Status: 4xx, 5xx

The errors described below are returned by the REST API itself, not by the logic of a specific method. They can arrive in response to any method.

Continue LearningContinue Learning

• CRM Items in REST 3.0: Overview of Methods
• Create a CRM Item v 3.0 crm.[type].add
• Update a CRM Item v 3.0 crm.[type].update
• Get a CRM Item by ID v 3.0 crm.[type].get
• Delete a CRM Item v 3.0 crm.[type].delete
• Count CRM Items v 3.0 crm.[type].aggregate
• Get Field Descriptions v 3.0 crm.[type].field.list