Contacts

Overview

A contact is someone relevant to the Wix user’s business – either a site visitor who has performed a meaningful interaction within the site, or a person who was added directly by the user.

Users can manage their contacts from the Wix Dashboard – they can add, view, or delete contacts, including the contacts your app will create.

How Does it Work?

With the WixHive, you can get information about contacts and also share information your app collects – like a contact’s name, email, address, etc. (see the Contact Schema for all properties):

  • When a user adds or updates a contact using your app, share it with the WixHive to create or update the contact. This is for any app that allows users to manage contacts or contact information (hotel guests, shipping addresses, etc).
  • When your app needs to use information about contacts, get it from the WixHive. You’ll be able to get information about all contacts – not just the ones created by your app.
Important: If your app collects contact information when site visitors perform actions on the site (like purchases or reservations), don’t use the methods shown below. Instead, post the activity – we’ll create the contact while also linking the contact to its activity on the site.
Create/Update Contacts

When you have information about a contact, there are three ways to share it with the WixHive – choose the one that best describes your use case:

Once you share the information, the contact is immediately created/updated, and users can see it in the Contacts section of the Wix Dashboard (it may take a few seconds to update).

Report information about a contact

This is the most common way to add information about a contact. You simply report the data your app collected, making sure to include at least one of these details – the contact’s email or phone number.

We’ll check if the contact already exists – if it does, we’ll update it. If not, we’ll create a new contact.

When to use it:

  • You don’t have the Contact ID
  • You have a lot of information about a specific contact (it’ll save you the hassle of posting each one separately!)

Here’s how:

Share all the information you have about the contact using the Wix.Contacts.reconcileContact SDK method or the POST /Contacts (version=2.0.0) HTTP API endpoint.

Remember to include the email or phone number in your request – we need it to create/update the contact.

Once posted, we’ll check if the contact already exists and immediately send you a response with this information:

  • If this contact doesn’t exist, we’ll create it and send you the Contact ID.
  • If the contact already exists, we’ll add the new information and send you:
    • The Contact ID
    • The reconciled information (we’ll send this only if your app has read permissions from the WixHive)
    • Any rejected data – if this contact already has a value for a property you sent, and the data type isn’t an array, we’ll dismiss it and send you the rejected data.
      You can override the existing information with your data by prompting the user to use your value instead – here’s how.
 Note: If we find more than one contact that matches the information you sent, we’ll return the contact that was created first.

Add specific information to an existing contact

When you already have the Contact ID, you can add a value to a specific property – as long as its data type is an array: email, phone, address, URL, and date. See the Contact Schema for a list of all properties and their data type.

What if the property’s data type isn’t an array? In that case, just report the information you have about the contact.

How to add a value to a specific property:

Use any one of the POST /Contacts/{ContactId}/* HTTP API endpoints (for example: POST /Contacts/{ContactId}/address).

Once posted, we’ll add the new information to the contact

Override information for an existing contact

You can override data as long as the Wix user approves the change – so make sure your UI includes the option for the user to select the correct data.

Here’s an example: The Wix user updated a contact’s name using your app. Your app reports this change – but since the contact already has a name, your data is rejected. All is not lost, though – just prompt the user to approve the change, and then override existing data with newer information from your app.

To use this method, you need:

  1. The Contact ID
  2. The user’s approval to override the information.
  3. If the property is an array, you need the ID of the specific value you are changing.

How to override information:

Once the user approves, you can update the value for a specific property – use any one of the PUT /Contacts/{ContactId}/* HTTP API endpoints.

 

Get Contact Details

There are three ways for your app to get information about contacts – it all depends on what you need:

  • Get information about a specific contact
  • Get a list of all contacts in a site
  • Get notifications when a contact is created or updated

Get information about a specific contact

If you have the Contact ID, your app can get information about a specific contact – use the GET /Contacts/{ContactID} HTTP API endpoint or the Wix.Contacts.getContactById SDK method.

Don’t have the Contact ID? There might be another way to get the information you need: If you have the contact’s email, phone, first or last name, you can get a list of all contacts in the site, and then filter the response to get details for this contact only.

Get a list of all contacts in a site

Your app can get a list of all contacts in a site, including their information – use the Wix.Contacts.getContacts SDK method or the GET /contacts HTTP API endpoint.

In the response, we send all the information we have for each contact in the site. If you’re using the HTTP API endpoint, you can specify what we send in the response:

  • To keep the response size small, you can request only certain fields – like the contacts’ emails. In the fields parameter, enter one or more values, like NAME, EMAIL, or ADDRESS (use a comma to separate the values).
  • If you only need information for specific contacts (and not all contacts in the site), you can tell us which results to send in the response. Specify one or more values in the following parameters: email, phone, name.first, or name.last. This is a great way to get details about a contact when you don’t have the Contact ID.

 

Get notifications when a contact is created or updated

You can sign up in your app’s page in the Dev Center to receive immediate notifications. These events will be delivered to your app via webhooks and will include the Contact ID.

Contacts Schema
NameTypeDescription

Was this page helpful?

What can we do to improve it?

What did you like about it?