Skip to main content

Managing users

All authentication in EVA relates to users in one way ore another. Users are exactly what you would think, nothing exciting. Employees are users, customers are users, we even have special user types for API integrations.

UserType​

The distinction between customers or employees is made on the Type property of the user:

This means that customers and employees also fall into the same pool of UserID's.

Note

If a user is both an employee and a customer, they have UserType 3 (1+2). UserType 3 is the default for newly created employees.

UserAccountType​

Aside from a UserType, you can also specify a UserAccountType. This type lets you define the account's login and searchability options, divided into three types:

Standard (0)

  • Has a unique login identifier (email/nickname)
  • Can login
  • Can be found in the UserSearch

Basic (1)

  • No unique identifier
  • Cannot login
  • Can be found in the UserSearch

Incognito (2)

  • No unique identifier
  • Cannot login
  • Cannot be found in the UserSearch
Changing user account types

To change the account type of a user, you can use the service UpdateUserAccountType:

When changing the AccountType from Standard to Incognito or Basic, all credentials and roles are removed.

When changing the AccountType from Incognito or Basic to Standard:

  • Uniqueness checks are done for the EmailAddress and Nickname
  • Default customer roles are generated
  • When no password is provided, one is generated and returned in the response
  • If configured, the user will receive a welcome to EVA email. If no valid password is provided, the email will also contain a generated password.

Create​

There are several ways to create users, but since we're talking about integrations, we're going to assume you'd like to sync users to EVA from an external system. For this, we use PushUser.

Basic information​

In its most basic form, this request requires only five properties:

{
  "UserType": "1",
  "EmailAddress": "pete@tortugapirate.com",
  "FirstName": "Pete",
  "LastName": "Pirate",
  "PhoneNumber": "0612345678"
}

When the request is successful, EVA returns the UserID for the newly created User. If the user already exists, EVA simply returns the existing user's ID.

In general, EVA determines whether the user is new by checking the following values:

  1. BackendID (seeing as that PushUser's often used in synergy with a 3rd party system)
  2. Email address
  3. Nickname
  4. DuplicateFiscalID (optional setting)

Incognito​

If a user is of the type Incognito, there will be no EmailAddress check. A unique NickName however is required, as it's used to log in and check the corresponding order; there will be no profile in the account and no password recovery service. This also means you can create as many anonymous accounts as you like with a single email address. Lastly, any changes made to an incognito user's order address, will only be applicable to that specific order.

Addresses​

To include Addresses:

{
    "UserType": "1",
    "EmailAddress": "pete@tortugapirate.com",
    "FirstName": "Pete",
    "LastName": "Pirate",
    "PhoneNumber": "0612345678",
    "ShippingAddress": {
        "Address1": "Conch Street",
        "Address2": "124",
        "City": "Bikini Bottom",
        "Country": "Pacific Ocean"
    }
}

BillingAddress follows the same method.

Subscriptions​

To include Subscriptions:

{
    "UserType": "1",
    "EmailAddress": "pete@tortugapirate.com",
    "FirstName": "Pete",
    "LastName": "Pirate",
    "PhoneNumber": "0612345678",
    "Subscriptions": [
        {
            "SubscriptionID": "5",
            "Subscribed": "true"
        }
    ]
}

CustomFields​

To include CustomFields:

{
    "UserType": "1",
    "EmailAddress": "pete@tortugapirate.com",
    "FirstName": "Pete",
    "LastName": "Pirate",
    "PhoneNumber": "0612345678",
    "CustomFields": [
        {
            "CustomFieldID": "5",
            "NumberValue": "10"
        }
    ]
}

Get​

To get information on a user, use GetUser. Naturally, the information that's returned depends on what has been set on the User in the first place.

{
    "ID": 56,
    "BackendID": "54",
    "EmailAddress": "michael@sfs.com",
    "FirstName": "Michael",
    "LastName": "Shipper",
    "FullName": "Michael Shipper",
    "Type": 2,
    "LanguageID": "en",
    "CountryID": "NL",
    "IsDeleted": false,
    "IsIncognito": false,
    "IsDebtor": false,
    "GravatarHash": "d2c8ea9ff0e75b1f1dae2e087bb10000",
    "Data": {},
    "CreatedByID": 54,
    "CreatedByFullName": "Pedro Pascal",
    "CreationTime": "2022-02-16T14:18:34.983Z",
    "ModifiedByFullName": "",
    "CustomFields": [
        {
            "CustomFieldID": 66,
            "Name": "Loyalty member",
            "DisplayName": "Loyalty member",
            "DataType": "Bool",
            "DataTypeID": 1,
            "Options": {
                "IsArray": false,
                "IsRequired": false
            },
            "BackendID": "is_loyalty_member",
            "IsEditableByUser": true,
            "IsArray": false
        },
        {
            "CustomFieldID": 67,
            "Name": "Coffee add-ons",
            "DisplayName": "Coffee add-ons",
            "DataType": "Enum",
            "DataTypeID": 4,
            "Options": {
                "IsArray": true,
                "IsRequired": false,
                "EnumValues": {
                    "sugar": "Sugar",
                    "mil": "Milk",
                    "soy_milk": "Soy milk"
                }
            },
            "BackendID": "coffee",
            "IsEditableByUser": true,
            "IsArray": true
        },
        {
            "CustomFieldID": 68,
            "Name": "Favorite color",
            "DisplayName": "Favorite color",
            "DataType": "String",
            "DataTypeID": 0,
            "Options": {
                "IsArray": false,
                "IsRequired": false,
                "MinimumLength": 2
            },
            "BackendID": "favo_color",
            "IsEditableByUser": true,
            "IsArray": false
        },
        {
            "CustomFieldID": 72,
            "Name": "Zip Code for Reporting",
            "DisplayName": "Zip Code for Reporting",
            "DataType": "String",
            "DataTypeID": 0,
            "Options": {
                "IsArray": false,
                "IsRequired": false
            },
            "BackendID": "Zip Code for Reporting",
            "IsEditableByUser": true,
            "IsArray": false
        }
    ],
    "AllowPasswordLogin": true,
    "AccountType": 0
}

Update​

In order to Update an existing User, you can use UpdateUser. It's possible to update all properties on a User, except for its BackendID, CustomID, UserType and EmailAddress. The request only expects a UserID and the properties you'd like to update.

To update a User's e-mail address, use UpdateUserEmailAddress.

Delete​

Deleting Users is a somewhat strange process. Whenever we delete Users, we don't actually delete them. Take a look at the response we got from GetUser; the User has a property IsDeleted. Whenever we delete a User, this property changes to true and the User will no longer be visible in any of our front ends. The data however, will still be there for the sake of historical accuracy.

To delete a User, use DeleteUser. Example request:

{
    "ID": "7"
}

Privacy data removals​

Generally, we do not allow for user deletion, in order for us to maintain historical order data. It is possible however, to formally delete user data for GDPR reasons. Such a deletion can only be requested, it will then take a certain amount of time before the user data is actually 'deleted'.

We can schedule a privacy removal request using CreatePrivacyRemovalRequest. Example request:

{
    "UserID": "6"
}

This service returns the ID for your newly created removal request.

After creating your request, we will kick off the process of replacing all personal information with bogus placeholders in order to maintain order history. This exceeds only the user data model. We're talking about customer interaction history, order history, any place really where your personal information is stored.

This process can only take place if there are no pending invoices for the requested user. If there are, EVA will try again in 24 hours.

To check on your removal progress, use GetPrivacyRemovalRequestByID. Use the ID that was returned to you by CreatePrivacyRemovalRequest. Example request:

{
    "ID": 1
}

This will return one of the following three statuses:

  • "Status": 0 = Requested
  • "Status": 1 = Processing
  • "Status": 2 = Done