Search.../
  1. APIs

mergeContacts( )

Merges source contacts into a target contact.

Description

Merging contacts has these effects on the target contact:

  • No target contact data is overwritten or deleted.
  • Arrays (emails, phones, addresses, and labels) are merged from the source contacts into the target contact.
  • If merging more than one source contact, the 1st source is given precedence, then the 2nd, and so on.

Source contacts are deleted when merging. However, if a source contact is a site member or collaborator, the mergeContacts() function fails because site collaborators and members can't be deleted. Site members and collaborators can only be target contacts.

After merging, if you call the getContact() function with a deleted source contact ID, the target contact ID is returned. This is only supported when calling getContact(). Previously deleted source contact IDs can't be passed in any other function.

Admin Method

This function requires elevated permissions to run. This function is not universal and runs only on the backend.

Syntax

function mergeContacts(targetContactId: string, targetContactRevision: number, options: MergeContactsOptions): Promise<MergeContactsResponse>

mergeContacts Parameters

NAME
TYPE
DESCRIPTION
targetContactId
string

Target contact ID.

targetContactRevision
number

Target contact revision number, which increments by 1 each time the contact is updated. To prevent conflicting changes, the target contact's current revision must be passed.

options
Optional
MergeContactsOptions

Merge contacts options.

Returns

Return Type:

Promise<
MergeContactsResponse
>
NAME
TYPE
DESCRIPTION
contact
Contact

Updated target contact.

Was this helpful?

Get revision ID and merge contacts (dashboard page code)

This function uses getContact() to extract the revision for the target contact, then merges the source contacts into the target contact.

Copy Code
1import { contacts } from 'wix-crm.v2';
2

3/*
4 * Sample targetContactId value: '5518ee7f-270e-40c4-b756-dad56e8f0ffc'
5 * 
6 * Sample targetContactRevision value: Extract from `getContact()` return object
7 * 
8 * Sample options value:
9 *  {
10 *    sourceContactIds: [
11 *      'ce6475cf-55d7-411c-8cb1-7f62be2429dd',
12 *      'cb591d0e-a308-4f19-a9b9-5fb26ee7a11f'
13 *    ]
14 *  }
15*/
16

17export async function mergeContactsFunction(targetContactId, targetContactRevision, options) {
18  
19  try{
20    const targetContact = await contacts.getContact(targetContactId);
21    
22    // Extract revision from target contact
23    targetContactRevision = targetContact.revision;
24    const mergedContact = await contacts.mergeContacts(targetContactId, targetContactRevision, options);
25    console.log("successfully merged contacts!");
26

27    return mergedContact.contact;  
28  } catch (error) {
29    console.log(error);
30    // Handle the error
31  }
32}
33

34/* Promise resolves to:
35 * {
36 *   "revision": 3,
37 *   "source": {
38 *     "sourceType": "WIX_CODE",
39 *     "appId": "151e476a-715e-ec33-db9a-a7ff4d51f70a"
40 *   },
41 *   "lastActivity": {
42 *     "activityDate": "2024-01-09T12:41:24.295Z",
43 *     "activityType": "CONTACT_MERGED"
44 *   },
45 *   "primaryInfo": {
46 *     "email": "sally.smith@example.com",
47 *     "phone": "524-624-2486"
48 *   },
49 *   "info": {
50 *     "name": {
51 *       "first": "Sally",
52 *       "last": "Smith"
53 *     },
54 *     "emails": {
55 *       "items": [
56 *         {
57 *           "tag": "UNTAGGED",
58 *           "email": "sally.smith@example.com",
59 *           "primary": true,
60 *           "_id": "fa2a8be4-b0d9-4926-adb3-463ef487787b"
61 *         }
62 *       ]
63 *     },
64 *     "phones": {
65 *       "items": [
66 *         {
67 *           "tag": "MOBILE",
68 *           "countryCode": "US",
69 *           "phone": "524-624-2486",
70 *           "e164Phone": "+15246242486",
71 *           "primary": true,
72 *           "_id": "73382a58-55c6-4b1c-8af1-ffe60a7e5485"
73 *         },
74 *         {
75 *           "tag": "WORK",
76 *           "countryCode": "US",
77 *           "phone": "214-268-2998",
78 *           "e164Phone": "+12142682998",
79 *           "primary": false,
80 *           "_id": "69bd9ea5-31e3-4e68-97a7-1c74031f26cd"
81 *         }
82 *       ]
83 *     },
84 *     "addresses": {
85 *       "items": [
86 *         {
87 *           "tag": "HOME",
88 *           "address": {
89 *             "formatted": "NY",
90 *             "city": "NY"
91 *           },
92 *           "_id": "f22294bf-349b-47bb-9229-8a0d2ca9cb78"
93 *         },
94 *         {
95 *           "tag": "WORK",
96 *           "address": {
97 *             "formatted": "12 Park Ave\nNY\nUnited States",
98 *             "addressLine1": "12 Park Ave",
99 *             "city": "NY",
100 *             "country": "US"
101 *           },
102 *           "_id": "471391d8-285f-405b-ae44-bda559088ac1"
103 *         }
104 *       ]
105 *     },
106 *     "labelKeys": {
107 *       "items": [
108 *         "custom.active-customer",
109 *         "custom.contact",
110 *         "contacts.customers",
111 *         "custom.anonymous"
112 *       ]
113 *     },
114 *     "extendedFields": {
115 *       "items": {
116 *         "contacts.displayByLastName": "Smith Sally",
117 *         "invoices.vatId": "",
118 *         "emailSubscriptions.deliverabilityStatus": "NOT_SET",
119 *         "emailSubscriptions.subscriptionStatus": "NOT_SET",
120 *         "emailSubscriptions.effectiveEmail": "sally.smith@example.com",
121 *         "custom.age": 24,
122 *         "contacts.displayByFirstName": "Sally Smith",
123 *         "custom.nickname": "Silly"
124 *       }
125 *     }
126 *   },
127 *   "_id": "5518ee7f-270e-40c4-b756-dad56e8f0ffc",
128 *   "_createdDate": "2023-12-28T11:44:11.331Z",
129 *   "_updatedDate": "2024-01-09T12:41:24.295Z"
130 * }
131 */
132
Get revision ID and merge contacts (export from backend code)

This function uses getContact() to extract the revision for the target contact, then merges the source contacts into the target contact.

Copy Code
1import { Permissions, webMethod } from 'wix-web-module';
2import { contacts } from 'wix-crm.v2';
3import { elevate } from 'wix-auth';
4

5/*
6 * Sample targetContactId value: '5518ee7f-270e-40c4-b756-dad56e8f0ffc'
7 * 
8 * Sample targetContactRevision value: Extract from `getContact()` return object
9 * 
10 * Sample options value:
11 *  {
12 *    sourceContactIds: [
13 *      'ce6475cf-55d7-411c-8cb1-7f62be2429dd',
14 *      'cb591d0e-a308-4f19-a9b9-5fb26ee7a11f'
15 *    ]
16 *  }
17*/
18

19export const mergeContactsFunction = webMethod(Permissions.Anyone, async (targetContactId, targetContactRevision, options) => {
20  
21  try{
22    const elevateGetContactRevision = elevate(contacts.getContact);
23    const elevatedMergeContacts = elevate(contacts.mergeContacts);
24    const targetContact = await elevateGetContactRevision(targetContactId);
25    
26    // Extract revision from target contact
27    targetContactRevision = targetContact.revision;
28    const mergedContact = await elevatedMergeContacts(targetContactId, targetContactRevision, options);
29    console.log("successfully merged contacts!");
30

31    return mergedContact.contact;  
32  } catch (error) {
33    console.log(error);
34    // Handle the error
35  }
36});
37

38/* Promise resolves to:
39 * {
40 *   "revision": 3,
41 *   "source": {
42 *     "sourceType": "WIX_CODE",
43 *     "appId": "151e476a-715e-ec33-db9a-a7ff4d51f70a"
44 *   },
45 *   "lastActivity": {
46 *     "activityDate": "2024-01-09T12:41:24.295Z",
47 *     "activityType": "CONTACT_MERGED"
48 *   },
49 *   "primaryInfo": {
50 *     "email": "sally.smith@example.com",
51 *     "phone": "524-624-2486"
52 *   },
53 *   "info": {
54 *     "name": {
55 *       "first": "Sally",
56 *       "last": "Smith"
57 *     },
58 *     "emails": {
59 *       "items": [
60 *         {
61 *           "tag": "UNTAGGED",
62 *           "email": "sally.smith@example.com",
63 *           "primary": true,
64 *           "_id": "fa2a8be4-b0d9-4926-adb3-463ef487787b"
65 *         }
66 *       ]
67 *     },
68 *     "phones": {
69 *       "items": [
70 *         {
71 *           "tag": "MOBILE",
72 *           "countryCode": "US",
73 *           "phone": "524-624-2486",
74 *           "e164Phone": "+15246242486",
75 *           "primary": true,
76 *           "_id": "73382a58-55c6-4b1c-8af1-ffe60a7e5485"
77 *         },
78 *         {
79 *           "tag": "WORK",
80 *           "countryCode": "US",
81 *           "phone": "214-268-2998",
82 *           "e164Phone": "+12142682998",
83 *           "primary": false,
84 *           "_id": "69bd9ea5-31e3-4e68-97a7-1c74031f26cd"
85 *         }
86 *       ]
87 *     },
88 *     "addresses": {
89 *       "items": [
90 *         {
91 *           "tag": "HOME",
92 *           "address": {
93 *             "formatted": "NY",
94 *             "city": "NY"
95 *           },
96 *           "_id": "f22294bf-349b-47bb-9229-8a0d2ca9cb78"
97 *         },
98 *         {
99 *           "tag": "WORK",
100 *           "address": {
101 *             "formatted": "12 Park Ave\nNY\nUnited States",
102 *             "addressLine1": "12 Park Ave",
103 *             "city": "NY",
104 *             "country": "US"
105 *           },
106 *           "_id": "471391d8-285f-405b-ae44-bda559088ac1"
107 *         }
108 *       ]
109 *     },
110 *     "labelKeys": {
111 *       "items": [
112 *         "custom.active-customer",
113 *         "custom.contact",
114 *         "contacts.customers",
115 *         "custom.anonymous"
116 *       ]
117 *     },
118 *     "extendedFields": {
119 *       "items": {
120 *         "contacts.displayByLastName": "Smith Sally",
121 *         "invoices.vatId": "",
122 *         "emailSubscriptions.deliverabilityStatus": "NOT_SET",
123 *         "emailSubscriptions.subscriptionStatus": "NOT_SET",
124 *         "emailSubscriptions.effectiveEmail": "sally.smith@example.com",
125 *         "custom.age": 24,
126 *         "contacts.displayByFirstName": "Sally Smith",
127 *         "custom.nickname": "Silly"
128 *       }
129 *     }
130 *   },
131 *   "_id": "5518ee7f-270e-40c4-b756-dad56e8f0ffc",
132 *   "_createdDate": "2023-12-28T11:44:11.331Z",
133 *   "_updatedDate": "2024-01-09T12:41:24.295Z"
134 * }
135 */
136