Setup

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

Copy Code
npm install @wix/crm

or

Copy Code
yarn add @wix/crm

Then import { contacts } from @wix/crm:

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

Introduction

When a new visitor first shares some of their contact information with your site, they're added to your Contact List. Once that happens, their details are available through the Contacts API.

Some examples of how a person can become a contact are:

  • A site visitor fills in a form with their contact details.
  • A site visitor signs up as a member of the site.
  • A site collaborator imports a contact or adds a contact manually.
  • A 3rd-party app creates a contact with the Contacts API.

Learn more about how you can manage your contact list.

With the Contacts APIs, you can:

  • Manage site contacts.
  • Manage contact labels.
  • Manage extended field definitions.
Was this helpful?
Yes
No
createContact( )
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 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.

Params
infoContactInfoRequired
Contact info.
optionsCreateContactOptions
Create contact options.
Response Object
CreateContactResponse
Was this helpful?
Yes
No
deleteContact( )
Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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.

Params
contactIdstringRequired
ID of the contact to delete.
Response Object
void
Was this helpful?
Yes
No
getContact( )
Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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 with 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(), and only for merged contacts. Deleted source contact IDs are not supported on any other function.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Contacts
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Params
_idstringRequired
ID of the contact to retrieve.
optionsGetContactOptions
Get contact options.
Response Object
Contact
Was this helpful?
Yes
No
labelContact( )
Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Adds labels to a contact.

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

Params
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 or retrieved with findOrCreateLabel() or queryLabels().
Response Object
LabelContactResponse
Was this helpful?
Yes
No
mergeContacts( )
Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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.
  • If merging more than one source contact, the 1st source is given precedence, then the 2nd, and so on.

Important: Merges cannot be undone. Use Preview Merge Contacts to test before merging.

Source contacts are deleted when merging. However, if a source contact is a site member or contributor, the merge fails because site contributors and members can't be deleted. Site members and contributors can be target contacts only.

After merging, if you call Get Contact with a deleted source contact ID, the target contact ID is returned. This is supported when calling Get Contact only. Deleted source contact IDs are not supported on any other endpoint.

Merging contacts triggers these webhooks:

  • Contact Merged is triggered.
  • Contact Updated is triggered for the target contact. originatedFrom is set to merge.
  • Contact Deleted is triggered for each source contact. originatedFrom is set to merge.

This function is not a universal function and runs only on the backend.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Contacts
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Params
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.
Response Object
MergeContactsResponse
Was this helpful?
Yes
No
unlabelContact( )
Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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 delete it with Labels deleteLabel().

Params
contactIdstringRequired
ID of the contact to remove labels from.
labelKeysArray<string>Required
List of label keys to remove from the contact.
Response Object
UnlabelContactResponse
Was this helpful?
Yes
No
updateContact( )
Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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 it prevents unintended overwrites.

Params
contactIdstringRequired
ID of the contact to update.
infoContactInfoRequired
Contact info.
optionsUpdateContactOptionsRequired
Contact update options.
Response Object
UpdateContactResponse
Was this helpful?
Yes
No