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:
- Create, update, and remove contacts.
- Retrieve contacts to access their contact information.
- Merge duplicate contacts.
- Label and unlabel contacts for categorization purposes.
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.
Setup
To use the Contacts API, install the @wix/crm
package using npm or Yarn:
1npm install @wix/crm
or
1yarn add @wix/crm
Then import { contacts }
from @wix/crm
:
1import { contacts } from '@wix/crm'
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:function createContact(info: ContactInfo, options: CreateContactOptions): Promise<CreateContactResponse>
Contact info.
Create contact options.
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:function deleteContact(contactId: string): Promise<void>
ID of the contact to delete.
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:function getContact(_id: string, options: GetContactOptions): Promise<Contact>
ID of the contact to retrieve.
Get contact options.
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()
, orqueryLabels()
.
Permission Scopes
For app development, you must have one of the following permission scopes:function labelContact(contactId: string, labelKeys: Array<string>): Promise<LabelContactResponse>
ID of the contact to add labels to.
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.
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:function mergeContacts(targetContactId: string, targetContactRevision: number, options: MergeContactsOptions): Promise<MergeContactsResponse>
Target contact ID.
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.
Merge contacts options.
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.
Permission Scopes
For app development, you must have one of the following permission scopes:function queryContacts(options: QueryContactsOptions): ContactsQueryBuilder
Query contact options.
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:function unlabelContact(contactId: string, labelKeys: Array<string>): Promise<UnlabelContactResponse>
ID of the contact to remove labels from.
List of label keys to remove from the contact.
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:function updateContact(contactId: string, info: ContactInfo, revision: number, options: UpdateContactOptions): Promise<UpdateContactResponse>
ID of the contact to update.
Contact info.
Revision number. When updating, include the existing revision to prevent conflicting updates.
Contact update options.