Adding a Contact

POST /api/contacts.json

When adding a Contact via the API you can:

  • Provide the Contact's basic information such as their name, email etc. 
  • Set the Contact's primary address. 
  • Grant access permissions.
  • Invite a user to your website to set their own password or set the password via the API.

You may supply various different types of contact data:

user Requires the contact to have a first name, last name and password. If you do not supply a password you must invite the user to set their own password. The email address of a user must be unique. Attempting to add a user with an email address already in use by an existing user will result in an error. 
guest Guests are usually associated with orders and do not have a password protected account. However, you may add a guest before creating an order on their behalf. Guest data requires first name, last name and email address but is open to duplication - it does not have the same unique email restriction as user data. This means you may have one or more guest Contacts with the same email address. 
branch You may add additional branches to your organisation. Branch data requires the company field and email address but ignores password, first name and last name fields. Branches must have their own unique email addresses. Since a branch may not have a password the email address may be a duplicate of a user's email address. However, we strongly discourage this.
recipient Recipient data is data associated with email newsletter subscriptions. Recipient data only requires an email address. Recipient email addresses must be unique and must not conflict with a user's email address. Please do not use this facility for adding newsletter subscribers.

Note: you cannot add an hq Contact object.

JSON payload example

In the example below we are requesting to add a new User to 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": "",
        "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"
        "tags": {
            "contact": [
    "invite": true

Adding a user with a password

You may supply a password for a user when creating the Contact. The password must:

  • be supplied in plain text.
  • be greater than or equal to 8 characters in length.
  • contain letters and numbers.
The user's password will be encrypted using a one-way hash and may not be read once stored.

Inviting a user to set their password

You may omit the password field and opt to invite the user to create their own password. You may also provide a temporary password and invite the user to set a new one. In either scenario, the example above illustrates setting the "invite" property to true. Note, the invite property is supplied outside the contact data so that it does not conflict with any other properties for the contact.

The Contact will be sent an email containing a link to a page where they can review their basic information and supply a password. We recommend using this option if you are migrating contact data from an existing website. 

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

When creating a user with a password you may also supply an array of access roles. Access roles supplied for any other contact type will be ignored. You may supply each access role 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 when creating a new Contact.

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