How to Filter Items by Stage Name
Scope:
crm, user_briefWho can execute the method: a user with read access to CRM entities
If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the MCP server so that the assistant can use the official REST documentation.
The stage name is not stored in the "Stage" field of the CRM entity. The "Stage" field contains an identifier. You can correlate the name and identifier of the stage using methods for working with reference books — system fields of the "list" type. To search for items by stage name, we will sequentially execute three methods:
- crm.category.list — retrieve the funnel identifier
- crm.status.list — retrieve the stage identifier in the funnel
- crm.item.list — retrieve the list of items at the stage
1. Retrieve the Funnel Identifier
We will use the crm.category.list method with the parameters:
entityTypeId— set to2for deals. This is the identifier for the object type. To find out the identifier of the smart process, execute the crm.enum.ownertype method without parameters.
How to Use Examples in Documentation
JS
PHP
BX24.callMethod(
"crm.category.list",
{
entityTypeId: 2,
},
);
require_once('crest.php');
$result = CRest::call(
'crm.category.list',
[
'entityTypeId' => 2
]
);
As a result, we obtained the deal funnels. We will identify the required funnel by its name in the name field. The funnel identifier will be taken from the id field.
{
"result": {
"categories": [
{
"id": 9,
"name": "Funnel with Original Name",
"sort": 200,
"entityTypeId": 2,
"isDefault": "N",
"originId": "",
"originatorId": ""
},
{
"id": 10,
"name": "Lead Route",
"sort": 200,
"entityTypeId": 2,
"isDefault": "N",
"originId": "",
"originatorId": ""
},
{
"id": 11,
"name": "Path to Success",
"sort": 200,
"entityTypeId": 2,
"isDefault": "N",
"originId": "",
"originatorId": ""
},
{
"id": 0,
"name": "General",
"sort": 300,
"entityTypeId": 2,
"isDefault": "Y"
}
]
},
"total": 4,
}
2. Retrieve the Stage Identifier
We will use the crm.status.list method with the filter:
ENTITY_ID— set toDEAL_STAGE_10, where10is the funnel identifier obtained in step 1.
To obtain stages of the smart process, use a formula likeDYNAMIC_185_STAGE_11, where185is theIDof the smart process, and11is theIDof the funnel.
If theIDof the funnel is0, make the request for stages without adding_ID.
JS
PHP
BX24.callMethod(
"crm.status.list",
{
filter: { "ENTITY_ID": "DEAL_STAGE_10"}
},
);
require_once('crest.php');
$result = CRest::call(
'crm.status.list',
[
'filter' => [
'ENTITY_ID' => 'DEAL_STAGE_10'
]
]
);
As a result, we obtained a list of stages. We will identify the required stage by its name in the NAME field. The stage identifier will be taken from the STATUS_ID field.
{
"result": [
{
"ID": "331",
"ENTITY_ID": "DEAL_STAGE_10",
"STATUS_ID": "C10:NEW",
"NAME": "New",
"NAME_INIT": "New",
"SORT": "10",
"SYSTEM": "Y",
"CATEGORY_ID": "5",
"COLOR": "#39A8EF",
"SEMANTICS": null,
"EXTRA": {
"SEMANTICS": "process",
"COLOR": "#39A8EF"
}
},
{
"ID": "333",
"ENTITY_ID": "DEAL_STAGE_10",
"STATUS_ID": "C10:PREPARATION",
"NAME": "Document Preparation",
"NAME_INIT": "",
"SORT": "20",
"SYSTEM": "N",
"CATEGORY_ID": "5",
"COLOR": "#2FC6F6",
"SEMANTICS": null,
"EXTRA": {
"SEMANTICS": "process",
"COLOR": "#2FC6F6"
}
},
{
"ID": "335",
"ENTITY_ID": "DEAL_STAGE_10",
"STATUS_ID": "C10:PREPAYMENT_INVOICE",
"NAME": "Agreement",
"NAME_INIT": "",
"SORT": "30",
"SYSTEM": "N",
"CATEGORY_ID": "5",
"COLOR": "#55d0e0",
"SEMANTICS": null,
"EXTRA": {
"SEMANTICS": "process",
"COLOR": "#55d0e0"
}
},
{
"ID": "337",
"ENTITY_ID": "DEAL_STAGE_10",
"STATUS_ID": "C10:EXECUTING",
"NAME": "In Progress",
"NAME_INIT": "",
"SORT": "40",
"SYSTEM": "N",
"CATEGORY_ID": "5",
"COLOR": "#47E4C2",
"SEMANTICS": null,
"EXTRA": {
"SEMANTICS": "process",
"COLOR": "#47E4C2"
}
},
{
"ID": "339",
"ENTITY_ID": "DEAL_STAGE_10",
"STATUS_ID": "C10:FINAL_INVOICE",
"NAME": "Final Invoice",
"NAME_INIT": "",
"SORT": "50",
"SYSTEM": "N",
"CATEGORY_ID": "5",
"COLOR": "#FFA900",
"SEMANTICS": null,
"EXTRA": {
"SEMANTICS": "process",
"COLOR": "#FFA900"
}
},
{
"ID": "341",
"ENTITY_ID": "DEAL_STAGE_10",
"STATUS_ID": "C10:WON",
"NAME": "Deal Successful",
"NAME_INIT": "Deal Successful",
"SORT": "60",
"SYSTEM": "Y",
"CATEGORY_ID": "5",
"COLOR": "#7BD500",
"SEMANTICS": "S",
"EXTRA": {
"SEMANTICS": "success",
"COLOR": "#7BD500"
}
},
{
"ID": "343",
"ENTITY_ID": "DEAL_STAGE_10",
"STATUS_ID": "C10:LOSE",
"NAME": "Deal Failed",
"NAME_INIT": "Deal Failed",
"SORT": "70",
"SYSTEM": "Y",
"CATEGORY_ID": "5",
"COLOR": "#FF5752",
"SEMANTICS": "F",
"EXTRA": {
"SEMANTICS": "failure",
"COLOR": "#FF5752"
}
},
{
"ID": "345",
"ENTITY_ID": "DEAL_STAGE_10",
"STATUS_ID": "C10:APOLOGY",
"NAME": "Analysis of Failure Reason",
"NAME_INIT": "",
"SORT": "80",
"SYSTEM": "N",
"CATEGORY_ID": "5",
"COLOR": "#FF5752",
"SEMANTICS": "F",
"EXTRA": {
"SEMANTICS": "apology",
"COLOR": "#FF5752"
}
}
],
"total": 8,
}
3. Retrieve the List of Items at the Stage
We will use the crm.item.list method with the parameters:
entityTypeId— set to2for deals. This is the identifier for the object type. To find out the identifier of the smart process, execute the crm.enum.ownertype method without parameters.filter[stageId]— set toC10:PREPAYMENT_INVOICE. This is the identifier of the stage obtained in step 2.select[]— specify the fields of the items you want to retrieve. Without theselectparameter, all fields, including custom ones, will be returned.
JS
PHP
BX24.callMethod(
'crm.item.list',
{
entityTypeId: 2,
select: [
"id",
"title",
"assignedById",
"opportunity",
],
filter: {
"stageId": ["C10:PREPAYMENT_INVOICE"],
},
},
);
require_once('crest.php');
$result = CRest::call(
'crm.item.list',
[
'entityTypeId' => 2,
'select' => [
"id",
"title",
"assignedById",
"opportunity",
],
'filter' => [
"stageId" => ["C10:PREPAYMENT_INVOICE"],
],
]
);
As a result, we obtained a list of items at the requested stage.
{
"result": {
"items": [
{
"id": 5111,
"assignedById": 1,
"title": "Purchase of Stoves",
"opportunity": 500
},
{
"id": 5199,
"assignedById": 29,
"title": "Purchase of Heaters",
"opportunity": 250
},
{
"id": 5257,
"assignedById": 29,
"title": "Purchase of Bread Makers",
"opportunity": 200
},
{
"id": 5273,
"assignedById": 29,
"title": "Purchase of Cars",
"opportunity": 0
},
{
"id": 5317,
"assignedById": 29,
"title": "Purchase of Blenders",
"opportunity": 100
}
]
},
"total": 5,
}
Retrieve the Responsible Person's Data
In the obtained result, the ID of the employee responsible for the item is indicated. To display the first and last name of the employee, we will use the user.get method with the filter:
ID— set to the value from theassignedByIdparameter obtained in step 3.
JS
PHP
BX24.callMethod(
"user.get",
{
"ID": 29
},
);
require_once('crest.php');
$result = CRest::call(
'user.get',
[
'ID' => 29
]
);
As a result, we will receive data about the employee, including the NAME and LAST_NAME fields.
{
"result": [
{
"ID": "29",
"ACTIVE": true,
"NAME": "Vadim",
"LAST_NAME": "Valeev",
"SECOND_NAME": "",
"EMAIL": "v.r.valeev@bitrix.com",
"LAST_LOGIN": "2025-05-15T13:06:54+00:00",
"DATE_REGISTER": "2024-07-15T00:00:00+00:00",
"TIME_ZONE": "",
"IS_ONLINE": "Y",
"TIMESTAMP_X": {
},
"LAST_ACTIVITY_DATE": {
},
"PERSONAL_GENDER": "",
"PERSONAL_WWW": "",
"PERSONAL_BIRTHDAY": "2000-07-14T00:00:00+00:00",
"PERSONAL_MOBILE": "",
"PERSONAL_CITY": "",
"WORK_PHONE": "",
"WORK_POSITION": "",
"UF_EMPLOYMENT_DATE": "",
"UF_DEPARTMENT": [1],
"USER_TYPE": "employee"
},
],
}
Code Example
JS
PHP
// Step 1: Request the funnel name from the user
let funnelName = prompt("Enter the name of the deal funnel:");
// Step 2: Retrieve the list of funnels
BX24.callMethod(
"crm.category.list",
{
entityTypeId: 2,
},
function (result) {
if (result.error()) {
console.error(result.error().ex);
return;
}
let categories = result.data().categories;
let selectedFunnel = categories.find(cat => cat.name === funnelName);
if (!selectedFunnel) {
alert("Funnel not found.");
return;
}
let funnelId = selectedFunnel.id;
// Step 3: Request the stage name from the user
let stageName = prompt("Enter the name of the stage:");
// Step 4: Retrieve the list of stages for the selected funnel
let entityID = funnelId === 0 ? "DEAL_STAGE" : `DEAL_STAGE_${funnelId}`;
BX24.callMethod(
"crm.status.list",
{
filter: { "ENTITY_ID": entityID }
},
function (result) {
if (result.error()) {
console.error(result.error().ex);
return;
}
let stages = result.data();
let selectedStage = stages.find(stage => stage.NAME === stageName);
if (!selectedStage) {
alert("Stage not found.");
return;
}
let stageId = selectedStage.STATUS_ID;
// Step 5: Retrieve the list of deals at the selected stage
BX24.callMethod(
"crm.item.list",
{
entityTypeId: 2,
select: ["id", "title", "assignedById", "opportunity"],
filter: {
"stageId": stageId,
},
},
function (result) {
if (result.error()) {
console.error(result.error().ex);
return;
}
let deals = result.data().items;
let uniqueResponsibleIds = [...new Set(deals.map(deal => deal.assignedById))];
let userMap = {};
// Step 6: Retrieve user information
uniqueResponsibleIds.forEach(userId => {
BX24.callMethod(
"user.get",
{
"ID": userId
},
function (userResult) {
if (userResult.error()) {
console.error(userResult.error().ex);
return;
}
let user = userResult.data()[0];
userMap[userId] = {
name: user.NAME,
lastName: user.LAST_NAME
};
}
);
});
// Step 7: Output results to the console in a text table format
setTimeout(() => {
let table = [];
// Header
table.push([
"Deal ID",
"Title",
"Responsible First Name",
"Responsible Last Name",
"Expected Revenue"
]);
// Data rows
deals.forEach(deal => {
let responsible = userMap[deal.assignedById] || { name: "Unknown", lastName: "Unknown" };
table.push([
deal.id,
deal.title,
responsible.name,
responsible.lastName,
deal.opportunity || 0
]);
});
// Output the table to the console
console.table(table);
}, 1000); // Delay for all requests to complete
}
);
}
);
}
);
require_once('crest.php');
// Step 1: Request the funnel name from the user
$funnelName = readline("Enter the name of the deal funnel: ");
// Step 2: Retrieve the list of funnels
$result = CRest::call(
'crm.category.list',
[
'entityTypeId' => 2
]
);
if (!empty($result['error'])) {
echo "Error: " . $result['error_description'] . "\n";
exit;
}
$categories = $result['result']['categories'];
$selectedFunnel = null;
foreach ($categories as $category) {
if ($category['NAME'] === $funnelName) {
$selectedFunnel = $category;
break;
}
}
if (!$selectedFunnel) {
echo "Funnel not found.\n";
exit;
}
$funnelId = $selectedFunnel['ID'];
// Step 3: Request the stage name from the user
$stageName = readline("Enter the name of the stage: ");
// Step 4: Retrieve the list of stages for the selected funnel
$entityID = $funnelId === 0 ? "DEAL_STAGE" : "DEAL_STAGE_{$funnelId}";
$result = CRest::call(
'crm.status.list',
[
'filter' => [
'ENTITY_ID' => $entityID
]
]
);
if (!empty($result['error'])) {
echo "Error: " . $result['error_description'] . "\n";
exit;
}
$stages = $result['result'];
$selectedStage = null;
foreach ($stages as $stage) {
if ($stage['NAME'] === $stageName) {
$selectedStage = $stage;
break;
}
}
if (!$selectedStage) {
echo "Stage not found.\n";
exit;
}
$stageId = $selectedStage['STATUS_ID'];
// Step 5: Retrieve the list of deals at the selected stage
$result = CRest::call(
'crm.item.list',
[
'entityTypeId' => 2,
'select' => [
"id",
"title",
"assignedById",
"opportunity"
],
'filter' => [
"stageId" => $stageId
]
]
);
if (!empty($result['error'])) {
echo "Error: " . $result['error_description'] . "\n";
exit;
}
$deals = $result['result']['items'];
$uniqueResponsibleIds = array_unique(array_column($deals, 'assignedById'));
$userMap = [];
// Step 6: Retrieve user information
foreach ($uniqueResponsibleIds as $userId) {
$result = CRest::call(
'user.get',
[
'ID' => $userId
]
);
if (!empty($result['error'])) {
echo "Error: " . $result['error_description'] . "\n";
continue;
}
$user = $result['result'][0];
$userMap[$userId] = [
'name' => $user['NAME'],
'lastName' => $user['LAST_NAME']
];
}
// Step 7: Output results in a text table format
$table = [];
// Header
$table[] = [
"Deal ID",
"Title",
"Responsible First Name",
"Responsible Last Name",
"Expected Revenue"
];
// Data rows
foreach ($deals as $deal) {
$responsible = $userMap[$deal['assignedById']] ?? ['name' => 'Unknown', 'lastName' => 'Unknown'];
$table[] = [
$deal['id'],
$deal['title'],
$responsible['name'],
$responsible['lastName'],
$deal['opportunity'] ?? 0
];
}
// Output the table
foreach ($table as $row) {
echo implode("\t", $row) . "\n";
}
Copied
Previous