Updating a Contact

POST /api/contacts/{id}.json

Modify the properties of a single Contact. 

When updating a Contact via the API you can:

  • update the Contact's basic information such as their name, email etc. 
  • modify the Contact's primary address. If the contact does not already have a primary address you may include a new address to add. 
  • grant access roles. If you include the accessRoles property in your payload, you must supply all access roles you wish to keep for the Contact. Evance will drop any existing grants if they are missing from your update request.

JSON payload example

In the example below we are requesting to update a new User in our website by supplying some basic information about the user and then inviting the user to check their details and set their own password. We're also setting their primary address and granting two access roles: customer and trade-account. However, although the customer permission is granted perpetually, the trade-account is only granted for a given period.

    "contact": {
        "firstname": "Bob",
        "lastname": "Bobsworth",
        "email": "bob@email.com",
        "company": null,
        "type": "user",
        "address": {
            "line1": "2 Sorrel Horse Mews",
            "line2": "Grimwade Street",
            "line3": "",
            "city": "Ipswich",
            "region": "Suffolk",
            "countryCode": "GB",
            "zip": "IP4 1LN"
        "accessRoles": [
                "reference": "trade-account",
                "expires": "2018-01-01T00:00:00+00:00",
                "status": "active"

Supplying a contact's primary address

Supplying a primary address is optional. In the example above you will notice the user's first name, last name and company field is not supplied to the address. The address will automatically inherit these fields from the Contact. Although you may also supply an alternative first name, last name and company field, we do not recommend it. 

If you supply an existing address object to a new Contact (i.e. the address is supplied with an "id" property) a new Address object will be generated.

Supplying access roles

You may supply an array of access roles in one of two formats:


A string containing the identifier for the existing access role. When supplying an access role as a string the default grant rules/settings for the access role will be enforced. If the access role's default rules require email verification or manual approval, these rules must be adhered to before the role is active.


An object containing the "reference" of an existing access role and any of the following properties:

reference The reference of an existing access role. You may not add new access roles when creating a contact.
expires The date the access role expires. This is supplied as a date and time string in ATOM format. 
status Supplying a "status" of "active" bypasses the default verification protocols for the access role and grants the role immediately.

You cannot create new Access Roles during this process. 

Adding tags

You can attach tags to Contacts using the tag property. This must contain an object with a single contactproperty (representing the default Contact Tag Type), which MUST be an array containing zero or more tag values.

    "contact": {
        "tags": {
            "contact": [

The tag values supplied may be new or existing tag values.

COVID-19 NOTICE – Business as Usual
Evance continues to provide all services and support throughout this difficult period. See our full statement here