Changes fields on a contact that already exists — its email, phone, name, or address.
POST https://www.wixapis.com/contacts/v5/contacts/search — locate the contactPATCH https://www.wixapis.com/contacts/v5/contacts/{contactId} — change its fieldsPOST https://www.wixapis.com/contacts/v5/contacts/{contactId}/addresses — add one addressContacts has two live versions. Use the v5 endpoints above for updates; the v4 update takes a
different, more deeply nested body, and mixing the two shapes is rejected with
400 {"message":"Expected an object"}.
When the user identifies a contact by name — "my contact Jordan Lee" — the lookup is Search Contacts. Query Contacts filters on a small closed set of fields that does not include the contact's name, so a query filtered by name is rejected:
Search Contacts takes a free-text expression, and matches on names. Note the doubled search —
the outer one is the search request, the inner one is the free-text clause:
Read both id and revision off the contact it returns. Step 2 needs both. Query Contacts is
still the right call when you already have an email address, a phone number or an id to filter on.
Copy this body and change the values. Only the fields you send are being set; id and revision
identify which contact and which version you are updating:
Swap email for phone ({ "phone": { "phone": "+1-212-555-0100" } }) or name to change those
instead. revision changes on every write, so re-read it if an update conflicts.
To attach one more address, post it to the contact's addresses sub-resource rather than sending
the whole contact — the address is appended, so existing addresses survive:
Note the doubled address here too: the outer object is the contact's address entry, which can
carry a tag, and the inner one is the postal address itself.
tag is one of OTHER, HOME, WORK, BILLING, SHIPPING, and that list is closed — there is
no "untagged" or "none" member. When the user did not say what kind of address it is, leave tag
out, exactly as above; inventing a value for that case is rejected:
subdivision in ISO 3166-2 formsubdivision is the 2-letter country code, a hyphen, then 1-3 characters for the state, region,
prefecture or province: US-NY, GB-ENG, FR-976. A bare state code is rejected, on updates as
well as on creates:
The Contacts reference describes this field as a "short code (2 or 3 letters)" and gives NY as
the example, which the server does not accept. Use the hyphenated form.
country is the plain ISO 3166-1 alpha-2 code
— US, no hyphen. Only subdivision carries the country prefix.
Last updated: 10 August 2026