Search.../

appendOrCreateContact( )

Appends contactInfo to an existing contact or creates a new contact if it doesn't already exist.

Description

The appendOrCreateContact() function returns a Promise that resolves to a contact ID and identity type when a contact is found or created.

When called, appendOrCreateContact() accepts an object with contact information and follows the steps below. When one of the conditions is met, this process ends and the specified data is handled:

  1. If the current visitor is a logged-in member: appendOrCreateContact() reconciles with the member's associated contact.
  2. If the current visitor is not a logged-in member: appendOrCreateContact() tries to reconcile any specified email addresses and/or phone numbers with an existing contact.
  3. If an email address, phone number, and/or name has been provided, but the contact can't be reconciled: A new contact is created and appendOrCreateContact() reconciles with the new contact.
  4. If a contact can't be reconciled by email or phone and a new contact isn't created: appendOrCreateContact() tries to reconcile the visitor's session identity with an existing contact.
  5. If no contact can be created: The Promise is rejected.

appendOrCreateContact() does not require member authentication, so it does not return the entire contact object. The contact's data can be retrieved with getContact().

How the Data is Handled

If an existing contact is found:

  • The current visitor's session identity is associated with the contact.
  • If a specified property is empty in the existing contact, the property is updated with the specified information.
  • For arrays, any specified information is added as new array items. This includes emails, addresses, phones, and labelKeys.
  • No existing data is overwritten or deleted.

Note: If the reconciled contact belongs to a member who isn't currently logged in to the site, identityType is returned as "NOT_AUTHENTICATED_MEMBER". In that case, no contact properties are modified.

If a new contact is created:

  • The new contact's data is populated with the specified contact object.
  • The current visitor's session identity is associated with the contact.

Syntax

function appendOrCreateContact(contactInfo: ContactInfo): Promise<ContactIdentification>

appendOrCreateContact Parameters

NAME
TYPE
DESCRIPTION
contactInfo
ContactInfo

Contact's information. To reconcile with an existing contact, a phone or email must be provided, or the current session identity must be attached to a contact or member.

If no existing contact can be found, a new contact is created with the specified information.

Returns

Return Type:

Promise<ContactIdentification>
NAME
TYPE
DESCRIPTION
contactId
string

ID of the contact that was found or created.

identityType
string

Identity type of the returned contact.

One of:

  • "CONTACT": The returned contact ID belongs to a new or existing contact.
  • "MEMBER": The returned contact ID belongs to the currently logged-in site member.
  • "NOT_AUTHENTICATED_MEMBER": The returned contact ID belongs to a site member who is not currently logged in.

Was this helpful?

Append or create a contact with a name

Copy Code
1import { contacts } from 'wix-crm-backend';
2
3export function myAppendOrCreateContactFunction() {
4 const contactInfo = {
5 name: {
6 first: "Ari",
7 last: "Thereyet"
8 }
9 };
10
11 return contacts.appendOrCreateContact(contactInfo)
12 .then((resolvedContact) => {
13 return resolvedContact;
14 })
15 .catch((error) => {
16 console.error(error);
17 });
18}
19
20/* Promise resolves to:
21 * {
22 * "contactId": "a52852d7-e0d6-484b-93fe-bffdb670f08f",
23 * "identityType": "CONTACT"
24 * }
25 */
Append or create a contact, full object

Copy Code
1import { contacts } from 'wix-crm-backend';
2
3export function myAppendOrCreateContactFunction() {
4 const contactInfo = {
5 name: {
6 first: "Ari",
7 last: "Thereyet"
8 },
9 emails: [
10 {
11 email: "ari.thereyet@example.com",
12 },
13 {
14 email: "ari.thereyet.appended.email@example.com"
15 }
16 ],
17 phones: [
18 {
19 tag: "MOBILE",
20 countryCode: "US",
21 phone: "601-081-124",
22 primary: true
23 }
24 ]
25 };
26
27 return contacts.appendOrCreateContact(contactInfo)
28 .then((resolvedContact) => {
29 return resolvedContact;
30 })
31 .catch((error) => {
32 console.error(error);
33 });
34}
35
36/* Promise resolves to:
37 * {
38 * "contactId": "a52852d7-e0d6-484b-93fe-bffdb670f08f",
39 * "identityType": "CONTACT"
40 * }
41 */