> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL. > > Documentation indexes by section: > - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt > - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt > - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt > - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt > > Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth > Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks > > OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json > MCP server: https://docusign.docs.buildwithfern.com/_mcp/server # How to create a room with data > Learn how to create a Docusign room with populated data. This topic demonstrates how to create a Docusign room that contains populated data. > **Note** > > Run this code example from our [Quickstart](/docs/esign-rest-api/quickstart) or launcher projects: [Bash](https://github.com/docusign/code-examples-bash), [C#](https://github.com/docusign/code-examples-csharp), [Java](https://github.com/docusign/code-examples-java), [Node.js](https://github.com/docusign/code-examples-node), [PHP](https://github.com/docusign/code-examples-php), [PowerShell](https://github.com/docusign/code-examples-powershell), [Python](https://github.com/docusign/code-examples-python), or [Ruby](https://github.com/docusign/code-examples-ruby). ## Required data Running the code in this how-to requires this data: | Data element | Description | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | \{API_ACCOUNT_ID} | A [GUID](http://guid.one/) 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](https://admindemo.docusign.com/authenticate?goTo=appsAndKeys) 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\://\/restapi/v2 Where \ is demo.rooms.docusign.com for the developer environment and rooms.docusign.com for production. | | \{OFFICE_ID} | An optional identifier for the office location that is responsible for the room itself. Retrieve this value with the [Offices:GetOffices](/docs/rooms-api/reference/offices/offices/getoffices) method. | | \{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](/docs/rooms-api/reference/roles/roles/getroles) method. | | Rooms enabled for your account | You will need access enabled to use the Rooms API. See [creating a Rooms developer account](/docs/rooms-api/rooms101/create-account). | | Rooms field data | On room creation, you can fill out form data in advance by specifying the field data. This is the set of fields that appears on the room's **Details** tab in the UI, such as `contactName` and `phone`. Retrieve the available fields that you can set with the [Rooms:GetRoomFieldSet](/docs/rooms-api/reference/rooms/rooms/getroomfieldset) method. | ## Step 1. Obtain your OAuth token To make the API call shown in this how-to, you need a valid OAuth access token with the `dtr.rooms.write` scope enabled. 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. > **Note** > > See [Authentication](/docs/rooms-api/rooms101/auth) 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](/_fern-files/_img/64f473773042ee439449a096bf7673292b1585b86a4ccc55f82ba0dda41f61a1.webp) ## 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}. **`Bash`** ```bash title="Bash" declare -a Headers=('--header' "Authorization: Bearer ${ACCESS_TOKEN}" \ '--header' "Accept: application/json" \ '--header' "Content-Type: application/json") ``` **`C#`** ```csharp title="C#" var apiClient = new DocuSignClient(basePath); apiClient.Configuration.DefaultHeader.Add("Authorization", $"Bearer {accessToken}"); var roomsApi = new RoomsApi(apiClient); var rolesApi = new RolesApi(apiClient); ``` **`Java`** ```java title="Java" RoomsApi roomsApi = createRoomsApiClient(this.session.getBasePath(), this.user.getAccessToken()); ``` **`Node.js`** ```javascript title="Node.js" let dsApiClient = new docusignRooms.ApiClient(); dsApiClient.setBasePath(args.basePath); dsApiClient.addDefaultHeader('Authorization', 'Bearer ' + args.accessToken); ``` **`PHP`** ```php title="PHP" $config = new Configuration(); $config->setHost('https://demo.rooms.docusign.com/restapi'); $config->addDefaultHeader('Authorization', 'Bearer ' . $args['ds_access_token']); $this->apiClient = new ApiClient($config); ``` **`PowerShell`** ```text title="PowerShell" $headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]" $headers.add("Authorization", "Bearer $accessToken") $headers.add("Accept", "application/json") $headers.add("Content-Type", "application/json") ``` **`Python`** ```python title="Python" api_client = create_rooms_api_client( access_token=args["access_token"] ) ``` **`Ruby`** ```ruby title="Ruby" api_client = DocuSign_Rooms::ApiClient.new(configuration) api_client.set_default_header('Authorization', "Bearer #{args[:access_token]}") ``` ## Step 3. Construct your request body Next, create the request body. To create a room, you need to specify some room attributes. | Attribute | Description | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | A string value that identifies the room. | | `roleId` | A string value that specifies which group of users can control the room. | | `transactionSideId` | A 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. | **`Bash`** ```bash title="Bash" printf \ ' { "name": "Sample Room Creation", "roleId": "'"$roleId"'", "transactionSideId": "listbuy", "officeId": "'"$officeId"'", "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 ``` **`C#`** ```csharp title="C#" var newRoom = BuildRoom(model, clientRole); private static RoomForCreate BuildRoom(RoomModel model, RoleSummary clientRole) { var newRoom = new RoomForCreate { Name = model.Name, RoleId = clientRole.RoleId, TransactionSideId = "buy", FieldData = new FieldDataForCreate { Data = new Dictionary { { "address1", "Street 1" }, { "address2", "Unit 10" }, { "city", "New York" }, { "postalCode", "11112" }, { "companyRoomStatus", "5" }, { "state", "US-NY" }, { "comments", @"New room for sale." }, }, }, }; return newRoom; } ``` **`Java`** ```java title="Java" Room createdRoom = CreateRoomService.createRoomFromModel( roomsApi, this.session.getAccountId(), CreateRoomService.createRoomModel(adminRole.getRoleId(), args.getRoomName())); ``` **`Node.js`** ```javascript title="Node.js" let roomWithData = makeRoomsWithData(args.roomsWithDataArgs); function makeRoomsWithData(args) { return { body: { name: args.roomName, roleId: args.roleId, 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.`, }, }, }, }; } ``` **`PHP`** ```php title="PHP" $room = new RoomForCreate( [ 'name' => $args["room_name"], 'role_id' => $role_id, 'transaction_side_id' => "listbuy", 'field_data' => new FieldDataForCreate( ['data' => [ 'address1' => '111', 'address2' => 'unit 10', 'city' => 'Galaxian', 'state' => 'US-HI', 'postalCode' => '88888', 'companyRoomStatus' => '5', 'comments' => 'Lorem ipsum dolor sit amet, consectetur adipiscin', ] ] ) ] ); ``` **`PowerShell`** ```text title="PowerShell" $body = @" { "name": "Sample Room Creation", "roleId": "$roleId", "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." } } } "@ ``` **`Python`** ```python title="Python" room = RoomForCreate( name=args["room_name"], role_id=role_id, transaction_side_id="listbuy", field_data=FieldDataForCreate( data={ 'address1': '123 EZ Street', 'address2': 'unit 10', 'city': 'Galaxian', 'state': 'US-HI', 'postalCode': '88888', 'companyRoomStatus': '5', 'comments': '''Lorem ipsum dolor sit amet, consectetur adipiscin''' } ) ) ``` **`Ruby`** ```ruby title="Ruby" DocuSign_Rooms::RoomForCreate.new( { name: args[:room_name], roleId: args[:role_id], transactionSideId: 'buy', fieldData: DocuSign_Rooms::FieldDataForCreate.new( data: { address1: '123 EZ Street', address2: 'unit 10', city: 'Galaxian', state: 'US-HI', postalCode: '88888', companyRoomStatus: '5', comments: 'Lorem ipsum dolor sit amet, consectetur adipiscin' } ) } ) ``` ## Step 4. Call the Rooms API Now that you have constructed your API headers and request body, make a POST request to the [Rooms:CreateRoom](/docs/rooms-api/reference/rooms/rooms/createroom) endpoint and include the request body to create a new room. Here’s how you make the call, but make sure to substitute your API account ID for \{ACCOUNT_ID} > **Note** > > View the source code for this how-to on GitHub: [Bash](https://github.com/docusign/code-examples-bash/blob/master/examples/Rooms/eg001CreateRoomWithDataController.sh), [C#](https://github.com/docusign/code-examples-csharp/blob/master/launcher-csharp/Rooms/Examples/CreateRoomWithData.cs), [Java](https://github.com/docusign/code-examples-java/blob/master/src/main/java/com/docusign/controller/rooms/examples/R001ControllerCreateRoom.java), [Node](https://github.com/docusign/code-examples-node/blob/master/lib/rooms/examples/createRoomWithData.js), [PHP](https://github.com/docusign/code-examples-php/blob/master/src/Services/Examples/Rooms/CreateRoomsWithDataService.php), [PowerShell](https://github.com/docusign/code-examples-powershell/blob/master/examples/Rooms/eg001CreateRoomWithDataController.ps1), [Python](https://github.com/docusign/code-examples-python/blob/master/app/rooms/examples/eg001_create_room_with_data.py), or [Ruby](https://github.com/docusign/code-examples-ruby/blob/master/app/services/room_api/eg001_create_room_with_data_service.rb). **`Bash`** ```bash title="Bash" 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} ) ``` **`C#`** ```csharp title="C#" var response = roomsApi.CreateRoomWithHttpInfo(accountId, newRoom); response.Headers.TryGetValue("X-RateLimit-Remaining", out remaining); response.Headers.TryGetValue("X-RateLimit-Reset", out reset); if (reset != null && remaining != null) { DateTime resetDate = DateTimeOffset.FromUnixTimeSeconds(long.Parse(reset)).UtcDateTime; Console.WriteLine("API calls remaining: " + remaining); Console.WriteLine("Next Reset: " + resetDate); } return response.Data; ``` **`Java`** ```java title="Java" public final class CreateRoomService { public static Room createRoomFromModel( RoomsApi roomsApi, String accountId, RoomForCreate roomForCreate) throws ApiException { ApiResponse response = roomsApi.createRoomWithHttpInfo(accountId, roomForCreate); Map> headers = response.getHeaders(); List remaining = headers.get("X-RateLimit-Remaining"); List reset = headers.get("X-RateLimit-Reset"); if (remaining != null & reset != null) { Instant resetInstant = Instant.ofEpochSecond(Long.parseLong(reset.get(0))); System.out.println("API calls remaining: " + remaining); System.out.println("Next Reset: " + resetInstant); } return response.getData(); } ``` **`Node.js`** ```javascript title="Node.js" results = await new Promise((resolve, reject) => { roomsApi.createRoom(args.accountId, roomWithData, null, (err, data, response) => { if (err) return reject(err); resolve({ data, response }); }); }); headers = results.response.headers; remaining = headers['x-ratelimit-remaining']; reset = headers['x-ratelimit-reset']; if (remaining && reset) { const resetInstant = new Date(Number(reset) * 1000); console.log(`API calls remaining: ${remaining}`); console.log(`Next Reset: ${resetInstant.toISOString()}`); } ``` **`PHP`** ```php title="PHP" return $clientService->createRoom($args, $room); ``` **`PowerShell`** ```text title="PowerShell" $uri = "https://demo.rooms.docusign.com/restapi/v2/accounts/$APIAccountId/rooms" try { # Display the JSON response Write-Output "Response:" $response = Invoke-WebRequest -uri $uri -UseBasicParsing -headers $headers -body $body -method POST $response.Content | ConvertFrom-Json | ConvertTo-Json $($response.Content | ConvertFrom-Json).roomId > .\config\ROOM_ID } catch { Write-Output "Unable to create a new room." # On failure, display a notification, X-DocuSign-TraceToken, error message, and the command that triggered the error foreach ($header in $_.Exception.Response.Headers) { if ($header -eq "X-DocuSign-TraceToken") { Write-Output "TraceToken : " $_.Exception.Response.Headers[$int] } $int++ } Write-Output "Error : "$_.ErrorDetails.Message Write-Output "Command : "$_.InvocationInfo.Line } ``` **`Python`** ```python title="Python" rooms_api = RoomsApi(api_client) (response, status, headers) = rooms_api.create_room_with_http_info( body=room, account_id=args["account_id"] ) remaining = headers.get("X-RateLimit-Remaining") reset = headers.get("X-RateLimit-Reset") if remaining is not None and reset is not None: reset_date = dt.fromtimestamp(int(reset), tz=timezone.utc) print(f"API calls remaining: {remaining}") print(f"Next Reset: {reset_date}") ``` **`Ruby`** ```ruby title="Ruby" rooms_api = DocuSign_Rooms::RoomsApi.new(api_client) results, _status, headers = rooms_api.create_room_with_http_info(args[:account_id], body(args)) remaining = headers['X-RateLimit-Remaining'] reset = headers['X-RateLimit-Reset'] if remaining && reset reset_date = Time.at(reset.to_i).utc puts "API calls remaining: #{remaining}" puts "Next Reset: #{reset_date}" end ``` ## Expected response If you run this code example from our Quickstart or launcher projects, you should see a JSON response similar to the code shown. **`Sample response`** ```json title="Sample response" { "roomId": "3xxxx5", "companyId": "1xxx2", "name": "Sample Rooms Creation", "officeId": "3xxx2", "createdDate": "2020-08-06T20:38:38.06", "createdByUserId": "2xxxxs4", "closedStatusId": "", "fieldData": { "data": { "comments": "Lorem ipsum dolor sit amet, consectetur adi piscing 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 conseq uat. 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 de serunt mollit anim id est laborum." } } } ``` ## Next steps * Run this code example from our [Quickstart](/docs/esign-rest-api/quickstart) or launcher projects: [Bash](https://github.com/docusign/code-examples-bash), [C#](https://github.com/docusign/code-examples-csharp), [Java](https://github.com/docusign/code-examples-java), [Node.js](https://github.com/docusign/code-examples-node), [PHP](https://github.com/docusign/code-examples-php), [PowerShell](https://github.com/docusign/code-examples-powershell), [Python](https://github.com/docusign/code-examples-python), or [Ruby](https://github.com/docusign/code-examples-ruby). * See all available Rooms API [How-to guides](/docs/rooms-api/how-to). * See [How to create a room with a template](/docs/rooms-api/how-to/create-room-with-template). * See [How to add forms to a room](/docs/rooms-api/how-to/add-form-to-room). * Learn more about [Using room templates and task lists](/docs/rooms-api/rooms101/templates). * See how to [Go-Live](/docs/rooms-api/go-live) with a completed app and find the base path for API calls in the production environment.