Introduction

The Contacts API provides functionality for adding and managing contacts on your site. When a new visitor shares contact information with your site, they're added to your Contact List. You can then access their contact details using the API.

A site visitor can become a contact through various methods, including but not limited to:

  • Completing forms such as event registrations, membership sign-ups, customer support inquiries, or billing address submissions.
  • Being manually added by a site collaborator.
  • Engaging with 3rd-party integrations that leverage the Contacts API, for example, logging in with social media. Learn more about how you can manage your contact list.

With the Contacts API, you can:

Before you begin

It is important to note the following points before you begin to code:

  • You can't label or unlabel a contact if the label does not yet exist. To create a label, use the Labels API.
  • Merging a contact is irreversible.
  • Site members and collaborators can only be used as the target contact when merging contacts.

Terminology

  • Label: A tag that enables site admins to organize and group contacts.
  • Extended field: An additional property that stores contact information.
  • Source contact: A contact you intend to merge into a target contact. These contacts get deleted after being merged.
  • Target contact: A contact that receives merged data from source contacts.
Was this helpful?
Yes
No

Setup

To use the Contacts API, install the @wix/crm package using npm or Yarn:

Copy
1
npm install @wix/crm

or

Copy
1
yarn add @wix/crm

Then import { contacts } from @wix/crm:

Copy
1
import { contacts } from '@wix/crm'
Was this helpful?
Yes
No

createContact( )

Creates a new contact.

The createContact() function returns a Promise that resolves to the new contact when it is created.

The info parameter object must include a name, phone number, or email address. If all 3 of these parameters are missing, the contact won't be created.

By default, if the call contains an email already in use by another contact, the new contact won't be created. To override this behavior, set allowDuplicates in the options object to true.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Contacts
Manage Members and Contacts - all permissions
Learn more about permission scopes.
Copy
function createContact(info: ContactInfo, options: CreateContactOptions): Promise<CreateContactResponse>
Method Parameters
infoContactInfoRequired
Contact info.

optionsCreateContactOptions
Create contact options.
Returns
Return Type:Promise<CreateContactResponse>
Was this helpful?
Yes
No

deleteContact( )

Deletes a contact who is not a site member or contributor.

The deleteContact() function returns a Promise that resolves when the specified contact is deleted.

Deleting a contact permanently removes them from your Contact List.

If the contact is also a site member, the member must be deleted first, and then the contact can be deleted.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Contacts
Manage Members and Contacts - all permissions
Manage Members
Learn more about permission scopes.
Copy
function deleteContact(contactId: string): Promise<void>
Method Parameters
contactIdstringRequired
ID of the contact to delete.
Was this helpful?
Yes
No

getContact( )

Retrieves a contact.

The getContact() function returns a Promise that resolves when the contact is found.

Getting Merged Contacts

When a source contact is merged into a target contact, the source contact is deleted. When calling getContact() for a merged contact, you can use the source or target contact ID. In both cases, the target contact is returned.

This is supported only when calling getContact()on merged contacts. Previously deleted source contact IDs can't be passed to any other function.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Contacts
Read Members and Contacts - all read permissions
Manage Contacts
Manage Members and Contacts - all permissions
Learn more about permission scopes.
Copy
function getContact(_id: string, options: GetContactOptions): Promise<Contact>
Method Parameters
_idstringRequired
ID of the contact to retrieve.

optionsGetContactOptions
Get contact options.
Returns
Return Type:Promise<Contact>
Was this helpful?
Yes
No

labelContact( )

Adds labels to a contact.

The labelContact() function returns a Promise that resolves when the specified labels are added to the contact.

  • To create new labels: Use findOrCreateLabel().
  • To find labels: Use findOrCreateLabel(), getLabel(), or queryLabels().

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Contacts
Manage Members and Contacts - all permissions
Learn more about permission scopes.
Copy
function labelContact(contactId: string, labelKeys: Array<string>): Promise<LabelContactResponse>
Method Parameters
contactIdstringRequired
ID of the contact to add labels to.

labelKeysArray<string>Required
List of label keys to add to the contact. Label keys must exist to be added to the contact. Contact labels can be created with the findOrCreateLabel() function. You can use the queryLabels() function to view the currently existing labels.
Returns
Return Type:Promise<LabelContactResponse>
Was this helpful?
Yes
No

mergeContacts( )

Merges source contacts into a target contact.

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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Contacts
Manage Members and Contacts - all permissions
Learn more about permission scopes.
Copy
function mergeContacts(targetContactId: string, targetContactRevision: number, options: MergeContactsOptions): Promise<MergeContactsResponse>
Method Parameters
targetContactIdstringRequired
Target contact ID.

targetContactRevisionnumberRequired
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.

optionsMergeContactsOptions
Merge contacts options.
Returns
Return Type:Promise<MergeContactsResponse>
Was this helpful?
Yes
No

queryContacts( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Creates a query to retrieve a list of contacts.

The queryContacts() function builds a query to retrieve a list of contacts and returns a ContactsQueryBuilder object.

The returned object contains the query definition, which is typically used to run the query using the find() function.

You can refine the query by chaining ContactsQueryBuilder functions onto the query. ContactsQueryBuilder functions enable you to sort, filter, and control the results queryContacts() returns.

queryContacts() runs with these ContactsQueryBuilder defaults, which you can override:

The functions that are chained to queryContacts() are applied in the order they are called. For example, if you apply ascending('info.company') and then descending('info.name.last'), the results are sorted first by the company name, and then, if there are multiple results with the same company, the items are sorted by last name.

PROPERTYSUPPORTED FILTERS & SORTING
_ideq(),ne(),in(),exists()
_createdDateeq(),ne(),gt(),lt(),ge(),le(),ascending(),descending()
_updatedDateeq(),ne(),gt(),lt(),ge(),le()
lastActivity.activityDateeq(),ne(),gt(),lt(),ge(),le(),ascending(),descending()
primaryInfo.emaileq(),ne(),in(),exists(),startsWith(),ascending(),descending()
primaryInfo.phoneeq(),ne(),in(),exists(),startsWith()
info.name.firsteq(),ne(),in(),exists(),startsWith(),ascending(),descending()
info.name.lasteq(),ne(),in(),exists(),startsWith(),ascending(),descending()
info.companyeq(),ne(),in(),exists(),startsWith(),ascending(),descending()
info.jobTitleeq(),ne(),in(),exists(),startsWith(),ascending(),descending()
info.birthdateeq(),ne(),ascending(),descending()
info.localeeq(),ne(),in(),exists()
primaryEmail.emaileq(),ne(),in(),exists(),startsWith(),ascending(),descending()
primaryEmail.subscriptionStatuseq(),ne(),in()
primaryEmail.deliverabilityStatuseq(),ne(),in()
primaryPhone.countryCodeeq(),ne(),in(),exists(),startsWith(),ascending(),descending()
primaryPhone.e164Phoneeq(),ne(),in(),exists(),startsWith()
primaryPhone.formattedPhoneeq(),ne(),in(),exists(),startsWith(),ascending(),descending()
primaryPhone.subscriptionStatuseq(),ne(),in()
primaryPhone.phoneeq(),ne(),in(),exists(),startsWith()

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Contacts
Read Members and Contacts - all read permissions
Manage Contacts
Manage Members and Contacts - all permissions
Learn more about permission scopes.
Copy
function queryContacts(options: QueryContactsOptions): ContactsQueryBuilder
Method Parameters
optionsQueryContactsOptions
Query contact options.
Returns
Was this helpful?
Yes
No

unlabelContact( )

Removes labels from a contact.

The unlabelContact() function returns a Promise that resolves when the specified labels are removed from the contact.

If a label is no longer needed and you want to remove it from all contacts, you can remove it with the Labels deleteLabel() function.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Contacts
Manage Members and Contacts - all permissions
Learn more about permission scopes.
Copy
function unlabelContact(contactId: string, labelKeys: Array<string>): Promise<UnlabelContactResponse>
Method Parameters
contactIdstringRequired
ID of the contact to remove labels from.

labelKeysArray<string>Required
List of label keys to remove from the contact.
Returns
Return Type:Promise<UnlabelContactResponse>
Was this helpful?
Yes
No

updateContact( )

Updates a contact's properties.

The updateContact() function returns a Promise that resolves when the specified contact's information is updated.

Each time the contact is updated, revision increments by 1. The existing revision must be included when updating the contact. This ensures you're working with the latest contact information, and prevents unintended overwrites.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Contacts
Manage Members and Contacts - all permissions
Learn more about permission scopes.
Copy
function updateContact(contactId: string, info: ContactInfo, revision: number, options: UpdateContactOptions): Promise<UpdateContactResponse>
Method Parameters
contactIdstringRequired
ID of the contact to update.

infoContactInfoRequired
Contact info.

revisionnumberRequired
Revision number. When updating, include the existing revision to prevent conflicting updates.

optionsUpdateContactOptions
Contact update options.
Returns
Return Type:Promise<UpdateContactResponse>
Was this helpful?
Yes
No