ROOM

ROOM API Documentation

Build powerful form solutions by integrating directly with the ROOM platform

Getting Started

Learn the basics of the ROOM API

API Reference

Explore available endpoints

Resources

Additional developer resources

Introduction

The ROOM API is organized around REST principles. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the ROOM API to create forms, collect responses, manage teams, and more. Whether you're building a custom integration or extending ROOM's functionality, our API provides the tools you need.

Base URL

https://roomforms.com/api/v1

All API requests should be made to this base URL, followed by the specific endpoint.

Content Type

All requests should use:

Content-Type: application/json

Responses will be returned in JSON format.

Authentication

The ROOM API uses API keys for authentication. You can generate an API key from your dashboard settings.

Your API keys carry many privileges, so be sure to keep them secure. Do not share your API keys in publicly accessible areas such as GitHub, client-side code, or in your frontend application.

Authentication Header

Authorization: Bearer YOUR_API_KEY

Important: Keep your API keys secure and never expose them in client-side code.

Example Request with Authentication

fetch('https://roomforms.com/api/v1/forms/submit', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    formId: 'form_id_here',
    data: {
      field_id_1: 'value_1',
      field_id_2: 'value_2'
    }
  })
})
.then(response => response.json())
.then(data => console.log(data));

API Reference

POST

/forms/submit

Note:

To obtain the formId, create a new form and publish it. The formId can be retrieved after the form is successfully published—typically from the response payload or the URL.

Error Handling

The ROOM API uses conventional HTTP response codes to indicate the success or failure of an API request.

CodeDescription
200 - OKEverything worked as expected.
400 - Bad RequestThe request was unacceptable, often due to missing a required parameter.
401 - UnauthorizedNo valid API key provided.
403 - ForbiddenThe API key doesn't have permissions to perform the request.
404 - Not FoundThe requested resource doesn't exist.
429 - Too Many RequestsToo many requests hit the API too quickly.
500, 502, 503, 504 - Server ErrorsSomething went wrong on ROOM's end.

Error Response Format

When an error occurs, the API will return a JSON object with the following structure:

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has expired.",
    "param": null,
    "doc_url": "https://docs.room.com/api/errors#invalid-api-key"
  }
}

Rate Limits

To ensure the stability and availability of the ROOM API for all users, we implement rate limiting. Rate limits vary based on your subscription plan.

PlanRequests per minuteDaily limit
Free101,000
Pro6050,000

Rate Limit Headers

All API responses include headers that indicate your current rate limit status:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 56
X-RateLimit-Reset: 1635788400
  • X-RateLimit-Limit: The maximum number of requests you're permitted to make per minute.
  • X-RateLimit-Remaining: The number of requests remaining in the current rate limit window.
  • X-RateLimit-Reset: The time at which the current rate limit window resets in UTC epoch seconds.

Webhooks

Webhooks allow you to receive real-time notifications when certain events happen in your ROOM account.

Available Events

  • form.created
    Triggered when a new form is created
  • form.updated
    Triggered when a form is updated
  • form.deleted
    Triggered when a form is deleted
  • response.created
    Triggered when a new response is submitted
  • team.member_added
    Triggered when a member is added to a team

Webhook Payload Example

{
  "id": "evt_123456",
  "type": "response.created",
  "created": "2023-10-05T16:45:12Z",
  "data": {
    "id": "resp_125",
    "formId": "form_123abc",
    "createdAt": "2023-10-05T16:45:12Z",
    "data": {
      "field_1": "Sarah Johnson",
      "field_2": "sarah@example.com",
      "field_3": "The product exceeded my expectations!"
    }
  }
}

Setting Up Webhooks

You can set up webhooks in your ROOM dashboard under Settings > API & Webhooks. For each webhook, you'll need to provide:

  • A URL to receive the webhook payload
  • The events you want to subscribe to
  • An optional description to help you identify the webhook

For security, we recommend verifying webhook signatures using the secret provided when you create the webhook.

Need Help?

If you have any questions about the API or need assistance with your integration, our developer support team is here to help.