Creating a User

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

You can view the latest reference documentation for the Advance API at https://yourorganization.com/HdaApi/rest/documentation/index.html, where yourorganization.com is the domain under which your Advance deployment is located.

Request

Request URL

POST https://{tenancymoniker}.{domain}/HdaApi/rest/v1.1/Users/{id}

Headers

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]

 

Parameters

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.

 

Examples

Example Request URL

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

Example Request JSON

{

    "firstName": "Emma",

    "lastName": "MacDiarmid",

    "emailAddress": "emma.macdiarmid@acmecorp.com",

    "roles": [

"SiteAdministrator"

],

    "sendEmail": true

}

Example Response

Status: 201 Created

Body: 4a404239-527c-4470-b53f-7cc7f46445bd

Code example

See Create User Example for further examples.

C#

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");
        }
    }
}