Contacts

Note:
Before using these API endpoints, learn more about how to use WixHive contacts in your app.

GET/contacts

Returns all contacts that are part of the current site, determined by the application-id and instance-id parameters/headers. The results will be returned in cursored form. By default, all Contacts are returned.

Parameters:

Name	Data Type	Parameter Type	Description
fields	'NAME', 'COMPANY', 'EMAILS', 'PHONES', 'ADDRESSES', 'URLS', 'DATES', 'NOTES', 'CUSTOM','LINKS'	Query	The Contact fields to return. Multiple fields are separated by a comma, for example: NAME, EMAILS. System fields (like the contact’s id and ModifiedAt) are always returned.
email	String	Query	The email to search against
phone	String	Query	The phone number to search against
name.first	String	Query	The first name to search against
name.last	String	Query	The last name to search against
cursor	String	Query	The semi-optional cursor into the desired data. This cursor will expire after 30 minutes, it should not be cached.
pageSize	Integer (1-500)	Query	The number of results to return per page of data. Defaults to 25.
version (required)	Integer	Query	The specific version of this endpoint. This version uses semantic versioning, in the form of major.minor.path
application-id (required)	String	Query/ Header	The application definition ID. If sent through the header, this field must be prefixed with x-wix-
instance-id (required)	String	Query/ Header	The instance ID used for security validation with Wix. If sent through the header, this field must be prefixed with x-wix-
signature (required)	String	Query/ Header	The computed signature. If sent through the header, this field must be prefixed with x-wix-
timestamp (required)	Datetime	Query/ Header	The timestamp as an ISO 8601 timestamp. If sent through the header, this field must be prefixed with x-wix-

Example:

Copy

Response:

Here’s the full list of fields that can be part of the response.

The fields you’ll actually receive depend on the information you request and what we have in the system.

Name	Type	Description
total	Number	The total number of Contacts that can be returned
pageSize	Integer (1-500)	The number of results returned per cursor
previousCursor	String	The cursor used to access the previous set of contacts. Returns null if there are no previous results.
nextCursor	String	The cursor used to access the next set of contacts. Returns null if there are no more results.
results	Array[Objects]	An array of Contact items. Each contact object contains information about the contact.
results.id	String	Contact's ID
results.name	Object	Contact's name
results.name.prefix	String	Name prefix
results.name.first	String	First name
results.name.middle	String	Middle name
results.name.last	String	Last name
results.name.suffix	String	Name suffix
results.picture	String	URL of the contact's photo
results.company	Object	Contact's company details
results.company.role	String	Contact's role in the company
results.company.name	String	Contact's company name
results.emails	Array[Objects]	Contact's email addresses
results.emails.id	Number	ID of this email within the array
results.emails.tag	String	Tag for this email - home, work, etc
results.emails.email	String	Email address
results.emails.emailStatus	‘optOut’, ‘transactional’, ‘recurring’	The subscription status of the current email
results.emails.deliveryStatus	‘valid’, ‘spam’, ‘complaint’, ‘rejected’, ‘deferral’, ‘bounce’	Email delivery status:* valid: When emails are delivered successfully. * spam: When emails are marked as spam by the recipient. * complaint: When the recipient of the email has made a complaint to the email provider. * rejected: When the email is rejected by email provider. * deferral: When your email provider refuses to send emails. * bounce: When the mailbox is full, email address doesn't exist, etc.
results.phones	Array[Objects]	Contact's phone numbers
results.phones.id	Number	ID of this phone number within the array
results.phones.tag	String	Tag for this phone number - home, work, etc
results.phones.phone	String	Phone number
results.phones.normalizedPhone	String	Normalized phone number
results.addresses	Array[Objects]	Contact's addresses
results.addresses.id	Number	ID of this address within the array
results.addresses.tag	String	Tag for this address - home, work, etc
results.addresses.address	String	Street address
results.addresses.neighborhood	String	Neighborhood
results.addresses.city	String	City
results.addresses.region	String	Region, like a U.S state or a province in Canada
results.addresses.country	String	Country
results.addresses.postalCode	String	Postal code
results.urls	Array[Objects]	URLs associated with the contact, like Facebook or LinkedIn
results.urls.id	Number	ID of this URL within the array
results.urls.tag	String	Tag for this URL - personal, work, etc
results.urls.url	String	The URL
results.dates	Array[Objects]	Important dates for this Contact, like birthday
results.dates.id	Number	ID of this date within the array
results.dates.tag	String	Tag for this date - birthday, anniversary, etc
results.dates.date	Datetime	The date, as an ISO 8601 timestamp
results.createdAt	Date	The date this contact was created, as an ISO 8601 timestamp
results.links	Array[Objects]	An array of HATEOAS links to operations applicable to the Contact resource
results.links.href	String	The href of the operation relevant to this resource
results.links.rel	String	The relationship of this operation to the returned resource
results.modifiedAt	Timestamp	Date and time this contact was modified, as an ISO 8601 timestamp

Errors:

Here’s a list of possible errors and when they occur. Read more about our API errors.

HTTP Status Code	Reason/Error Message
400	* Invalid pageSize. Valid values are 25, 50 or 100. * Invalid or missing cursor. * Bad authentication credentials. * Bad request. Authentication credentials may be missing. * Missing endpoint version number.
403	* Unauthorized. Your app has been removed from the site. * Unauthorized. Insufficient permissions.
404	* App is not found on site. * Endpoint version number does not exist.
408	Timestamp expired on the request, please submit again with a new timestamp.
410	Cursor expired. The cursor is no longer valid. Please query again.

GET/contacts/{contactId}

Find a contact referenced by its ID, only relevant for the given site determined by the application-id and instance-id parameters/headers.

Parameters:

Name	Data Type	Parameter Type	Description
contactId (required)	String	Path	ID of the contact
version (required)	Integer	Query	The specific version of this endpoint. This version uses semantic versioning, in the form of major.minor.path
application-id (required)	String	Query/header	The application definition ID. If sent through the header, this field must be prefixed with x-wix-
instance-id (required)	String	Query/header	The instance ID used for security validation with Wix. If sent through the header, this field must be prefixed with x-wix-
signature (required)	String	Query/header	The computed signature. If sent through the header, this field must be prefixed with x-wix-
timestamp (required)	Datetime	Query/header	The timestamp as an ISO 8601 timestamp. If sent through the header, this field must be prefixed with x-wix-

Example:

Copy

Response:

Here’s the full list of fields that can be part of the response.

The fields you’ll actually receive depend on the information you request and what we have in the system.

Name	Type	Description
id	String	Contact's ID
name	Object	Contact's name
name.prefix	String	Name prefix
name.first	String	First name
name.middle	String	Middle name
name.last	String	Last name
name.suffix	String	Name suffix
picture	String	URL of the contact's photo
company	Object	Contact's company details
company.role	String	Contact's role in the company
company.name	String	Contact's company name
emails	Array[Objects]	Contact's email addresses
emails.id	Number	ID of this email within the array
emails.tag	String	Tag for this email - home, work, etc
emails.email	String	Email address
emails.emailStatus	‘optOut’, ‘transactional’, ‘recurring’	The subscription status of the current email
emails.deliveryStatus	‘valid’, ‘spam’, ‘complaint’, ‘rejected’, ‘deferral’, ‘bounce’	Email delivery status:* valid: When emails are delivered successfully. * spam: When emails are marked as spam by the recipient. * complaint: When the recipient of the email has made a complaint to the email provider. * rejected: When the email is rejected by email provider. * deferral: When your email provider refuses to send emails. * bounce: When the mailbox is full, email address doesn't exist, etc.
phones	Array[Objects]	Contact's phone numbers
phones.id	Number	ID of this phone number within the array
phones.tag	String	Tag for this phone number - home, work, etc
phones.phone	String	Phone number
phones.normalizedPhone	String	Normalized phone number
addresses	Array[Objects]	Contact's addresses
addresses.id	Number	ID of this address within the array
addresses.tag	String	Tag for this address - home, work, etc
addresses.address	String	Street address
addresses.neighborhood	String	Neighborhood
addresses.city	String	City
addresses.region	String	Region, like a U.S state or a province in Canada
addresses.country	String	Country
addresses.postalCode	String	Postal code
urls	Array[Objects]	URLs associated with the contact, like Facebook or LinkedIn
urls.id	Number	ID of this URL within the array
urls.tag	String	Tag for this URL - personal, work, etc
urls.url	String	The URL
dates	Array[Objects]	Important dates for this Contact, like birthday
dates.id	Number	ID of this date within the array
dates.tag	String	Tag for this date - birthday, anniversary, etc
dates.date	Datetime	The date, as an ISO 8601 timestamp
createdAt	Date	The date this contact was created, as an ISO 8601 timestamp
links	Array[Objects]	An array of HATEOAS links to operations applicable to the Contact resource
links.href	String	The href of the operation relevant to this resource
links.rel	String	The relationship of this operation to the returned resource
modifiedAt	Timestamp	Date and time this contact was modified, as an ISO 8601 timestamp

Errors:

Here’s a list of possible errors and when they occur. Read more about our API errors.

HTTP Status Code	Reason/Error Message
400	* Bad authentication credentials. * Bad request. Authentication credentials may be missing. * Missing endpoint version number.
403	* Unauthorized. Your app has been removed from the site. * Unauthorized. Insufficient permissions.
404	* Contact not found, or site for instance-id and app-id does not exist.* App is not found on site. * Endpoint version number does not exist.
408	Timestamp expired on the request, please submit again with a new timestamp.

POST/contacts

Version 2.0.0 : Reconciles Contact information with that of the WixHive’s.

Use this when your app has information about a site visitor that may already be registered as a Contact as part of the WixHive. Your app should provide as much information as possible so that we will find the best match for that Contact and return it with the reconciled information. If no match was found, we will create a new Contact.

Depending on the type of information, we will either add or dismiss changes. When the information can be added to a list, such as emails or phones, a new item will be added if no similar item exists. When the information cannot be added we dismiss the change, such is the case with name, company and picture. If your wish is to override such data, there are explicit ways to do so using the Contact’s ID and our HTTP API.

Parameters:

Name	Data Type	Parameter Type	Description
version (required)	Integer	Query	The specific version of this endpoint. This version uses semantic versioning, in the form of major.minor.path. Latest version is 2.0.0
application-id (required)	String	Query/header	The application definition ID. If sent through the header, this field must be prefixed with x-wix-
instance-id (required)	String	Query/header	The instance ID used for security validation with Wix. If sent through the header, this field must be prefixed with x-wix-
signature (required)	String	Query/header	The computed signature. If sent through the header, this field must be prefixed with x-wix-
timestamp (required)	Datetime	Query/header	The timestamp as an ISO 8601 timestamp. If sent through the header, this field must be prefixed with x-wix-
contactInfo (required)	Object	Body	The Contact object to reconcile. Important: Include at least the email or phone number in your request - we need it to create/update the contact.
contactInfo.name	Object	Body	Contact's name
contactInfo.name.prefix	String	Body	Name prefix
contactInfo.name.first	String	Body	First name
contactInfo.name.middle	String	Body	Middle name
contactInfo.name.last	String	Body	Last name
contactInfo.name.suffix	String	Body	Name suffix
contactInfo.picture	String	Body	URL of the contact's photo
contactInfo.company	Object	Body	Contact's company details
contactInfo.company.role	String	Body	Contact's role in the company
contactInfo.company.name	String	Body	Contact's company name
contactInfo.emails	Array[Objects]	Body	Contact's email addresses
contactInfo.emails.tag	String	Body	Tag for this email - home, work, etc
contactInfo.emails.email	String	Body	Email address
contactInfo.emails.emailStatus	‘optOut’, ‘transactional’, ‘recurring’	Body	The subscription status of the current email
contactInfo.emails.deliveryStatus	‘valid’, ‘spam’, ‘complaint’, ‘rejected’, ‘deferral’, ‘bounce’	Body	Email delivery status:* valid: When emails are delivered successfully. * spam: When emails are marked as spam by the recipient. * complaint: When the recipient of the email has made a complaint to the email provider. * rejected: When the email is rejected by email provider. * deferral: When your email provider refuses to send emails. * bounce: When the mailbox is full, email address doesn't exist, etc.
contactInfo.phones	Array[Objects]	Body	Contact's phone numbers
contactInfo.phones.tag	String	Body	Tag for this phone number - home, work, etc
contactInfo.phones.phone	String	Body	Phone number
contactInfo.addresses	Array[Objects]	Body	Contact's addresses
contactInfo.addresses.tag	String	Body	Tag for this address - home, work, etc
contactInfo.addresses.address	String	Body	Street address
contactInfo.addresses.neighborhood	String	Body	Neighborhood
contactInfo.addresses.city	String	Body	City
contactInfo.addresses.region	String	Body	Region, like a U.S state or a province in Canada
contactInfo.addresses.country	String	Body	Country
contactInfo.addresses.postalCode	String	Body	Postal code
contactInfo.urls	Array[Objects]Body		URLs associated with the contact, like Facebook or LinkedIn
contactInfo.urls.tag	String	Body	Tag for this URL - personal, work, etc
contactInfo.urls.url	String	Body	The URL
contactInfo.dates	Array[Objects]	Body	Important dates for this Contact, like birthday
contactInfo.dates.tag	String	Body	Tag for this date - birthday, anniversary, etc
contactInfo.dates.date	Datetime	Body	The date, as an ISO 8601 timestamp
contactInfo.notes	Array[objects]	Body	Notes associated with this contact
contactInfo.notescontent (required)	String	Body	The content of the note
contactInfo.custom	Array[objects]	Body	Custom fields associated with this contact
contactInfo.custom.field (required)	String	Body	The name of the custom field
contactInfo.custom.value (required)	String	Body	The value of the custom field

Example:

Copy

Response:

Here’s the full list of fields that can be part of the response.

The fields you’ll actually receive depend on the information you request and what we have in the system.

Name	Type	Description
contact	Object	The reconciled Contact and its information
contact.id	String	Contact's ID
contact.name	Object	Contact's name
contact.name.prefix	String	Name prefix
contact.name.first	String	First name
contact.name.middle	String	Middle name
contact.name.last	String	Last name
contact.name.suffix	String	Name suffix
contact.picture	String	URL of the contact's photo
contact.company	Object	Contact's company details
contact.company.role	String	Contact's role in the company
contact.company.name	String	Contact's company name
contact.emails	Array[Objects]	Contact's email addresses
contact.emails.id	Number	ID of this email within the array
contact.emails.tag	String	Tag for this email - home, work, etc
contact.emails.email	String	Email address
contact.emails.emailStatus	‘optOut’, ‘transactional’, ‘recurring’	The subscription status of the current email
contact.emails.deliveryStatus	‘valid’, ‘spam’, ‘complaint’, ‘rejected’, ‘deferral’, ‘bounce’	Email delivery status:* valid: When emails are delivered successfully. * spam: When emails are marked as spam by the recipient. * complaint: When the recipient of the email has made a complaint to the email provider. * rejected: When the email is rejected by email provider. * deferral: When your email provider refuses to send emails. * bounce: When the mailbox is full, email address doesn't exist, etc.
contact.phones	Array[Objects]	Contact's phone numbers
contact.phones.id	Number	ID of this phone number within the array
contact.phones.tag	String	Tag for this phone number - home, work, etc
contact.phones.phone	String	Phone number
contact.phones.normalizedPhone	String	Normalized phone number
contact.addresses	Array[Objects]	Contact's addresses
contact.addresses.id	Number	ID of this address within the array
contact.addresses.tag	String	Tag for this address - home, work, etc
contact.addresses.address	String	Street address
contact.addresses.neighborhood	String	Neighborhood
contact.addresses.city	String	City
contact.addresses.region	String	Region, like a U.S state or a province in Canada
contact.addresses.country	String	Country
contact.addresses.postalCode	String	Postal code
contact.urls	Array[Objects]	URLs associated with the contact, like Facebook or LinkedIn
contact.urls.id	Number	ID of this URL within the array
contact.urls.tag	String	Tag for this URL - personal, work, etc
contact.urls.url	String	The URL
contact.dates	Array[Objects]	Important dates for this Contact, like birthday
contact.dates.id	Number	ID of this date within the array
contact.dates.tag	String	Tag for this date - birthday, anniversary, etc
contact.dates.date	Datetime	The date, as an ISO 8601 timestamp
contact.createdAt	Date	The date this contact was created, as an ISO 8601 timestamp
contact.links	Array[Objects]	An array of HATEOAS links to operations applicable to the Contact resource
contact.linkshref	String	The href of the operation relevant to this resource
contact.linksrel	String	The relationship of this operation to the returned resource
contact.modifiedAt	Timestamp	Date and time this contact was modified, as an ISO 8601 timestamp
details	Object	Details about the reconciliation process
details.rejectedData	Array[objects]	Contact information which was rejected during the reconciliation process
details.existingData	Array[objects]	Contact information which was added by the WixHive
details.note	Object	Notes about the operation
details.note.returnedData	'COMPLETE' or 'RESTRICTED'	The level of details returned. Your app may receive RESTRICTED details when it does not have sufficient permissions.
details.note.requiredPermissionsForAllData	Array[string]	The permissions missing for your app to receive complete information from the WixHive.

Errors:

Here’s a list of possible errors and when they occur. Read more about our API errors.

HTTP Status Code	Reason/Error Message
200	Found match for Contact information which was supplied. Contact information was merged.
201	No match found for Contact information supplied, new Contact created.
400	* Contact data is malformed. * Contact info must contain at least one phone, email or address. * Bad authentication credentials. * Bad request. Authentication credentials may be missing. * Missing endpoint version number.
403	* Unauthorized. Your app has been removed from the site. * Unauthorized. Insufficient permissions.
404	* App is not found on site. * Endpoint version number does not exist.
408	Timestamp expired on the request, please submit again with a new timestamp.

POST/contacts/{contactId}/address

Adds a tag and address to a given Contact. Note: tags are not unique.

Parameters:

Name	Data Type	Parameter Type	Description
contactId (required)	String	Path	ID of the contact to edit
modifiedAt (required)	Timestamp	Query	The modification time of the Contact as received from Wix, as an ISO 8601 timestamp. Note: There may be times where another app makes an update to the same Contact. When that happens the modifiedAt value in our system will be updated and your app will have to re-fetch in order to sync. If your app tries to make an update using an outdated modifiedAt value it will receive an error.
version (required)	Integer	Query	The specific version of this endpoint. This version uses semantic versioning, in the form of major.minor.path
application-id (required)	String	Query/header	The application definition ID. If sent through the header, this field must be prefixed with x-wix-
instance-id (required)	String	Query/header	The instance ID used for security validation with Wix. If sent through the header, this field must be prefixed with x-wix-
signature (required)	String	Query/header	The computed signature. If sent through the header, this field must be prefixed with x-wix-
timestamp (required)	Datetime	Query/header	The timestamp as an ISO 8601 timestamp. If sent through the header, this field must be prefixed with x-wix-
address	Object	Body	The address to add to the contact
address.tag (required)	String	Body	Tag for this address - home, work, etc
address.address	String	Body	Street address
address.neighborhood	String	Body	Neighborhood
address.city	String	Body	City
address.region	String	Body	Region, like a U.S state or a province in Canada
address.country	String	Body	Country
address.postalCode	String	Body	Postal code

Example:

Copy

Response:

Here’s the full list of fields that can be part of the response.

The fields you’ll actually receive depend on the information you request and what we have in the system.

Name	Type	Description
id	String	Contact's ID
name	Object	Contact's name
name.prefix	String	Name prefix
name.first	String	First name
name.middle	String	Middle name
name.last	String	Last name
name.suffix	String	Name suffix
picture	String	URL of the contact's photo
company	Object	Contact's company details
company.role	String	Contact's role in the company
company.name	String	Contact's company name
emails	Array[Objects]	Contact's email addresses
emails.id	Number	ID of this email within the array
emails.tag	String	Tag for this email - home, work, etc
emails.email	String	Email address
emails.emailStatus	‘optOut’, ‘transactional’, ‘recurring’	The subscription status of the current email
emails.deliveryStatus	‘valid’, ‘spam’, ‘complaint’, ‘rejected’, ‘deferral’, ‘bounce’	Email delivery status:* valid: When emails are delivered successfully. * spam: When emails are marked as spam by the recipient. * complaint: When the recipient of the email has made a complaint to the email provider. * rejected: When the email is rejected by email provider. * deferral: When your email provider refuses to send emails. * bounce: When the mailbox is full, email address doesn't exist, etc.
phones	Array[Objects]	Contact's phone numbers
phones.id	Number	ID of this phone number within the array
phones.tag	String	Tag for this phone number - home, work, etc
phones.phone	String	Phone number
phones.normalizedPhone	String	Normalized phone number
addresses	Array[Objects]	Contact's addresses
addresses.id	Number	ID of this address within the array
addresses.tag	String	Tag for this address - home, work, etc
addresses.address	String	Street address
addresses.neighborhood	String	Neighborhood
addresses.city	String	City
addresses.region	String	Region, like a U.S state or a province in Canada
addresses.country	String	Country
addresses.postalCode	String	Postal code
urls	Array[Objects]	URLs associated with the contact, like Facebook or LinkedIn
urls.id	Number	ID of this URL within the array
urls.tag	String	Tag for this URL - personal, work, etc
urls.url	String	The URL
dates	Array[Objects]	Important dates for this Contact, like birthday
dates.id	Number	ID of this date within the array
dates.tag	String	Tag for this date - birthday, anniversary, etc
dates.date	Datetime	The date, as an ISO 8601 timestamp
createdAt	Date	The date this contact was created, as an ISO 8601 timestamp
links	Array[Objects]	An array of HATEOAS links to operations applicable to the Contact resource
links.href	String	The href of the operation relevant to this resource
links.rel	String	The relationship of this operation to the returned resource
modifiedAt	Timestamp	Date and time this contact was modified, as an ISO 8601 timestamp

Errors:

Here’s a list of possible errors and when they occur. Read more about our API errors.

HTTP Status Code	Reason/Error Message
400	* address information is malformed. * modifiedAt is missing.
404	* Contact not found. * Site for instance-id and app-id does not exist.
409	There was a conflict updating the current Contact. Please re-fetch the Contact to sync and get the most recent modifiedAt value, then try again.

POST/contacts/{contactId}/email

Adds a tag and email to a given Contact. Note: tags are not unique.

Parameters:

Name	Data Type	Parameter Type	Description
contactId (required)	String	Path	ID of the contact to edit
modifiedAt (required)	Timestamp	Query	The modification time of the Contact as received from Wix, as an ISO 8601 timestamp. Note: There may be times where another app makes an update to the same Contact. When that happens the modifiedAt value in our system will be updated and your app will have to re-fetch in order to sync. If your app tries to make an update using an outdated modifiedAt value it will receive an error.
version (required)	Integer	Query	The specific version of this endpoint. This version uses semantic versioning, in the form of major.minor.path
application-id (required)	String	Query/header	The application definition ID. If sent through the header, this field must be prefixed with x-wix-
instance-id (required)	String	Query/header	The instance ID used for security validation with Wix. If sent through the header, this field must be prefixed with x-wix-
signature (required)	String	Query/header	The computed signature. If sent through the header, this field must be prefixed with x-wix-
timestamp (required)	Datetime	Query/header	The timestamp as an ISO 8601 timestamp. If sent through the header, this field must be prefixed with x-wix-
email (required)	Object	Body	The email to add to the contact
email.tag	String	Body	Tag for this email - home, work, etc
email.email (required)	String	Body	Email address
email.emailStatus	‘optOut’, ‘transactional’, ‘recurring’	Body	The subscription status of the current email
email.deliveryStatus	‘valid’, ‘spam’, ‘complaint’, ‘rejected’, ‘deferral’, ‘bounce’	Body	Email delivery status:* valid: When emails are delivered successfully. * spam: When emails are marked as spam by the recipient. * complaint: When the recipient of the email has made a complaint to the email provider. * rejected: When the email is rejected by email provider. * deferral: When your email provider refuses to send emails. * bounce: When the mailbox is full, email address doesn't exist, etc.

Example:

Copy

Response:

Here’s the full list of fields that can be part of the response.

The fields you’ll actually receive depend on the information you request and what we have in the system.

Name	Type	Description
id	String	Contact's ID
name	Object	Contact's name
name.prefix	String	Name prefix
name.first	String	First name
name.middle	String	Middle name
name.last	String	Last name
name.suffix	String	Name suffix
picture	String	URL of the contact's photo
company	Object	Contact's company details
company.role	String	Contact's role in the company
company.name	String	Contact's company name
emails	Array[Objects]	Contact's email addresses
emails.id	Number	ID of this email within the array
emails.tag	String	Tag for this email - home, work, etc
emails.email	String	Email address
emails.emailStatus	‘optOut’, ‘transactional’, ‘recurring’	The subscription status of the current email
emails.deliveryStatus	‘valid’, ‘spam’, ‘complaint’, ‘rejected’, ‘deferral’, ‘bounce’	Email delivery status:* valid: When emails are delivered successfully. * spam: When emails are marked as spam by the recipient. * complaint: When the recipient of the email has made a complaint to the email provider. * rejected: When the email is rejected by email provider. * deferral: When your email provider refuses to send emails. * bounce: When the mailbox is full, email address doesn't exist, etc.
phones	Array[Objects]	Contact's phone numbers
phones.id	Number	ID of this phone number within the array
phones.tag	String	Tag for this phone number - home, work, etc
phones.phone	String	Phone number
phones.normalizedPhone	String	Normalized phone number
addresses	Array[Objects]	Contact's addresses
addresses.id	Number	ID of this address within the array
addresses.tag	String	Tag for this address - home, work, etc
addresses.address	String	Street address
addresses.neighborhood	String	Neighborhood
addresses.city	String	City
addresses.region	String	Region, like a U.S state or a province in Canada
addresses.country	String	Country
addresses.postalCode	String	Postal code
urls	Array[Objects]	URLs associated with the contact, like Facebook or LinkedIn
urls.id	Number	ID of this URL within the array
urls.tag	String	Tag for this URL - personal, work, etc
urls.url	String	The URL
dates	Array[Objects]	Important dates for this Contact, like birthday
dates.id	Number	ID of this date within the array
dates.tag	String	Tag for this date - birthday, anniversary, etc
dates.date	Datetime	The date, as an ISO 8601 timestamp
createdAt	Date	The date this contact was created, as an ISO 8601 timestamp
links	Array[Objects]	An array of HATEOAS links to operations applicable to the Contact resource
links.href	String	The href of the operation relevant to this resource
links.rel	String	The relationship of this operation to the returned resource
modifiedAt	Timestamp	Date and time this contact was modified, as an ISO 8601 timestamp

Errors:

Here’s a list of possible errors and when they occur. Read more about our API errors.

HTTP Status Code	Reason/Error Message
400	* email information is malformed. * modifiedAt is missing
404	Contact not found, or site for instance-id and app-id does not exist.
409	There was a conflict updating the current contact. Please re-fetch the contact to sync and get the most recent modifiedAt value, then try again.

POST/contacts/{contactId}/phone

Adds a tag and phone number to a given Contact. Note: tags are not unique.

Parameters:

Name	Data Type	Parameter Type	Description
contactId (required)	String	Path	ID of the contact to edit
modifiedAt (required)	Timestamp	Query	The modification time of the Contact as received from Wix, as an ISO 8601 timestamp. Note: There may be times where another app makes an update to the same Contact. When that happens the modifiedAt value in our system will be updated and your app will have to re-fetch in order to sync. If your app tries to make an update using an outdated modifiedAt value it will receive an error.
version (required)	Integer	Query	The specific version of this endpoint. This version uses semantic versioning, in the form of major.minor.path
application-id (required)	String	Query/header	The application definition ID. If sent through the header, this field must be prefixed with x-wix-
instance-id (required)	String	Query/header	The instance ID used for security validation with Wix. If sent through the header, this field must be prefixed with x-wix-
signature (required)	String	Query/header	The computed signature. If sent through the header, this field must be prefixed with x-wix-
timestamp (required)	Datetime	Query/header	The timestamp as an ISO 8601 timestamp. If sent through the header, this field must be prefixed with x-wix-
phone (required)	Object	Body	The phone number to add to the contact
phone.tag (required)	String	Body	Tag for this phone number - home, work, etc
phone.phone (required)	String	Body	The contact's raw phone number

Example:

Copy

Response:

Here’s the full list of fields that can be part of the response.

The fields you’ll actually receive depend on the information you request and what we have in the system.

Name	Type	Description
id	String	Contact's ID
name	Object	Contact's name
name.prefix	String	Name prefix
name.first	String	First name
name.middle	String	Middle name
name.last	String	Last name
name.suffix	String	Name suffix
picture	String	URL of the contact's photo
company	Object	Contact's company details
company.role	String	Contact's role in the company
company.name	String	Contact's company name
emails	Array[Objects]	Contact's email addresses
emails.id	Number	ID of this email within the array
emails.tag	String	Tag for this email - home, work, etc
emails.email	String	Email address
emails.emailStatus	‘optOut’, ‘transactional’, ‘recurring’	The subscription status of the current email
emails.deliveryStatus	‘valid’, ‘spam’, ‘complaint’, ‘rejected’, ‘deferral’, ‘bounce’	Email delivery status:* valid: When emails are delivered successfully. * spam: When emails are marked as spam by the recipient. * complaint: When the recipient of the email has made a complaint to the email provider. * rejected: When the email is rejected by email provider. * deferral: When your email provider refuses to send emails. * bounce: When the mailbox is full, email address doesn't exist, etc.
phones	Array[Objects]	Contact's phone numbers
phones.id	Number	ID of this phone number within the array
phones.tag	String	Tag for this phone number - home, work, etc
phones.phone	String	Phone number
phones.normalizedPhone	String	Normalized phone number
addresses	Array[Objects]	Contact's addresses
addresses.id	Number	ID of this address within the array
addresses.tag	String	Tag for this address - home, work, etc
addresses.address	String	Street address
addresses.neighborhood	String	Neighborhood
addresses.city	String	City
addresses.region	String	Region, like a U.S state or a province in Canada
addresses.country	String	Country
addresses.postalCode	String	Postal code
urls	Array[Objects]	URLs associated with the contact, like Facebook or LinkedIn
urls.id	Number	ID of this URL within the array
urls.tag	String	Tag for this URL - personal, work, etc
urls.url	String	The URL
dates	Array[Objects]	Important dates for this Contact, like birthday
dates.id	Number	ID of this date within the array
dates.tag	String	Tag for this date - birthday, anniversary, etc
dates.date	Datetime	The date, as an ISO 8601 timestamp
createdAt	Date	The date this contact was created, as an ISO 8601 timestamp
links	Array[Objects]	An array of HATEOAS links to operations applicable to the Contact resource
links.href	String	The href of the operation relevant to this resource
links.rel	String	The relationship of this operation to the returned resource
modifiedAt	Timestamp	Date and time this contact was modified, as an ISO 8601 timestamp

Errors:

Here’s a list of possible errors and when they occur. Read more about our API errors.

HTTP Status Code	Reason/Error Message
400	* phone number information is malformed. * modifiedAt is missing.
404	* Contact not found, or site for instance-id and app-id does not exist.
409	There was a conflict updating the current Contact. Please re-fetch the Contact to sync and get the most recent modifiedAt value, then try again.

POST/contacts/{contactId}/url

Adds a tag and url to a given Contact. Note: tags are not unique.

Parameters:

Name	Data Type	Parameter Type	Description
contactId (required)	String	Path	ID of the contact to edit
modifiedAt (required)	Timestamp	Query	The modification time of the Contact as received from Wix, as an ISO 8601 timestamp. Note: There may be times where another app makes an update to the same Contact. When that happens the modifiedAt value in our system will be updated and your app will have to re-fetch in order to sync. If your app tries to make an update using an outdated modifiedAt value it will receive an error.
application-id (required)	String	Query/header	The application definition ID. If sent through the header, this field must be prefixed with x-wix-
instance-id (required)	String	Query/header	The instance ID used for security validation with Wix. If sent through the header, this field must be prefixed with x-wix-
signature (required)	String	Query/header	The computed signature. If sent through the header, this field must be prefixed with x-wix-
timestamp (required)	Datetime	Query/header	The timestamp as an ISO 8601 timestamp. If sent through the header, this field must be prefixed with x-wix-
url (required)	Object	Body	The URL to add to the contact
url.tag	String	Body	Tag for this URL - personal, work, etc
url.url	String	Body	The URL

Example:

Copy

Response:

Here’s the full list of fields that can be part of the response.

The fields you’ll actually receive depend on the information you request and what we have in the system.

Name	Type	Description
id	String	Contact's ID
name	Object	Contact's name
name.prefix	String	Name prefix
name.first	String	First name
name.middle	String	Middle name
name.last	String	Last name
name.suffix	String	Name suffix
picture	String	URL of the contact's photo
company	Object	Contact's company details
company.role	String	Contact's role in the company
company.name	String	Contact's company name
emails	Array[Objects]	Contact's email addresses
emails.id	Number	ID of this email within the array
emails.tag	String	Tag for this email - home, work, etc
emails.email	String	Email address
emails.emailStatus	‘optOut’, ‘transactional’, ‘recurring’	The subscription status of the current email
emails.deliveryStatus	‘valid’, ‘spam’, ‘complaint’, ‘rejected’, ‘deferral’, ‘bounce’	Email delivery status:* valid: When emails are delivered successfully. * spam: When emails are marked as spam by the recipient. * complaint: When the recipient of the email has made a complaint to the email provider. * rejected: When the email is rejected by email provider. * deferral: When your email provider refuses to send emails. * bounce: When the mailbox is full, email address doesn't exist, etc.
phones	Array[Objects]	Contact's phone numbers
phones.id	Number	ID of this phone number within the array
phones.tag	String	Tag for this phone number - home, work, etc
phones.phone	String	Phone number
phones.normalizedPhone	String	Normalized phone number
addresses	Array[Objects]	Contact's addresses
addresses.id	Number	ID of this address within the array
addresses.tag	String	Tag for this address - home, work, etc
addresses.address	String	Street address
addresses.neighborhood	String	Neighborhood
addresses.city	String	City
addresses.region	String	Region, like a U.S state or a province in Canada
addresses.country	String	Country
addresses.postalCode	String	Postal code
urls	Array[Objects]	URLs associated with the contact, like Facebook or LinkedIn
urls.id	Number	ID of this URL within the array
urls.tag	String	Tag for this URL - personal, work, etc
urls.url	String	The URL
dates	Array[Objects]	Important dates for this Contact, like birthday
dates.id	Number	ID of this date within the array
dates.tag	String	Tag for this date - birthday, anniversary, etc
dates.date	Datetime	The date, as an ISO 8601 timestamp
createdAt	Date	The date this contact was created, as an ISO 8601 timestamp
links	Array[Objects]	An array of HATEOAS links to operations applicable to the Contact resource
links.href	String	The href of the operation relevant to this resource
links.rel	String	The relationship of this operation to the returned resource
modifiedAt	Timestamp	Date and time this contact was modified, as an ISO 8601 timestamp

Errors:

Here’s a list of possible errors and when they occur. Read more about our API errors.

HTTP Status Code	Reason/Error Message
400	* url information is malformed. * modifiedAt is missing.
404	Contact not found, or site for instance-id and app-id does not exist.
409	There was a conflict updating the current Contact. Please re-fetch the Contact to sync and get the most recent modifiedAt value, then try again.

POST/contacts/{contactId}/date

Adds a tag and date to a given Contact. Note: tags are not unique.

Parameters:

Name	Data Type	Parameter Type	Description
contactId (required)	String	Path	ID of the contact to edit
modifiedAt (required)	Timestamp	Query	The modification time of the Contact as received from Wix, as an ISO 8601 timestamp. Note: There may be times where another app makes an update to the same Contact. When that happens the modifiedAt value in our system will be updated and your app will have to re-fetch in order to sync. If your app tries to make an update using an outdated modifiedAt value it will receive an error.
version (required)	Integer	Query	The specific version of this endpoint. This version uses semantic versioning, in the form of major.minor.path
application-id (required)	String	Query/header	The application definition ID. If sent through the header, this field must be prefixed with x-wix-
instance-id (required)	String	Query/header	The instance ID used for security validation with Wix. If sent through the header, this field must be prefixed with x-wix-
signature (required)	String	Query/header	The computed signature. If sent through the header, this field must be prefixed with x-wix-
timestamp (required)	Datetime	Query/header	The timestamp as an ISO 8601 timestamp. If sent through the header, this field must be prefixed with x-wix-
date (required)	Object	Body	The date to add to the contact
date.tag	String	Body	Tag for this date - birthday, anniversary, etc
date.date (required)	Datetime	Body	The date, as an ISO 8601 timestamp

Example:

Copy

Response:

Here’s the full list of fields that can be part of the response.

The fields you’ll actually receive depend on the information you request and what we have in the system.

Name	Type	Description
id	String	Contact's ID
name	Object	Contact's name
name.prefix	String	Name prefix
name.first	String	First name
name.middle	String	Middle name
name.last	String	Last name
name.suffix	String	Name suffix
picture	String	URL of the contact's photo
company	Object	Contact's company details
company.role	String	Contact's role in the company
company.name	String	Contact's company name
emails	Array[Objects]	Contact's email addresses
emails.id	Number	ID of this email within the array
emails.tag	String	Tag for this email - home, work, etc
emails.email	String	Email address
emails.emailStatus	‘optOut’, ‘transactional’, ‘recurring’	The subscription status of the current email
emails.deliveryStatus	‘valid’, ‘spam’, ‘complaint’, ‘rejected’, ‘deferral’, ‘bounce’	Email delivery status:* valid: When emails are delivered successfully. * spam: When emails are marked as spam by the recipient. * complaint: When the recipient of the email has made a complaint to the email provider. * rejected: When the email is rejected by email provider. * deferral: When your email provider refuses to send emails. * bounce: When the mailbox is full, email address doesn't exist, etc.
phones	Array[Objects]	Contact's phone numbers
phones.id	Number	ID of this phone number within the array
phones.tag	String	Tag for this phone number - home, work, etc
phones.phone	String	Phone number
phones.normalizedPhone	String	Normalized phone number
addresses	Array[Objects]	Contact's addresses
addresses.id	Number	ID of this address within the array
addresses.tag	String	Tag for this address - home, work, etc
addresses.address	String	Street address
addresses.neighborhood	String	Neighborhood
addresses.city	String	City
addresses.region	String	Region, like a U.S state or a province in Canada
addresses.country	String	Country
addresses.postalCode	String	Postal code
urls	Array[Objects]	URLs associated with the contact, like Facebook or LinkedIn
urls.id	Number	ID of this URL within the array
urls.tag	String	Tag for this URL - personal, work, etc
urls.url	String	The URL
dates	Array[Objects]	Important dates for this Contact, like birthday
dates.id	Number	ID of this date within the array
dates.tag	String	Tag for this date - birthday, anniversary, etc
dates.date	Datetime	The date, as an ISO 8601 timestamp
createdAt	Date	The date this contact was created, as an ISO 8601 timestamp
links	Array[Objects]	An array of HATEOAS links to operations applicable to the Contact resource
links.href	String	The href of the operation relevant to this resource
links.rel	String	The relationship of this operation to the returned resource
modifiedAt	Timestamp	Date and time this contact was modified, as an ISO 8601 timestamp

Errors:

Here’s a list of possible errors and when they occur. Read more about our API errors.

HTTP Status Code	Reason/Error Message
400	* date information is malformed. * modifiedAt is missing.
404	Contact not found, or site for instance-id and app-id does not exist.
409	There was a conflict updating the current contact. Please re-fetch the cntact to sync and get the most recent modifiedAt value, then try again.

PUT/contacts/{contactId}/name

Edits name information for the given contact.

Parameters:

Name	Data Type	Parameter Type	Description
contactId (required)	String	Path	ID of the contact to edit
modifiedAt (required)	Timestamp	Query	The modification time of the Contact as received from Wix, as an ISO 8601 timestamp. Note: There may be times where another app makes an update to the same Contact. When that happens the modifiedAt value in our system will be updated and your app will have to re-fetch in order to sync. If your app tries to make an update using an outdated modifiedAt value it will receive an error.
version (required)	Integer	Query	The specific version of this endpoint. This version uses semantic versioning, in the form of major.minor.path
application-id (required)	String	Query/header	The application definition ID. If sent through the header, this field must be prefixed with x-wix-
instance-id (required)	String	Query/header	The instance ID used for security validation with Wix. If sent through the header, this field must be prefixed with x-wix-
signature (required)	String	Query/header	The computed signature. If sent through the header, this field must be prefixed with x-wix-
timestamp (required)	Datetime	Query/header	The timestamp as an ISO 8601 timestamp. If sent through the header, this field must be prefixed with x-wix-
name (required)	Object	Body	The edited name information
name.prefix	String	Body	Name prefix
name.first	String	Body	First name
name.middle	String	Body	Middle name
name.last	String	Body	Last name
name.suffix	String	Body	Name suffix

Example:

Copy

Response:

Here’s the full list of fields that can be part of the response.

The fields you’ll actually receive depend on the information you request and what we have in the system.

Name	Type	Description
id	String	Contact's ID
name	Object	Contact's name
name.prefix	String	Name prefix
name.first	String	First name
name.middle	String	Middle name
name.last	String	Last name
name.suffix	String	Name suffix
picture	String	URL of the contact's photo
company	Object	Contact's company details
company.role	String	Contact's role in the company
company.name	String	Contact's company name
emails	Array[Objects]	Contact's email addresses
emails.id	Number	ID of this email within the array
emails.tag	String	Tag for this email - home, work, etc
emails.email	String	Email address
emails.emailStatus	‘optOut’, ‘transactional’, ‘recurring’	The subscription status of the current email
emails.deliveryStatus	‘valid’, ‘spam’, ‘complaint’, ‘rejected’, ‘deferral’, ‘bounce’	Email delivery status:* valid: When emails are delivered successfully. * spam: When emails are marked as spam by the recipient. * complaint: When the recipient of the email has made a complaint to the email provider. * rejected: When the email is rejected by email provider. * deferral: When your email provider refuses to send emails. * bounce: When the mailbox is full, email address doesn't exist, etc.
phones	Array[Objects]	Contact's phone numbers
phones.id	Number	ID of this phone number within the array
phones.tag	String	Tag for this phone number - home, work, etc
phones.phone	String	Phone number
phones.normalizedPhone	String	Normalized phone number
addresses	Array[Objects]	Contact's addresses
addresses.id	Number	ID of this address within the array
addresses.tag	String	Tag for this address - home, work, etc
addresses.address	String	Street address
addresses.neighborhood	String	Neighborhood
addresses.city	String	City
addresses.region	String	Region, like a U.S state or a province in Canada
addresses.country	String	Country
addresses.postalCode	String	Postal code
urls	Array[Objects]	URLs associated with the contact, like Facebook or LinkedIn
urls.id	Number	ID of this URL within the array
urls.tag	String	Tag for this URL - personal, work, etc
urls.url	String	The URL
dates	Array[Objects]	Important dates for this Contact, like birthday
dates.id	Number	ID of this date within the array
dates.tag	String	Tag for this date - birthday, anniversary, etc
dates.date	Datetime	The date, as an ISO 8601 timestamp
createdAt	Date	The date this contact was created, as an ISO 8601 timestamp
links	Array[Objects]	An array of HATEOAS links to operations applicable to the Contact resource
links.href	String	The href of the operation relevant to this resource
links.rel	String	The relationship of this operation to the returned resource
modifiedAt	Timestamp	Date and time this contact was modified, as an ISO 8601 timestamp

Errors:

Here’s a list of possible errors and when they occur. Read more about our API errors.

HTTP Status Code	Reason/Error Message
400	* name information is malformed. * modifiedAt is missing.
404	Contact not found, or site for instance-id and app-id does not exist.
409	There was a conflict updating the current contact. Please re-fetch the cntact to sync and get the most recent modifiedAt value, then try again.

PUT/contacts/{contactId}/company

Edits company information for the given contact.

Parameters:

Name	Data Type	Parameter Type	Description
contactId (required)	String	Path	ID of the contact to edit
modifiedAt (required)	Timestamp	Query	The modification time of the Contact as received from Wix, as an ISO 8601 timestamp.
version (required)	Integer	Query	The specific version of this endpoint. This version uses semantic versioning, in the form of major.minor.path
application-id (required)	String	Query/header	The application definition ID. If sent through the header, this field must be prefixed with x-wix-
instance-id (required)	String	Query/header	The instance ID used for security validation with Wix. If sent through the header, this field must be prefixed with x-wix-
signature (required)	String	Query/header	The computed signature. If sent through the header, this field must be prefixed with x-wix-
timestamp (required)	Datetime	Query/header	The timestamp as an ISO 8601 timestamp. If sent through the header, this field must be prefixed with x-wix-
company (required)	Object	Body	The edited company information
company.role	String	Body	Contact's role in the company
company.name	String	Body	Contact's company name

Example:

Copy

Response:

Here’s the full list of fields that can be part of the response.

The fields you’ll actually receive depend on the information you request and what we have in the system.

Name	Type	Description
id	String	Contact's ID
name	Object	Contact's name
name.prefix	String	Name prefix
name.first	String	First name
name.middle	String	Middle name
name.last	String	Last name
name.suffix	String	Name suffix
picture	String	URL of the contact's photo
company	Object	Contact's company details
company.role	String	Contact's role in the company
company.name	String	Contact's company name
emails	Array[Objects]	Contact's email addresses
emails.id	Number	ID of this email within the array
emails.tag	String	Tag for this email - home, work, etc
emails.email	String	Email address
emails.emailStatus	‘optOut’, ‘transactional’, ‘recurring’	The subscription status of the current email
emails.deliveryStatus	‘valid’, ‘spam’, ‘complaint’, ‘rejected’, ‘deferral’, ‘bounce’	Email delivery status:* valid: When emails are delivered successfully. * spam: When emails are marked as spam by the recipient. * complaint: When the recipient of the email has made a complaint to the email provider. * rejected: When the email is rejected by email provider. * deferral: When your email provider refuses to send emails. * bounce: When the mailbox is full, email address doesn't exist, etc.
phones	Array[Objects]	Contact's phone numbers
phones.id	Number	ID of this phone number within the array
phones.tag	String	Tag for this phone number - home, work, etc
phones.phone	String	Phone number
phones.normalizedPhone	String	Normalized phone number
addresses	Array[Objects]	Contact's addresses
addresses.id	Number	ID of this address within the array
addresses.tag	String	Tag for this address - home, work, etc
addresses.address	String	Street address
addresses.neighborhood	String	Neighborhood
addresses.city	String	City
addresses.region	String	Region, like a U.S state or a province in Canada
addresses.country	String	Country
addresses.postalCode	String	Postal code
urls	Array[Objects]	URLs associated with the contact, like Facebook or LinkedIn
urls.id	Number	ID of this URL within the array
urls.tag	String	Tag for this URL - personal, work, etc
urls.url	String	The URL
dates	Array[Objects]	Important dates for this Contact, like birthday
dates.id	Number	ID of this date within the array
dates.tag	String	Tag for this date - birthday, anniversary, etc
dates.date	Datetime	The date, as an ISO 8601 timestamp
createdAt	Date	The date this contact was created, as an ISO 8601 timestamp
links	Array[Objects]	An array of HATEOAS links to operations applicable to the Contact resource
links.href	String	The href of the operation relevant to this resource
links.rel	String	The relationship of this operation to the returned resource
modifiedAt	Timestamp	Date and time this contact was modified, as an ISO 8601 timestamp

Errors:

Here’s a list of possible errors and when they occur. Read more about our API errors.

HTTP Status Code	Reason/Error Message
400	* company information is malformed. * modifiedAt is missing.
404	Contact not found, or site for instance-id and app-id does not exist.
409	There was a conflict updating the current contact. Please re-fetch the cntact to sync and get the most recent modifiedAt value, then try again.

PUT/contacts/{contactId}/address/{addressId}

Edits address information for the given Contact. Note: tags are not unique.

Parameters:

Name	Data Type	Parameter Type	Description
addressId (required)	String	Path	ID of this address within the array
contactId (required)	String	Path	ID of the contact to edit
modifiedAt (required)	Timestamp	Query	The modification time of the Contact as received from Wix, as an ISO 8601 timestamp. Note: There may be times where another app makes an update to the same Contact. When that happens the modifiedAt value in our system will be updated and your app will have to re-fetch in order to sync. If your app tries to make an update using an outdated modifiedAt value it will receive an error.
version (required)	Integer	Query	The specific version of this endpoint. This version uses semantic versioning, in the form of major.minor.path
application-id (required)	String	Query/header	The application definition ID. If sent through the header, this field must be prefixed with x-wix-
instance-id (required)	String	Query/header	The instance ID used for security validation with Wix. If sent through the header, this field must be prefixed with x-wix-
signature (required)	String	Query/header	The computed signature. If sent through the header, this field must be prefixed with x-wix-
timestamp (required)	Datetime	Query/header	The timestamp as an ISO 8601 timestamp. If sent through the header, this field must be prefixed with x-wix-
address (required)	Object	The edited address information
address.tag	String	Body	Tag for this address - home, work, etc
address.address	String	Body	Street address
address.neighborhood	String	Body	Neighborhood
address.city	String	Body	City
address.region	String	Body	Region, like a U.S state or a province in Canada
address.country	String	Body	Country
address.postalCode	String	Body	Postal code

Example:

Copy

Response:

Here’s the full list of fields that can be part of the response.

The fields you’ll actually receive depend on the information you request and what we have in the system.

Name	Type	Description
id	String	Contact's ID
name	Object	Contact's name
name.prefix	String	Name prefix
name.first	String	First name
name.middle	String	Middle name
name.last	String	Last name
name.suffix	String	Name suffix
picture	String	URL of the contact's photo
company	Object	Contact's company details
company.role	String	Contact's role in the company
company.name	String	Contact's company name
emails	Array[Objects]	Contact's email addresses
emails.id	Number	ID of this email within the array
emails.tag	String	Tag for this email - home, work, etc
emails.email	String	Email address
emails.emailStatus	‘optOut’, ‘transactional’, ‘recurring’	The subscription status of the current email
emails.deliveryStatus	‘valid’, ‘spam’, ‘complaint’, ‘rejected’, ‘deferral’, ‘bounce’	Email delivery status:* valid: When emails are delivered successfully. * spam: When emails are marked as spam by the recipient. * complaint: When the recipient of the email has made a complaint to the email provider. * rejected: When the email is rejected by email provider. * deferral: When your email provider refuses to send emails. * bounce: When the mailbox is full, email address doesn't exist, etc.
phones	Array[Objects]	Contact's phone numbers
phones.id	Number	ID of this phone number within the array
phones.tag	String	Tag for this phone number - home, work, etc
phones.phone	String	Phone number
phones.normalizedPhone	String	Normalized phone number
addresses	Array[Objects]	Contact's addresses
addresses.id	Number	ID of this address within the array
addresses.tag	String	Tag for this address - home, work, etc
addresses.address	String	Street address
addresses.neighborhood	String	Neighborhood
addresses.city	String	City
addresses.region	String	Region, like a U.S state or a province in Canada
addresses.country	String	Country
addresses.postalCode	String	Postal code
urls	Array[Objects]	URLs associated with the contact, like Facebook or LinkedIn
urls.id	Number	ID of this URL within the array
urls.tag	String	Tag for this URL - personal, work, etc
urls.url	String	The URL
dates	Array[Objects]	Important dates for this Contact, like birthday
dates.id	Number	ID of this date within the array
dates.tag	String	Tag for this date - birthday, anniversary, etc
dates.date	Datetime	The date, as an ISO 8601 timestamp
createdAt	Date	The date this contact was created, as an ISO 8601 timestamp
links	Array[Objects]	An array of HATEOAS links to operations applicable to the Contact resource
links.href	String	The href of the operation relevant to this resource
links.rel	String	The relationship of this operation to the returned resource
modifiedAt	Timestamp	Date and time this contact was modified, as an ISO 8601 timestamp

Errors:

Here’s a list of possible errors and when they occur. Read more about our API errors.

HTTP Status Code	Reason/Error Message
400	* address information is malformed. * address id is not found. * modifiedAt is missing.
404	Contact not found, or site for instance-id and app-id does not exist.
409	There was a conflict updating the current contact. Please re-fetch the cntact to sync and get the most recent modifiedAt value, then try again.

PUT/contacts/{contactId}/email/{emailId}

Edits email information for the given Contact. Note: tags are not unique.

Parameters:

Name	Data Type	Parameter Type	Description
emailId (required)	String	Path	ID of the email to edit
contactId (required)	String	Path	ID of the contact to edit
modifiedAt (required)	Timestamp	Query	The modification time of the Contact as received from Wix, as an ISO 8601 timestamp. Note: There may be times where another app makes an update to the same Contact. When that happens the modifiedAt value in our system will be updated and your app will have to re-fetch in order to sync. If your app tries to make an update using an outdated modifiedAt value it will receive an error.
version (required)	Integer	Query	The specific version of this endpoint. This version uses semantic versioning, in the form of major.minor.path
application-id (required)	String	Query/header	The application definition ID. If sent through the header, this field must be prefixed with x-wix-
instance-id (required)	String	Query/header	The instance ID used for security validation with Wix. If sent through the header, this field must be prefixed with x-wix-
signature (required)	String	Query/header	The computed signature. If sent through the header, this field must be prefixed with x-wix-
timestamp (required)	Datetime	Query/header	The timestamp as an ISO 8601 timestamp. If sent through the header, this field must be prefixed with x-wix-
email (required)	Object	Body	Contact's email address
email.tag	String	Body	Tag for this email - home, work, etc
email.email (required)	String	Body	Email address
emails.emailStatus	‘optOut’, ‘transactional’, ‘recurring’	Body	The subscription status of the current email
emails.deliveryStatus	‘valid’, ‘spam’, ‘complaint’, ‘rejected’, ‘deferral’, ‘bounce’	Body	Email delivery status:* valid: When emails are delivered successfully. * spam: When emails are marked as spam by the recipient. * complaint: When the recipient of the email has made a complaint to the email provider. * rejected: When the email is rejected by email provider. * deferral: When your email provider refuses to send emails. * bounce: When the mailbox is full, email address doesn't exist, etc.

Example:

Copy

Response:

Here’s the full list of fields that can be part of the response.

The fields you’ll actually receive depend on the information you request and what we have in the system.

Name	Type	Description
id	String	Contact's ID
name	Object	Contact's name
name.prefix	String	Name prefix
name.first	String	First name
name.middle	String	Middle name
name.last	String	Last name
name.suffix	String	Name suffix
picture	String	URL of the contact's photo
company	Object	Contact's company details
company.role	String	Contact's role in the company
company.name	String	Contact's company name
emails	Array[Objects]	Contact's email addresses
emails.id	Number	ID of this email within the array
emails.tag	String	Tag for this email - home, work, etc
emails.email	String	Email address
emails.emailStatus	‘optOut’, ‘transactional’, ‘recurring’	The subscription status of the current email
emails.deliveryStatus	‘valid’, ‘spam’, ‘complaint’, ‘rejected’, ‘deferral’, ‘bounce’	Email delivery status:* valid: When emails are delivered successfully. * spam: When emails are marked as spam by the recipient. * complaint: When the recipient of the email has made a complaint to the email provider. * rejected: When the email is rejected by email provider. * deferral: When your email provider refuses to send emails. * bounce: When the mailbox is full, email address doesn't exist, etc.
phones	Array[Objects]	Contact's phone numbers
phones.id	Number	ID of this phone number within the array
phones.tag	String	Tag for this phone number - home, work, etc
phones.phone	String	Phone number
phones.normalizedPhone	String	Normalized phone number
addresses	Array[Objects]	Contact's addresses
addresses.id	Number	ID of this address within the array
addresses.tag	String	Tag for this address - home, work, etc
addresses.address	String	Street address
addresses.neighborhood	String	Neighborhood
addresses.city	String	City
addresses.region	String	Region, like a U.S state or a province in Canada
addresses.country	String	Country
addresses.postalCode	String	Postal code
urls	Array[Objects]	URLs associated with the contact, like Facebook or LinkedIn
urls.id	Number	ID of this URL within the array
urls.tag	String	Tag for this URL - personal, work, etc
urls.url	String	The URL
dates	Array[Objects]	Important dates for this Contact, like birthday
dates.id	Number	ID of this date within the array
dates.tag	String	Tag for this date - birthday, anniversary, etc
dates.date	Datetime	The date, as an ISO 8601 timestamp
createdAt	Date	The date this contact was created, as an ISO 8601 timestamp
links	Array[Objects]	An array of HATEOAS links to operations applicable to the Contact resource
links.href	String	The href of the operation relevant to this resource
links.rel	String	The relationship of this operation to the returned resource
modifiedAt	Timestamp	Date and time this contact was modified, as an ISO 8601 timestamp

Errors:

Here’s a list of possible errors and when they occur. Read more about our API errors.

HTTP Status Code	Reason/Error Message
400	* email information is malformed. * email id not found. * modifiedAt is missing.
404	Contact not found, or site for instance-id and app-id does not exist.
409	There was a conflict updating the current contact. Please re-fetch the cntact to sync and get the most recent modifiedAt value, then try again.

PUT/contacts/{contactId}/phone/{phoneId}

Edits phone number information for the given Contact. Note: tags are not unique.

Parameters:

Name	Data Type	Parameter Type	Description
phoneId (required)	String	Path	ID of the phone number to edit
contactId (required)	String	Path	ID of the contact to edit
modifiedAt (required)	Timestamp	Query	The modification time of the Contact as received from Wix, as an ISO 8601 timestamp. Note: There may be times where another app makes an update to the same Contact. When that happens the modifiedAt value in our system will be updated and your app will have to re-fetch in order to sync. If your app tries to make an update using an outdated modifiedAt value it will receive an error.
version (required)	Integer	Query	The specific version of this endpoint. This version uses semantic versioning, in the form of major.minor.path
application-id (required)	String	Query/header	The application definition ID. If sent through the header, this field must be prefixed with x-wix-
instance-id (required)	String	Query/header	The instance ID used for security validation with Wix. If sent through the header, this field must be prefixed with x-wix-
phone (required)	Object	Body	The edited phone number information
phone.tag (required)	String	Body	Tag for this phone number - home, work, etc
phone.phone (required)	String	Body	Phone number

Example:

Copy

Response:

Here’s the full list of fields that can be part of the response.

The fields you’ll actually receive depend on the information you request and what we have in the system.

Name	Type	Description
id	String	Contact's ID
name	Object	Contact's name
name.prefix	String	Name prefix
name.first	String	First name
name.middle	String	Middle name
name.last	String	Last name
name.suffix	String	Name suffix
picture	String	URL of the contact's photo
company	Object	Contact's company details
company.role	String	Contact's role in the company
company.name	String	Contact's company name
emails	Array[Objects]	Contact's email addresses
emails.id	Number	ID of this email within the array
emails.tag	String	Tag for this email - home, work, etc
emails.email	String	Email address
emails.emailStatus	‘optOut’, ‘transactional’, ‘recurring’	The subscription status of the current email
emails.deliveryStatus	‘valid’, ‘spam’, ‘complaint’, ‘rejected’, ‘deferral’, ‘bounce’	Email delivery status:* valid: When emails are delivered successfully. * spam: When emails are marked as spam by the recipient. * complaint: When the recipient of the email has made a complaint to the email provider. * rejected: When the email is rejected by email provider. * deferral: When your email provider refuses to send emails. * bounce: When the mailbox is full, email address doesn't exist, etc.
phones	Array[Objects]	Contact's phone numbers
phones.id	Number	ID of this phone number within the array
phones.tag	String	Tag for this phone number - home, work, etc
phones.phone	String	Phone number
phones.normalizedPhone	String	Normalized phone number
addresses	Array[Objects]	Contact's addresses
addresses.id	Number	ID of this address within the array
addresses.tag	String	Tag for this address - home, work, etc
addresses.address	String	Street address
addresses.neighborhood	String	Neighborhood
addresses.city	String	City
addresses.region	String	Region, like a U.S state or a province in Canada
addresses.country	String	Country
addresses.postalCode	String	Postal code
urls	Array[Objects]	URLs associated with the contact, like Facebook or LinkedIn
urls.id	Number	ID of this URL within the array
urls.tag	String	Tag for this URL - personal, work, etc
urls.url	String	The URL
dates	Array[Objects]	Important dates for this Contact, like birthday
dates.id	Number	ID of this date within the array
dates.tag	String	Tag for this date - birthday, anniversary, etc
dates.date	Datetime	The date, as an ISO 8601 timestamp
createdAt	Date	The date this contact was created, as an ISO 8601 timestamp
links	Array[Objects]	An array of HATEOAS links to operations applicable to the Contact resource
links.href	String	The href of the operation relevant to this resource
links.rel	String	The relationship of this operation to the returned resource
modifiedAt	Timestamp	Date and time this contact was modified, as an ISO 8601 timestamp

Errors:

Here’s a list of possible errors and when they occur. Read more about our API errors.

HTTP Status Code	Reason/Error Message
400	* phone number information is malformed. * phone number id not found. * modifiedAt is missing.
404	Contact not found, or site for instance-id and app-id does not exist.
409	There was a conflict updating the current contact. Please re-fetch the contact to sync and get the most recent modifiedAt value, then try again.

PUT/contacts/{contactId}/url/{urlId}

Edits url information for the given Contact. Note: tags are not unique.

Parameters:

Name	Data Type	Parameter Type	Description
urlId (required)	String	Path	ID of the URL to edit
contactId (required)	String	Path	ID of the contact to edit
modifiedAt (required)	Timestamp	Query	The modification time of the Contact as received from Wix, as an ISO 8601 timestamp. Note: There may be times where another app makes an update to the same Contact. When that happens the modifiedAt value in our system will be updated and your app will have to re-fetch in order to sync. If your app tries to make an update using an outdated modifiedAt value it will receive an error.
version (required)	Integer	Query	The specific version of this endpoint. This version uses semantic versioning, in the form of major.minor.path
application-id (required)	String	Query/header	The application definition ID. If sent through the header, this field must be prefixed with x-wix-
instance-id (required)	String	Query/header	The instance ID used for security validation with Wix. If sent through the header, this field must be prefixed with x-wix-
signature (required)	String	Query/header	The computed signature. If sent through the header, this field must be prefixed with x-wix-
timestamp (required)	Datetime	Query/header	The timestamp as an ISO 8601 timestamp. If sent through the header, this field must be prefixed with x-wix-
url (required)	Object	Body	The edited url information
url.tag (required)	String	Body	Tag for this URL - personal, work, etc
url.url (required)	String	Body	The URL

Example:

Copy

Response:

Here’s the full list of fields that can be part of the response.

The fields you’ll actually receive depend on the information you request and what we have in the system.

Name	Type	Description
id	String	Contact's ID
name	Object	Contact's name
name.prefix	String	Name prefix
name.first	String	First name
name.middle	String	Middle name
name.last	String	Last name
name.suffix	String	Name suffix
picture	String	URL of the contact's photo
company	Object	Contact's company details
company.role	String	Contact's role in the company
company.name	String	Contact's company name
emails	Array[Objects]	Contact's email addresses
emails.id	Number	ID of this email within the array
emails.tag	String	Tag for this email - home, work, etc
emails.email	String	Email address
emails.emailStatus	‘optOut’, ‘transactional’, ‘recurring’	The subscription status of the current email
emails.deliveryStatus	‘valid’, ‘spam’, ‘complaint’, ‘rejected’, ‘deferral’, ‘bounce’	Email delivery status:* valid: When emails are delivered successfully. * spam: When emails are marked as spam by the recipient. * complaint: When the recipient of the email has made a complaint to the email provider. * rejected: When the email is rejected by email provider. * deferral: When your email provider refuses to send emails. * bounce: When the mailbox is full, email address doesn't exist, etc.
phones	Array[Objects]	Contact's phone numbers
phones.id	Number	ID of this phone number within the array
phones.tag	String	Tag for this phone number - home, work, etc
phones.phone	String	Phone number
phones.normalizedPhone	String	Normalized phone number
addresses	Array[Objects]	Contact's addresses
addresses.id	Number	ID of this address within the array
addresses.tag	String	Tag for this address - home, work, etc
addresses.address	String	Street address
addresses.neighborhood	String	Neighborhood
addresses.city	String	City
addresses.region	String	Region, like a U.S state or a province in Canada
addresses.country	String	Country
addresses.postalCode	String	Postal code
urls	Array[Objects]	URLs associated with the contact, like Facebook or LinkedIn
urls.id	Number	ID of this URL within the array
urls.tag	String	Tag for this URL - personal, work, etc
urls.url	String	The URL
dates	Array[Objects]	Important dates for this Contact, like birthday
dates.id	Number	ID of this date within the array
dates.tag	String	Tag for this date - birthday, anniversary, etc
dates.date	Datetime	The date, as an ISO 8601 timestamp
createdAt	Date	The date this contact was created, as an ISO 8601 timestamp
links	Array[Objects]	An array of HATEOAS links to operations applicable to the Contact resource
links.href	String	The href of the operation relevant to this resource
links.rel	String	The relationship of this operation to the returned resource
modifiedAt	Timestamp	Date and time this contact was modified, as an ISO 8601 timestamp

Errors:

Here’s a list of possible errors and when they occur. Read more about our API errors.

HTTP Status Code	Reason/Error Message
400	* url information is malformed. * url id not found. * modifiedAt is missing.
404	Contact not found, or site for instance-id and app-id does not exist.
409	There was a conflict updating the current contact. Please re-fetch the contact to sync and get the most recent modifiedAt value, then try again.

PUT/contacts/{contactId}/date/{dateId}

Edits date information for the given Contact. Note: tags are not unique.

Parameters:

Name	Data Type	Parameter Type	Description
dateId (required)	String	Path	ID of the date to edit
contactId (required)	String	Path	ID of the contact to edit
modifiedAt (required)	Timestamp	Query	The modification time of the Contact as received from Wix, as an ISO 8601 timestamp. Note: There may be times where another app makes an update to the same Contact. When that happens the modifiedAt value in our system will be updated and your app will have to re-fetch in order to sync. If your app tries to make an update using an outdated modifiedAt value it will receive an error.
version (required)	Integer	Query	The specific version of this endpoint. This version uses semantic versioning, in the form of major.minor.path
application-id (required)	String	Query/header	The application definition ID. If sent through the header, this field must be prefixed with x-wix-
instance-id (required)	String	Query/header	The instance ID used for security validation with Wix. If sent through the header, this field must be prefixed with x-wix-
signature (required)	String	Query/header	The computed signature. If sent through the header, this field must be prefixed with x-wix-
timestamp (required)	Datetime	Query/header	The timestamp as an ISO 8601 timestamp. If sent through the header, this field must be prefixed with x-wix-
date (required)	Object	Body	The edited date information
dates.tag (required)	String	Body	Tag for this date - birthday, anniversary, etc
dates.date (required)	Datetime	Body	The date, as an ISO 8601 timestamp

Example:

Copy

Response:

Here’s the full list of fields that can be part of the response.

The fields you’ll actually receive depend on the information you request and what we have in the system.

Name	Type	Description
id	String	Contact's ID
name	Object	Contact's name
name.prefix	String	Name prefix
name.first	String	First name
name.middle	String	Middle name
name.last	String	Last name
name.suffix	String	Name suffix
picture	String	URL of the contact's photo
company	Object	Contact's company details
company.role	String	Contact's role in the company
company.name	String	Contact's company name
emails	Array[Objects]	Contact's email addresses
emails.id	Number	ID of this email within the array
emails.tag	String	Tag for this email - home, work, etc
emails.email	String	Email address
emails.emailStatus	‘optOut’, ‘transactional’, ‘recurring’	The subscription status of the current email
emails.deliveryStatus	‘valid’, ‘spam’, ‘complaint’, ‘rejected’, ‘deferral’, ‘bounce’	Email delivery status:* valid: When emails are delivered successfully. * spam: When emails are marked as spam by the recipient. * complaint: When the recipient of the email has made a complaint to the email provider. * rejected: When the email is rejected by email provider. * deferral: When your email provider refuses to send emails. * bounce: When the mailbox is full, email address doesn't exist, etc.
phones	Array[Objects]	Contact's phone numbers
phones.id	Number	ID of this phone number within the array
phones.tag	String	Tag for this phone number - home, work, etc
phones.phone	String	Phone number
phones.normalizedPhone	String	Normalized phone number
addresses	Array[Objects]	Contact's addresses
addresses.id	Number	ID of this address within the array
addresses.tag	String	Tag for this address - home, work, etc
addresses.address	String	Street address
addresses.neighborhood	String	Neighborhood
addresses.city	String	City
addresses.region	String	Region, like a U.S state or a province in Canada
addresses.country	String	Country
addresses.postalCode	String	Postal code
urls	Array[Objects]	URLs associated with the contact, like Facebook or LinkedIn
urls.id	Number	ID of this URL within the array
urls.tag	String	Tag for this URL - personal, work, etc
urls.url	String	The URL
dates	Array[Objects]	Important dates for this Contact, like birthday
dates.id	Number	ID of this date within the array
dates.tag	String	Tag for this date - birthday, anniversary, etc
dates.date	Datetime	The date, as an ISO 8601 timestamp
createdAt	Date	The date this contact was created, as an ISO 8601 timestamp
links	Array[Objects]	An array of HATEOAS links to operations applicable to the Contact resource
links.href	String	The href of the operation relevant to this resource
links.rel	String	The relationship of this operation to the returned resource
modifiedAt	Timestamp	Date and time this contact was modified, as an ISO 8601 timestamp

Errors:

Here’s a list of possible errors and when they occur. Read more about our API errors.

HTTP Status Code	Reason/Error Message
400	* date information is malformed. * date id not found. * modifiedAt is missing.
404	Contact not found, or site for instance-id and app-id does not exist.
409	There was a conflict updating the current contact. Please re-fetch the contact to sync and get the most recent modifiedAt value, then try again.

Did this help?