How to Find Duplicates in CRM by Phone and Email

from b24pysdk import BitrixWebhook, Client
        
        client = Client(
            BitrixWebhook(
                domain="your-domain.bitrix24.com",
                webhook_token="user_id/webhook_key",
            )
        )
        
        phone = input("Enter the phone number: ")
        email = input("Enter the email: ")
        
        entity_ids = {
            "LEAD": [],
            "CONTACT": [],
            "COMPANY": [],
        }
        
        rows = []
        

<?php
        // composer require bitrix24/b24phpsdk:"^3.0"
        require_once 'vendor/autoload.php';
        
        use Bitrix24\SDK\Services\ServiceBuilderFactory;
        use Symfony\Component\EventDispatcher\EventDispatcher;
        use Monolog\Logger;
        use Monolog\Handler\StreamHandler;
        
        $log = new Logger('b24');
        $log->pushHandler(new StreamHandler('php://stdout'));
        
        $sb = (new ServiceBuilderFactory(new EventDispatcher(), $log))
            ->initFromWebhook('https://your-domain.bitrix24.com/rest/USER_ID/TOKEN/');
        
        $phone = readline("Enter the phone number: ");
        $email = readline("Enter the email: ");
        
        $entityIDs = [
            'LEAD' => [],
            'CONTACT' => [],
            'COMPANY' => []
        ];
        
        $rows = [];
        

// The phone and email we search by. The neighbouring tabs ask the user for
        // them; here they are set by constants, because the example creates the
        // objects with these values itself.
        const (
        	phone = "+491701234567"
        	email = "duplicate@example.com"
        )
        
        // The identifiers of the found objects and the rows of the final table. The
        // keys are the same ones crm.duplicate.findbycomm returns.
        entityIDs := map[string][]b24.ID{"LEAD": nil, "CONTACT": nil, "COMPANY": nil}
        rows := make([]row, 0)
        

def merge_duplicates(data, entity_ids):
            """Merges the identifiers from the method response into entity_ids."""
            if not isinstance(data, dict):
                return
            for key in entity_ids:
                found = data.get(key)
                if isinstance(found, list):
                    entity_ids[key] = list(dict.fromkeys(entity_ids[key] + found))
        
        
        for comm_type, value in (("PHONE", phone), ("EMAIL", email)):
            if not value:
                continue
            result = client.crm.duplicate.findbycomm(
                type=comm_type,
                values=[value],
            ).response.result
            merge_duplicates(result, entity_ids)
        

use Bitrix24\SDK\Services\CRM\Duplicates\Result\DuplicateResult;
        
        // Merges the identifiers from the method response into the $entityIDs array
        function mergeDuplicates(DuplicateResult $result, array &$entityIDs): void
        {
            $data = $result->getCoreResponse()->getResponseData()->getResult();
            foreach (['LEAD', 'CONTACT', 'COMPANY'] as $type) {
                if (!empty($data[$type]) && is_array($data[$type])) {
                    $entityIDs[$type] = array_values(array_unique(
                        array_merge($entityIDs[$type], $data[$type])
                    ));
                }
            }
        }
        
        if ($phone) {
            mergeDuplicates($sb->getCRMScope()->duplicate()->findByPhone([$phone]), $entityIDs);
        }
        
        if ($email) {
            mergeDuplicates($sb->getCRMScope()->duplicate()->findByEmail([$email]), $entityIDs);
        }
        

// The method searches by ONE communication type per call, so we query the
        // phone and the email separately and accumulate the identifiers in a shared map.
        for _, comm := range []struct{ typ, value string }{
        	{"PHONE", phone},
        	{"EMAIL", email},
        } {
        	if comm.value == "" {
        		continue
        	}
        	res, err := core.Call(ctx, "crm.duplicate.findbycomm", b24.Params{
        		"type":   comm.typ,
        		"values": []string{comm.value},
        	}, b24.WithIdempotent())
        	if err != nil {
        		return fmt.Errorf("crm.duplicate.findbycomm %s: %w", comm.typ, err)
        	}
        
        	// The response is an object with the LEAD, CONTACT, and COMPANY keys. A key
        	// may be missing entirely: if nothing was found for that type, it is simply
        	// not sent. When nothing was found at all, result comes as an empty array
        	// rather than an object, so we ignore the parsing error here.
        	var found map[string][]b24.ID
        	if err := json.Unmarshal(res.Result, &found); err == nil {
        		for key := range entityIDs {
        			entityIDs[key] = appendUnique(entityIDs[key], found[key])
        		}
        	}
        }
        

SELECT = ["id", "title", "name", "lastName", "phone", "email"]
        ENTITY_TYPES = (
            ("LEAD", 1, "lead"),
            ("CONTACT", 3, "contact"),
            ("COMPANY", 4, "company"),
        )
        
        for key, entity_type_id, label in ENTITY_TYPES:
            if not entity_ids[key]:
                continue
        
            items = client.crm.item.list(
                entity_type_id=entity_type_id,
                filter={"id": entity_ids[key]},
                select=SELECT,
            ).response.result["items"]
        
            for item in items:
                name = " ".join(filter(None, [item.get("name"), item.get("lastName")]))
                rows.append({
                    "id": item["id"],
                    "kind": label,
                    "title": name or item.get("title") or "—",
                    "phone": item.get("phone") or "—",
                    "email": item.get("email") or "—",
                })
        

$select = ['id', 'title', 'name', 'lastName', 'phone', 'email'];
        $entityTypes = [
            ['key' => 'LEAD', 'entityTypeId' => 1, 'label' => 'lead'],
            ['key' => 'CONTACT', 'entityTypeId' => 3, 'label' => 'contact'],
            ['key' => 'COMPANY', 'entityTypeId' => 4, 'label' => 'company'],
        ];
        
        foreach ($entityTypes as $type) {
            if (empty($entityIDs[$type['key']])) {
                continue;
            }
        
            $items = $sb->getCRMScope()->item()->list(
                $type['entityTypeId'],
                [],
                ['id' => $entityIDs[$type['key']]],
                $select
            )->getItems();
        
            foreach ($items as $item) {
                $name = trim(($item->name ?? '') . ' ' . ($item->lastName ?? ''));
                $rows[] = [
                    'id' => $item->id,
                    'kind' => $type['label'],
                    'title' => $name ?: ($item->title ?? '—'),
                    'phone' => $item->phone ?: '—',
                    'email' => $item->email ?: '—',
                ];
            }
        }
        

// The data of all three types is returned by one method: only entityTypeId differs.
        for _, spec := range entityTypes {
        	ids := entityIDs[spec.key]
        	if len(ids) == 0 {
        		continue
        	}
        	res, err := core.Call(ctx, "crm.item.list", b24.Params{
        		"entityTypeId": spec.entityTypeID,
        		"filter":       b24.Params{"id": ids},
        		"select":       []string{"id", "title", "name", "lastName", "phone", "email"},
        	}, b24.WithIdempotent())
        	if err != nil {
        		return fmt.Errorf("crm.item.list %s: %w", spec.key, err)
        	}
        
        	// The method wraps the response in an object with the items key, fields in camelCase.
        	var list struct {
        		Items []entity `json:"items"`
        	}
        	if err := json.Unmarshal(res.Result, &list); err != nil {
        		return fmt.Errorf("parse the %s response: %w", spec.key, err)
        	}
        	for _, e := range list.Items {
        		rows = append(rows, e.row(spec.label))
        	}
        }
        

if not rows:
            print("No duplicates found")
        else:
            print("\t".join(["ID", "Object type", "Title/First and last name", "Phone", "Email"]))
            for row in rows:
                print("\t".join(str(row[key]) for key in ("id", "kind", "title", "phone", "email")))
        

if (empty($rows)) {
            echo "No duplicates found\n";
        } else {
            echo implode("\t", ['ID', 'Object type', 'Title/First and last name', 'Phone', 'Email']) . "\n";
            foreach ($rows as $row) {
                echo implode("\t", $row) . "\n";
            }
        }
        

if len(rows) == 0 {
        	fmt.Println("No duplicates found")
        	return nil
        }
        fmt.Println("ID\tObject type\tTitle/First and last name\tPhone\tEmail")
        for _, r := range rows {
        	fmt.Printf("%d\t%s\t%s\t%s\t%s\n", r.ID, r.Kind, r.Title, r.Phone, r.Email)
        }
        

from b24pysdk import BitrixWebhook, Client
        from b24pysdk.errors import BitrixAPIError
        
        client = Client(
            BitrixWebhook(
                domain="your-domain.bitrix24.com",
                webhook_token="user_id/webhook_key",
            )
        )
        
        SELECT = ["id", "title", "name", "lastName", "phone", "email"]
        ENTITY_TYPES = (
            ("LEAD", 1, "lead"),
            ("CONTACT", 3, "contact"),
            ("COMPANY", 4, "company"),
        )
        
        
        def merge_duplicates(data, entity_ids):
            """Merges the identifiers from the method response into entity_ids."""
            if not isinstance(data, dict):
                return
            for key in entity_ids:
                found = data.get(key)
                if isinstance(found, list):
                    entity_ids[key] = list(dict.fromkeys(entity_ids[key] + found))
        
        
        phone = input("Enter the phone number: ")
        email = input("Enter the email: ")
        
        entity_ids = {"LEAD": [], "CONTACT": [], "COMPANY": []}
        rows = []
        
        try:
            # Step 1: Searching for duplicates by phone and by email
            for comm_type, value in (("PHONE", phone), ("EMAIL", email)):
                if not value:
                    continue
                result = client.crm.duplicate.findbycomm(
                    type=comm_type,
                    values=[value],
                ).response.result
                merge_duplicates(result, entity_ids)
        
            # Step 2: Retrieving the data of the found objects
            for key, entity_type_id, label in ENTITY_TYPES:
                if not entity_ids[key]:
                    continue
        
                items = client.crm.item.list(
                    entity_type_id=entity_type_id,
                    filter={"id": entity_ids[key]},
                    select=SELECT,
                ).response.result["items"]
        
                for item in items:
                    name = " ".join(filter(None, [item.get("name"), item.get("lastName")]))
                    rows.append({
                        "id": item["id"],
                        "kind": label,
                        "title": name or item.get("title") or "—",
                        "phone": item.get("phone") or "—",
                        "email": item.get("email") or "—",
                    })
        except BitrixAPIError as error:
            print(error)
        
        # Printing the table with tab separators
        if not rows:
            print("No duplicates found")
        else:
            print("\t".join(["ID", "Object type", "Title/First and last name", "Phone", "Email"]))
            for row in rows:
                print("\t".join(str(row[key]) for key in ("id", "kind", "title", "phone", "email")))
        

<?php
        // composer require bitrix24/b24phpsdk:"^3.0"
        require_once 'vendor/autoload.php';
        
        use Bitrix24\SDK\Services\ServiceBuilderFactory;
        use Bitrix24\SDK\Services\CRM\Duplicates\Result\DuplicateResult;
        use Symfony\Component\EventDispatcher\EventDispatcher;
        use Monolog\Logger;
        use Monolog\Handler\StreamHandler;
        
        $log = new Logger('b24');
        $log->pushHandler(new StreamHandler('php://stdout'));
        
        $sb = (new ServiceBuilderFactory(new EventDispatcher(), $log))
            ->initFromWebhook('https://your-domain.bitrix24.com/rest/USER_ID/TOKEN/');
        
        // Asking the user for the phone and the email
        $phone = readline("Enter the phone number: ");
        $email = readline("Enter the email: ");
        
        $entityIDs = ['LEAD' => [], 'CONTACT' => [], 'COMPANY' => []];
        $rows = [];
        
        $select = ['id', 'title', 'name', 'lastName', 'phone', 'email'];
        $entityTypes = [
            ['key' => 'LEAD', 'entityTypeId' => 1, 'label' => 'lead'],
            ['key' => 'CONTACT', 'entityTypeId' => 3, 'label' => 'contact'],
            ['key' => 'COMPANY', 'entityTypeId' => 4, 'label' => 'company'],
        ];
        
        // Merges the identifiers from the method response into the $entityIDs array
        function mergeDuplicates(DuplicateResult $result, array &$entityIDs): void
        {
            $data = $result->getCoreResponse()->getResponseData()->getResult();
            foreach (['LEAD', 'CONTACT', 'COMPANY'] as $type) {
                if (!empty($data[$type]) && is_array($data[$type])) {
                    $entityIDs[$type] = array_values(array_unique(
                        array_merge($entityIDs[$type], $data[$type])
                    ));
                }
            }
        }
        
        try {
            // Step 1: Searching for duplicates by phone and by email
            if ($phone) {
                mergeDuplicates($sb->getCRMScope()->duplicate()->findByPhone([$phone]), $entityIDs);
            }
        
            if ($email) {
                mergeDuplicates($sb->getCRMScope()->duplicate()->findByEmail([$email]), $entityIDs);
            }
        
            // Step 2: Retrieving the data of the found objects
            foreach ($entityTypes as $type) {
                if (empty($entityIDs[$type['key']])) {
                    continue;
                }
        
                $items = $sb->getCRMScope()->item()->list(
                    $type['entityTypeId'],
                    [],
                    ['id' => $entityIDs[$type['key']]],
                    $select
                )->getItems();
        
                foreach ($items as $item) {
                    $name = trim(($item->name ?? '') . ' ' . ($item->lastName ?? ''));
                    $rows[] = [
                        'id' => $item->id,
                        'kind' => $type['label'],
                        'title' => $name ?: ($item->title ?? '—'),
                        'phone' => $item->phone ?: '—',
                        'email' => $item->email ?: '—',
                    ];
                }
            }
        } catch (\Throwable $e) {
            echo $e->getMessage() . "\n";
        }
        
        // Printing the table with tab separators
        if (empty($rows)) {
            echo "No duplicates found\n";
        } else {
            echo implode("\t", ['ID', 'Object type', 'Title/First and last name', 'Phone', 'Email']) . "\n";
            foreach ($rows as $row) {
                echo implode("\t", $row) . "\n";
            }
        }
        

// Setup in an empty directory — go get does not work without go mod init:
        //
        //	go mod init example && go get github.com/bitrix24/b24gosdk
        //
        // Run:
        //
        //	export B24_WEBHOOK_URL='https://your-domain.bitrix24.com/rest/1/token/' && go run .
        //
        // The example is self-contained: it creates a lead, a contact, and a company
        // with the same phone and email, finds them as duplicates, prints the table,
        // and cleans up after itself. It runs on any Bitrix24, nothing has to be edited.
        package main
        
        import (
        	"context"
        	"encoding/json"
        	"fmt"
        	"log"
        	"os"
        	"strings"
        
        	b24 "github.com/bitrix24/b24gosdk"
        )
        
        // The phone and email we search by. The neighbouring tabs ask the user for
        // them; here they are set by constants, because the example creates the
        // objects with these values itself.
        const (
        	phone = "+491701234567"
        	email = "duplicate@example.com"
        )
        
        // The object types we search duplicates in. The key is the same one the
        // crm.duplicate.findbycomm response holds, entityTypeID comes from crm.enum.ownertype.
        var entityTypes = []struct {
        	key          string
        	entityTypeID int
        	label        string
        }{
        	{"LEAD", 1, "lead"},
        	{"CONTACT", 3, "contact"},
        	{"COMPANY", 4, "company"},
        }
        
        func main() {
        	if err := run(context.Background()); err != nil {
        		log.Fatal(err)
        	}
        }
        
        func run(ctx context.Context) error {
        	// The webhook path is a secret, so it comes from the environment, not from the code.
        	core := b24.NewClient(os.Getenv("B24_WEBHOOK_URL")).Core()
        
        	// The identifiers of the found objects and the rows of the final table. The
        	// keys are the same ones crm.duplicate.findbycomm returns.
        	entityIDs := map[string][]b24.ID{"LEAD": nil, "CONTACT": nil, "COMPANY": nil}
        	rows := make([]row, 0)
        
        	// --- preparation: our own duplicates
        
        	cleanup, err := createDuplicates(ctx, core, phone, email)
        	defer cleanup()
        	if err != nil {
        		return err
        	}
        
        	// --- step 1: searching for duplicates by communications
        	// The method searches by ONE communication type per call, so we query the
        	// phone and the email separately and accumulate the identifiers in a shared map.
        	for _, comm := range []struct{ typ, value string }{
        		{"PHONE", phone},
        		{"EMAIL", email},
        	} {
        		if comm.value == "" {
        			continue
        		}
        		res, err := core.Call(ctx, "crm.duplicate.findbycomm", b24.Params{
        			"type":   comm.typ,
        			"values": []string{comm.value},
        		}, b24.WithIdempotent())
        		if err != nil {
        			return fmt.Errorf("crm.duplicate.findbycomm %s: %w", comm.typ, err)
        		}
        
        		// The response is an object with the LEAD, CONTACT, and COMPANY keys. A key
        		// may be missing entirely: if nothing was found for that type, it is simply
        		// not sent. When nothing was found at all, result comes as an empty array
        		// rather than an object, so we ignore the parsing error here.
        		var found map[string][]b24.ID
        		if err := json.Unmarshal(res.Result, &found); err == nil {
        			for key := range entityIDs {
        				entityIDs[key] = appendUnique(entityIDs[key], found[key])
        			}
        		}
        	}
        	fmt.Printf("found: leads %d, contacts %d, companies %d\n",
        		len(entityIDs["LEAD"]), len(entityIDs["CONTACT"]), len(entityIDs["COMPANY"]))
        
        	// --- step 2: the data of the found objects
        	// The data of all three types is returned by one method: only entityTypeId differs.
        	for _, spec := range entityTypes {
        		ids := entityIDs[spec.key]
        		if len(ids) == 0 {
        			continue
        		}
        		res, err := core.Call(ctx, "crm.item.list", b24.Params{
        			"entityTypeId": spec.entityTypeID,
        			"filter":       b24.Params{"id": ids},
        			"select":       []string{"id", "title", "name", "lastName", "phone", "email"},
        		}, b24.WithIdempotent())
        		if err != nil {
        			return fmt.Errorf("crm.item.list %s: %w", spec.key, err)
        		}
        
        		// The method wraps the response in an object with the items key, fields in camelCase.
        		var list struct {
        			Items []entity `json:"items"`
        		}
        		if err := json.Unmarshal(res.Result, &list); err != nil {
        			return fmt.Errorf("parse the %s response: %w", spec.key, err)
        		}
        		for _, e := range list.Items {
        			rows = append(rows, e.row(spec.label))
        		}
        	}
        
        	// --- printing the table
        	if len(rows) == 0 {
        		fmt.Println("No duplicates found")
        		return nil
        	}
        	fmt.Println("ID\tObject type\tTitle/First and last name\tPhone\tEmail")
        	for _, r := range rows {
        		fmt.Printf("%d\t%s\t%s\t%s\t%s\n", r.ID, r.Kind, r.Title, r.Phone, r.Email)
        	}
        	return nil
        }
        
        // entity — the common shape of a crm.item.list response row: the set of fields
        // differs for a lead, a contact, and a company, but the ones we need coincide.
        type entity struct {
        	ID       b24.ID `json:"id"`
        	Title    string `json:"title"`
        	Name     string `json:"name"`
        	LastName string `json:"lastName"`
        	Phone    string `json:"phone"`
        	Email    string `json:"email"`
        }
        
        type row struct {
        	ID                        b24.ID
        	Kind, Title, Phone, Email string
        }
        
        func (e entity) row(kind string) row {
        	title := strings.TrimSpace(e.Name + " " + e.LastName)
        	if title == "" {
        		title = e.Title
        	}
        	return row{ID: e.ID, Kind: kind, Title: title,
        		Phone: orDash(e.Phone), Email: orDash(e.Email)}
        }
        
        func orDash(value string) string {
        	if value == "" {
        		return "—"
        	}
        	return value
        }
        
        func appendUnique(dst, src []b24.ID) []b24.ID {
        	seen := make(map[b24.ID]bool, len(dst))
        	for _, id := range dst {
        		seen[id] = true
        	}
        	for _, id := range src {
        		if !seen[id] {
        			seen[id] = true
        			dst = append(dst, id)
        		}
        	}
        	return dst
        }
        
        // --- auxiliary: data preparation and cleanup
        
        // createDuplicates creates a lead, a contact, and a company with the same phone
        // and email — exactly the situation the scenario searches for. It returns a
        // cleanup function: it is called even when the preparation broke halfway.
        func createDuplicates(ctx context.Context, core *b24.Core, phone, email string) (func(), error) {
        	comm := b24.Params{
        		"PHONE": []map[string]any{b24.MultifieldAdd(phone, "WORK")},
        		"EMAIL": []map[string]any{b24.MultifieldAdd(email, "WORK")},
        	}
        	created := map[string]b24.ID{}
        	cleanup := func() {
        		for method, id := range created {
        			del(ctx, core, method, b24.Params{"id": id})
        		}
        	}
        
        	for _, spec := range []struct {
        		add, delete string
        		fields      b24.Params
        	}{
        		{"crm.lead.add", "crm.lead.delete", b24.Params{"TITLE": "Website request", "NAME": "Klaus", "LAST_NAME": "Weber"}},
        		{"crm.contact.add", "crm.contact.delete", b24.Params{"NAME": "Klaus", "LAST_NAME": "Weber"}},
        		{"crm.company.add", "crm.company.delete", b24.Params{"TITLE": "Müller GmbH"}},
        	} {
        		fields := b24.Params{}
        		for k, v := range spec.fields {
        			fields[k] = v
        		}
        		for k, v := range comm {
        			fields[k] = v
        		}
        		res, err := core.Call(ctx, spec.add, b24.Params{"fields": fields})
        		if err != nil {
        			return cleanup, fmt.Errorf("%s: %w", spec.add, err)
        		}
        		var id b24.ID
        		if err := json.Unmarshal(res.Result, &id); err != nil {
        			return cleanup, fmt.Errorf("parse the identifier from %s: %w", spec.add, err)
        		}
        		created[spec.delete] = id
        	}
        	return cleanup, nil
        }
        
        // del removes what was created. The cleanup error is printed but not returned:
        // it must not replace the real error of the scenario.
        func del(ctx context.Context, core *b24.Core, method string, params b24.Params) {
        	if _, err := core.Call(ctx, method, params); err != nil {
        		fmt.Fprintf(os.Stderr, "cleanup, %s: %v\n", method, err)
        	}
        }