Contacts

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 it Works

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.

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:

• Report information about a contact – Share any information your app collects about contact. We’ll match it to an existing contact or create a new one.
• Add specific information to an existing contact – When you have the Contact ID, you can add a value to a specific property if the property’s data type is an array (for example: email).
• Override information for an existing contact – When you have the Contact ID and the Wix user’s approval, you can replace data with newer information from your app.

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.

JS SDK

1
var contactInfo = {
2
   name: {first:"firstName", middle:"middleName", last:"lastName"},
3
   emails: [{tag:"main", email:"email@gmail.com"}]
4
};
5

6
Wix.Contacts.reconcileContact(contactInfo, function(ContactData), function(errorType));

HTTP API

1
POST /v1/contacts?version=2.0.0 HTTP/1.1
2
Accept: "*/*"
3
User-Agent: Restler for node.js
4
Host: openapi.wix.com
5
Accept-Encoding: gzip, deflate
6
x-wix-application-id: 13d6663a-d101-36f6-16e8-24723992a8bf
7
x-wix-instance-id: 13d6669a-1a08-51bc-0360-43e7a980348e
8
x-wix-timestamp: 2015-07-07T13:49:43.084Z
9
Content-Length: 82
10
content-type: application/json
11
x-wix-signature: MTQ2MmE0_QxNy1lMmExLWM5NWItM2Q2MzhkOTI2OTA0
12
Connection: keep-alive
13
{
14
   "emails":[{
15
      "tag":"work",
16
      "email":"karen_meep@wix.com",
17
      "emailStatus":"recurring"
18
   }]
19
}

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.

1
POST /v1/contacts/280ea988-9a4a-4804-8b62-90c5d7fc7391/address?version=1.0.0&modifiedAt=2015-07-09T13%3A24%3A08.653Z HTTP/1.1
2
Accept: "*/*"
3
User-Agent: Restler for node.js
4
Host: openapi.wix.com
5
Accept-Encoding: gzip, deflate
6
x-wix-application-id: 13d6663a-d101-36f6-16e8-24723992a8bf
7
x-wix-instance-id: 13d6669a-1a08-51bc-0360-43e7a980348e
8
x-wix-timestamp: 2015-07-09T13:24:12.367Z
9
Content-Length: 151
10
content-type: application/json
11
x-wix-signature: MTQ2MmE0_QxNy1lMmExLWM5NWItM2Q2MzhkOTI2OTA0
12
Connection: keep-alive
13
{
14
   "tag":"work",
15
   "address":"500 Terry A Francois",
16
   "neighborhood":"Awesomeville",
17
   "city":"San Francisco",
18
   "region":"CA",
19
   "country":"USA",
20
   "postalCode":"94158"
21
}

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.

1
PUT /v1/contacts/3ea03b98-0d73-4e18-af4e-da42c4f1e5c6/address/1?version=1.0.0&modifiedAt=2015-07-09T13%3A24%3A07.311Z  HTTP/1.1
2
Accept: "*/*"
3
User-Agent: Restler for node.js
4
Host: openapi.wix.com
5
Accept-Encoding: gzip, deflate
6
x-wix-application-id: 13d6663a-d101-36f6-16e8-24723992a8bf
7
x-wix-instance-id: 13d6669a-1a08-51bc-0360-43e7a980348e
8
x-wix-timestamp: 2015-07-09T13:24:11.009Z
9
Content-Length:  140
10
content-type: application/json
11
x-wix-signature: MTQ2MmE0_QxNy1lMmExLWM5NWItM2Q2MzhkOTI2OTA0
12
Connection: keep-alive
13
{
14
   "tag":"Wix NYC Lounge",
15
   "address":"235 W 23rd St",
16
   "neighborhood":"Wixville",
17
   "city":"NYC",
18
   "region":"NY",
19
   "country":"USA",
20
   "postalCode":"10011"
21
}

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.

JS SDK

1
Wix.Contacts.getContactById(id, function(data), function(errorType));

HTTP API

1
GET /v1/contacts/280ea988-9a4a-4804-8b62-90c5d7fc7391?version=1.0.0&application-id=13d6663a-d101-36f6-16e8-24723992a8bf&instance-id=13d6669a-1a08-51bc-0360-43e7a980348e×tamp=2015-07-09T13%3A24%3A11.949Z&signature=MTQ2MmE0_QxNy1lMmExLWM5NWItM2Q2MzhkOTI2OTA0 HTTP/1.1
2
Accept: "*/*"
3
User-Agent: Restler for node.js
4
Host: openapi.wix.com
5
Accept-Encoding: gzip, deflate
6
Content-Length: 0
7
Connection: keep-alive
8

9

10
Response:
11
HTTP/1.1 200 OK
12
X-Seen-By: sputnik1.aus_dsp
13
Date: Thu, 09 Jul 2015 13:24:09 GMT
14
Content-Type: application/json;charset=UTF-8
15
Content-Length: 1281
16
Server: sputnik1.aus
17
"id":"280ea988-9a4a-4804-8b62-90c5d7fc7391",
18
"tags": [
19
   "contacts/create",
20
   "contacts_server/new",
21
   "contacts_server/show" 
22
],
23
"notes":[ ],
24
"emails":[ ],
25
"phones":[ {
26
   "tag":"work",
27
   "phone":"+1-415-639-5555",
28
   "id":1,
29
   "normalizedPhone":"+14156395555"
30
}],
31
"addresses":[ ],
32
"dates":[ ],
33
"urls":[ ],
34
"custom":[ ],
35
"createdAt":"2015-07-09T13:24:08.653Z",
36
"links":[ {
37
   "rel":"unsubscribe",
38
   "href":"http://www.wix.com/my-account/contacts/unsubscribe?siteName=musicplayer&metaSiteId=0dc99bdb-6e44-4a74-b1ce-fb6c251d2d18&unsubscribeToken=abcefd4d5885911e7f4ea863ecce180388e169a39e4c714f1a99cb3376c2b706e7cbc8d202eefd38f12421e34429d44e519c1fc8b0663814dfb9334838ef939e76a9b40bdbcf57e8ff46f13272035cbb445fe65559299dd1ed48d4aea7087f26d4638b3196b3cb46baa73228a6278fed6fbe79df7882e3ba226ced0cd911ebfd3769603b1210035089e13c1b1107ceebb7c47679b5775d33927c49bcef2a3fa87bca94aa039d3b2f67c94643e5c9263b0bbd1e9f7a59b20a9e6eac2bc26783519b212256947ba9a90aca638d01b6323687c1a93c0e0fae3dd8ff1cbee9337c4b4b78a078f4f1c1f104c5677222e5fbd83ac7746dfda06c43d551a09a7fd4daf38c4272539bb80dddcd8e5c7c5fbb9e81f2f7a5a041bdb78ea0188700a880624c29ab180ec978fec93ba93bd3a5486a519bfe211a3d0b40d27590606ebc4ea07c81150cef0849e6a9156b5b4bda362c803ba602a0326bc0346938aa1550cf85f4b8abe3cf11a0271287d7ba45acfe670d",
39
   "id":1
40
}],
41
"modifiedAt":"2015-07-09T13:24:08.653Z"
42
}

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.

JS SDK

1
Wix.Contacts.getContacts(function(WixDataCursor), function(errorType));

HTTP API

1
GET /v1/contacts?version=1.0.0&pageSize=53&application-id=13d6663a-d101-36f6-16e8-24723992a8bf&instance-id=13d6669a-1a08-51bc-0360-43e7a980348e×tamp=2015-07-09T13%3A26%3A47.679Z&signature=MTQ2MmE0_QxNy1lMmExLWM5NWItM2Q2MzhkOTI2OTA0 HTTP/1.1
2
Accept: "*/*"
3
User-Agent: Restler for node.js
4
Host: openapi.wix.com
5
Accept-Encoding: gzip, deflate
6
Content-Length: 0
7
Connection: keep-alive

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