About the Contacts API

The Contacts API allows you to create and manage contacts. When a new visitor first shares their contact information with a site, they're added to the site's contact list. You can then access contacts and their details using the Contacts API.

A site visitor becomes a contact when:

  • The site visitor:
    • Submits their contact details to a form, such as event registrations, customer support inquiries, or billing address submissions.
    • Registers as a member of the site.
  • A Wix user:
  • Imports a contact.
  • Adds a contact manually.
  • You:

Learn more about how Wix users can manage a site's contact list.

With the Contacts API, you can:

  • Create, manage, and categorize contacts.
  • Retrieve information about existing contacts.

Before you begin

It's important to note the following points before starting to code:

  • You can't label or unlabel a contact if the label doesn't exist. To retrieve or create a label, use the Labels API.
  • Merging a contact is irreversible.
  • Wix users can only be specified as the target contact when merging contacts.

Terminology

  • Label: A tag that enables Wix users 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.
Did this help?

Setup

@wix/crm

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

Copy

or

Copy

Then import { contacts } from @wix/crm:

Copy
Did this help?

createContact( )

Creates a new contact.

The info object must include at least one of the following:

  • Name
  • Phone number
  • Email address

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 to true.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage Members and Contacts - all permissions
Manage Contacts
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
infoContactInfoRequired

Contact info.

optionsCreateContactOptions

Create contact options.

Returns
Return Type:Promise<CreateContactResponse>
JavaScript
Errors
400Invalid Argument

There are 3 errors with this status code.

409Already Exists

There are 2 errors with this status code.

This method may also return standard errors. Learn more about standard Wix errors.

Did this help?

deleteContact( )

Deletes a contact.

Deleting a contact permanently removes it from the contact list. If a contact is also a site member or Wix user, or has a valid billing subscription, the contact can't be deleted. The related site member or Wix user must first be deleted and any valid billing subscriptions must be canceled, before the contact can be deleted.

Members are typically linked to contacts, and while they share a relationship, the member ID and contact ID are distinct identifiers. Make sure to specify the contact ID when calling Delete Contact.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage Members and Contacts - all permissions
Manage Contacts
Manage Members
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
contactIdstringRequired

ID of the contact to delete.

JavaScript
Errors
428Failed Precondition

There are 3 errors with this status code.

500Internal

There is 1 error with this status code.

This method may also return standard errors. Learn more about standard Wix errors.

Did this help?

getContact( )

Retrieves a contact.

Getting Merged Contacts

When a source contact is merged with a target contact, the source contact is deleted. When calling Get Contact for a merged contact, you can use the source or target contact ID. In both bases, the target contact is returned.

This is supported only when calling Get Contact on merged contacts. Previously deleted source contact IDs can't be used for any other method.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Set Up Automations
Manage Members and Contacts - all permissions
Read Members and Contacts - all read permissions
Manage Contacts
Read Contacts
Manage Events
Manage Restaurants - all permissions
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
_idstringRequired

ID of the contact to retrieve.

optionsGetContactOptions

Get contact options.

Returns
Return Type:Promise<Contact>
JavaScript
Errors
404Not Found

There is 1 error with this status code.

This method may also return standard errors. Learn more about standard Wix errors.

Did this help?

labelContact( )

Adds labels to a contact.

Use the Labels API to create or retrieve labels.

Members are typically linked to contacts, and while they share a relationship, the member ID and contact ID are distinct identifiers. Make sure to specify the contact ID when calling Label Contact.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage Members and Contacts - all permissions
Manage Contacts
Learn more about app permissions.
Method Declaration
Copy
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. Use the Labels API to create or retrieve labels.

Returns
Return Type:Promise<LabelContactResponse>
JavaScript
Errors
404Not Found

There is 1 error with this status code.

This method may also return standard errors. Learn more about standard Wix errors.

Did this help?