Users

These endpoints allow for the invitation and management of users to an HQ subaccount.

POST /#subccount_id/invitation/team

Invite a new user to a subaccount.

Users can only be invited to a single subaccount via the public api. To assign multiple subaccounts to a newly invited user, please do so via the web application.

Additionally, adding further permissions to a newly invited user must also be completed via the web application; this endpoint will assign role type only.

Parameters:

• invitee_email_address (string) – Required. The email address of the user you'd like to invite.
• role (string) – Required. The role assigned to the newly created user. The invited user's role must be below your own assigned role. Valid values include: ‘response_only’, ‘author’, ‘editor‘, ‘full’, ‘owner’ (defined as ‘administrator’ in app), and ‘manager’. Role hierarchy is as follows: ‘parent’ > ‘manager’ > ‘owner’ (‘administrator’ in app) > ‘full’ > ‘editor’ > ‘author’ > ‘response_only’

Raises :Http400 if the role provided is invalid. Raises :Http401 if the requesting user is unable to create a user of that role type.

Sample Response [showhide]

POST /100/invitation/team
{
  "message": true
}

GET/#account_id/accounts/users

Lists the users of an account.

This endpoint allows owners and managers with the ‘manage_users’ permission to list the users for either the parent account, the parent account and all subs, or a particular subaccount.The list returned will include users that have accepted their invitation, and users that have not.

Additionally, there are params to include subaccount users, to filter via ‘account_id’, and to search for a specific user. This endpoint is paginated and will need to be called with pagination params if the response includes more than 500 users.

Parameters:

• include_sub_users (boolean) – Optional. Calling the endpoint using the ‘parent_account_id’ and this param set to ‘true’ will return the users associated with the parent account along with any users associated with any of the parent's subaccounts as well.
• searchterm (string) – Optional. Allows searching by the ‘user_id’, ‘user_name_first’, and ‘user_name_last’ values.
• filter_accounts (comma separated string) – Optional. Allows filtering of the results by returning users who have access to one of the passed accounts.

Returns :A response with a list of users including the accounts they have access to, the permissions they have, their role, and other user related data. Raises :Http404 if the parent account or requesting user does not exist. Raises :Http401 if the requesting user does not have access to the account or the ‘manage_users’ permission.

Sample Response [showhide]

GET /100/account/users
{
    "users": [
        {
            "accounts": [
                {
                    "account_id": 100,
                    "account_name": "Test Parent Account"
                }
            ],
            "create_ts": "Jun 21, 2012",
            "email": "emmaHQowner@myemma.com",
            "last_login_attempt": "Jul 22, 2021 02:47 PM",
            "role": "Parent",
            "user_group_list": [
                "account_create",
                "assets_access",
                "billing_access",
                "emma_account_default",
                "emma_agency_default",
                "emma_audience_default",
                "emma_campaigns_default",
                "emma_response_default",
                "exporting_access",
                "manage_api_key",
                "manage_sso",
                "manage_team",
                "public",
                "purging_access"
            ],
            "user_id": "emmaHQowner@myemma.com",
            "user_name_first": “Test”,
            "user_name_last": “Owner”
        }
    ]
}