Creating a User (via API)

The Create user API method enables you to create a new user in an existing HotDocs Advance tenancy.

Prerequisites

Before making an 'create work item' request, you must have an access token to sign the request. You can retrieve an access token using one of the following flows:

Overview

The 'create user' API method is a command method. The API client invoking this method must have either a command or a root scope.

This method is useful when you want to create one or multiple new user accounts in a tenancy, using data sourced from another system. When the user is successfully created, the response contains the ID for the new user.

Authentication

See Authentication for more information about authenticating requests to the Advance API.

API Documentation

Request

Request URL

Headers

Parameters

Examples

Example Request URL

https://yourtenancy.yourorganization.com/HdaApi/rest/v1.1/Users/4a404239-527c-4470-b53f-7cc7f46445bd

Example Request JSON

Example Response

Code example

using System;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

namespace HotDocsAdvanceApiExamples
{
    public class UserRequest
    {
        public async Task<HttpStatusCode> CreateUser(string token)
        {
            // Create the 'create user' request  
            var userId = Guid.NewGuid();
            var request = CreateHttpRequestMessage(userId);

            //Send create user request to Advance
            using (var client = new HttpClient())
            {
                client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
                var response = await client.SendAsync(request);                
                return response.StatusCode;
            }
        }

        private HttpRequestMessage CreateHttpRequestMessage(Guid userId)
        {
            // Create the request for the 'create user' API endpoint
            var createUserUrl = string.Format("https://yourtenancy.yourorganization.com/HdaApi/rest/v1.1/Users/{0}", userId);


            return new HttpRequestMessage
            {
                RequestUri = new Uri(createUserUrl),
                Method = HttpMethod.Post,
                Content = GetRequestContent()
            };
        }

        private StringContent GetRequestContent()
        {
            // Generate the JSON request body required by the 'create user' method
            var json = "{ 'firstName': 'Emma', 'lastName': 'MacDiarmid', 'emailAddress': 'emma.macdiarmid@example.com', 'roles': [ 'SiteAdministrator'	], 'sendEmail': true }";
            return new StringContent(json, Encoding.UTF8, "application/json");
        }
    }
}

Key	Required	Description	Example value
Authorization	Yes	The Authorization header for the request. Uses the access token retrieved (see Prerequisites section above for more information).	Bearer [access token]

Name	Type	Location	Required	Description
tenancymoniker	String	URL	Yes	The tenancy moniker for the tenancy in which you want to create the new user account.
domain	String	URL	Yes	Your domain. For example, yourorganization.com.
id	Guid	URL	Yes	A new Guid to identify the user. The ID cannot be the same as that of an existing user.
firstName	String	Request body	Yes	The first name of the user.
lastName	String	Request body	No	The last name of the user.
emailAddress	String	Request body	Yes	Note: the e-mail address must be unique within the tenancy to which the user is allocated. The e-mail address for the user. The e-mail address is used when the user logs into Advance. It is also used for sending any necessary e-mails to the user. For example, if a user requests to reset their password.
roles	Array (string)	Request body	No	An array of administrative roles allocated to the user. If you leave this empty, the user will have standard (i.e. non-administrative) permissions. The administrative roles available are: SiteAdministrator ContentAdministrator Author
sendEmail	Boolean	Request body	No	Send an on-boarding e-mail to the user. The e-mail contains a link for the new user to login to the Advance UI and set their password.

Creating a User