Adding a Contact

POST 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:

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": "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"
            }
        ],
        "tags": {
            "contact": [
                "Engineers",
                "QA"
            ]
        }
    },
    "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.

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:

String

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.

Object

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

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": [
                "Engineers",
                "QA"
            ]
        }
        ...
    }
}

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