Skip to main content

Quick Start

About Roam HQ​

Roam HQ is an all-in-one virtual office designed to bring a whole distributed company together in one headquarters.

Roam HQ makes companies:

  • more productive with shorter meetings
  • more connected with a map that gives a feeling of working together without meeting
  • & Roam saves companies money with our all-in-one bundle

NOTE: To create API clients, you must be an admin of the Roam. You can either generate an API key or OAuth client ID/secret.

Creating an Application​

In the Roam settings, visit the “Developer” tab. On this page, you can view all the apps created.

To access the API, you need to create an Application.

  1. Navigate to Roam Administration > Developer (by clicking the gear icon labeled Settings at the bottom right of the map. The list of API clients is displayed.
  2. Click Add ApiClient. A form appears.
  3. Enter a name & description, and select the Authorization type. For now, choose API key, but typically you would select OAuth, if the app acts on behalf of a user, or API Key if the app is not connected to a specific user.
  4. Click Add to save the app. A section showing the Client ID, Client Secret, and other settings appears.
  5. Select the Access Scopes based on the needs of the application. For now, choose groups:read.
  6. Save your changes.

To test your API key, you can list groups from the command line. Find your Roam ID from Roam Administration > Roam and run the following command:

$ curl -H "Authorization: Bearer $API_KEY" https://api.ro.am/v1/groups.list

That’s it! You have used the Roam API. Being a REST API, you can use your preferred programming language to build any automation you desire.

However, you may not need to write any code to accomplish your goal. Roam offers a few pre-built integrations for common scenarios.