Skip to navigation
How-to guides

How to create a room with a template

View as Markdown

This topic demonstrates how to create a Docusign room using a predefined template. If you’ve created a template for your organization in either Rooms for Mortgage or Rooms for Real Estate by following the steps in Using room templates and task lists, you can create rooms based on this template using the Rooms API.

To complete this how-to, the Rooms API must be enabled for your account. For more information, see creating a Rooms developer account.

Run this code example from our Quickstart or launcher projects: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.

Required data

Running the code in this how-to requires this data:

Data elementDescription
{API_ACCOUNT_ID}A GUID value that identifies your account. This value is automatically generated by Docusign for any account you create. Copy the value from the API Account ID field on the Apps and Keys page.
{BASE_PATH}A string value that forms the root of the URL required to make API calls. The base path value in the example code is set to target the developer environment at
https://<domain>/restapi/v2
Where <domain> is demo.rooms.docusign.com for the developer environment and rooms.docusign.com for production.
{ROLE_ID}A room-specific ID that can be allocated to a given user within a room. The role ID is necessary to set permissions on rooms for individuals within your Docusign organization. Retrieve this value with the Roles:GetRoles method.
{TEMPLATE_ID}A GUID value that identifies a Docusign template that is used to create a Docusign room. This value is automatically generated by Docusign when the template is created.

Step 1. Obtain your OAuth token

To make the API calls shown in this how-to, you need a valid OAuth access token. Docusign supports access tokens for three different recommended OAuth grant types: Public Authorization Code Grant, Confidential Authorization Code Grant, and JSON Web Token (JWT) Grant. Choose the OAuth grant type appropriate for your scenario.

See Authentication for guidance on your options to get an OAuth token.

Three icons that represent the three methods a user can use to obtain an OAuth token: JSON Web Token (JWT), Public Authorization Code Grant (ACG), and Confidential Authorization Code grant

Step 2. Construct your API headers

After you have a valid OAuth access token, you are ready to construct the API headers that you will pass to the API call. Construct your headers like this, but make sure to substitute your valid OAuth access token for {ACCESS_TOKEN}.

declare -a Headers=('--header' "Authorization: Bearer ${ACCESS_TOKEN}"
    '--header' "Accept: application/json"
    '--header' "Content-Type: application/json")

Step 3. Retrieve a Rooms template ID

To create a room by using a template, you must provide a template ID in the request body. To retrieve the template ID, make a request to the room_templates endpoint on the Accounts resource of the Rooms API, passing in your {API_ACCOUNT_ID}.

request_data=$(mktemp /tmp/request-rmtmp.XXXXXX)
echo ""
echo "Attempting to retrieve default role Id"
echo ""
response=$(mktemp /tmp/response-rmtmp.XXXXXX)
Status=$(curl -w '%{http_code}' -i --request GET "https://demo.rooms.docusign.com/restapi/v2/accounts/${account_id}/roles" \
    "${Headers[@]}" \
    --output ${response})
# If the status code returned is greater than 201 (OK / Accepted), display an error message with the API response.
if [[ "$Status" -gt "201" ]]; then
    echo ""
    echo "Unable to retrieve your account's role settings"
    echo ""
    cat $response
    exit 0
fi
echo ""
echo "Response:"
cat $response
echo ""
# Retrieve the role IDs from the API response and put them in an array.
roleIds=`cat $response | grep -o -P '(?<=roleId\":).*?(?=,")'`
arrRoleIds=($roleIds)
# Get the index of the role based on name and use that index for roleId. 
# Name of the role is 'Default Admin'
roles=`cat $response | grep -o -P '(?<=name\":).*?(?=,)'`
element="Default Admin"
roleId=$(GetRoleId "$roles" "$element" "$roleIds")
# Remove the temporary files
rm "$request_data"
rm "$response"
# Retrieve a Rooms office ID
# Create a temporary file to store the response
request_data=$(mktemp /tmp/request-rmtmp.XXXXXX)
echo ""
echo "Attempting to retrieve default office ID"
echo ""
response=$(mktemp /tmp/response-rmtmp.XXXXXX)
Status=$(curl -w '%{http_code}' -i --request GET "https://demo.rooms.docusign.com/restapi/v2/accounts/${account_id}/offices" \
    "${Headers[@]}" \
    --output ${response})
#If the status code returned is greater than 201 (OK / Accepted), display an error message with the API response.
if [[ "$Status" -gt "201" ]]; then
    echo ""
    echo "Unable to retrieve your account's office ids"
    echo ""
    cat $response
    exit 0
fi
echo ""
echo "Response:"
cat $response
echo ""
officeId=$(cat $response | grep officeId | sed 's/.*\"officeId\"://' | sed 's/,.*//')

Step 4. Construct the request body

Next, create the request body. To create a room, you need to specify some room attributes.

AttributeDescription
nameA string value that identifies the room.
roleIdA string value that specifies which group of users can control the room.
transactionSideIdA string value that defines the type of transaction that is occurring (such as buy, list, or dual). You can update this up until the transaction is completed.
request_data=$(mktemp /tmp/request-rms-001.XXXXXX)
printf \
    '
{
  "name": "Sample Room Creation",
  "roleId": "'"$roleId"'",
  "officeId": "'"$officeId"'",
  "RoomTemplateId": "'"$roomTemplateId"'",
  "transactionSideId": "listbuy",
  "fieldData": {
    "data" : {
     "address1": "123 EZ Street",
     "address2": "unit 10",
     "city": "Galaxian",
     "state": "US-HI",
     "postalCode": "11112",
     "companyRoomStatus": "5",
     "comments": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
      }
     }
}' >>$request_data

Step 5. Call the Rooms API

Now that you have constructed your API headers and request body, you’re ready to create the room. Make a POST request to the Rooms:CreateRoom endpoint and include the request body.

Here’s how you make the call, but make sure to substitute your API account ID for {ACCOUNT_ID}.

View the source code for this how-to on GitHub: Bash, C#, Java, Node, PHP, PowerShell, Python, or Ruby.

Status=$(curl -w '%{http_code}' -i --request POST https://demo.rooms.docusign.com/restapi/v2/accounts/${account_id}/rooms \
    "${Headers[@]}" \
    --data-binary @${request_data} \
    --output ${response})

Expected response

If you run this code example from our Quickstart or launcher projects, you should see a JSON response similar to this.

Sample response
roleID: 6xxxx2
TemplateId: 3xx2
Response:
{
  "roomId": "3xxxx6",
  "companyId": "1xxx2",
  "name": "Sample Rooms Creation from Template",
  "officeId": "3xxx2",
  "createdDate": "2020-08-06T21:19:19.37",
  "createdByUserId": "2xxxx4",
  "closedStatusId": ""
}

Next steps