CreateRoomLinkRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/hummingdeck/main/json-schema/hummingdeck-create-room-link-request-schema.json",
  "title": "CreateRoomLinkRequest",
  "description": "A room's second and later audience links: the same access-mode fields as primaryLink on POST /rooms, plus the recipient/company fields POST /shares and POST /rooms already accept. Supply at least one of recipientName, recipientEmail, contactId, companyId, or companyName.",
  "x-generated": "2026-10-24",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/hummingdeck-openapi.json#/components/schemas/CreateRoomLinkRequest",
  "type": "object",
  "properties": {
    "accessMode": {
      "type": "string",
      "enum": [
        "open",
        "verify-any",
        "verified-allowlist"
      ],
      "default": "open",
      "description": "open: anyone with the URL. verify-any: visitors confirm their email address with a one-time link before entering. verified-allowlist (Restricted): only allowedEmails and allowedDomains can enter, each confirming their address with a one-time link. verify-any and verified-allowlist need Pro or Business."
    },
    "requireEmail": {
      "type": "boolean",
      "description": "open links only: ask visitors for their email before they enter (Pro and Business)."
    },
    "allowedEmails": {
      "type": "array",
      "maxItems": 500,
      "items": {
        "$ref": "#/$defs/AllowedEmail"
      },
      "description": "verified-allowlist only. Each address becomes a contact. The API adds nobody on its own: include your own address if you want to preview the room. Required (with allowedDomains) on a verified-allowlist link — an empty allowlist would be a dead end no one could open."
    },
    "allowedDomains": {
      "type": "array",
      "maxItems": 100,
      "items": {
        "type": "string",
        "maxLength": 253
      },
      "description": "verified-allowlist only. Anyone with an address at one of these domains can enter. \"@acme.com\", \"acme.com\", and \"https://acme.com\" all mean acme.com. Free email providers such as gmail.com are refused."
    },
    "label": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 100,
      "description": "verified-allowlist only. Your internal name for the link."
    },
    "expiresAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When the link stops working. Must be in the future (Starter and above)."
    },
    "allowDownloads": {
      "type": "boolean",
      "description": "Whether viewers can download the room's documents. Omitted, uses the room's own download default."
    },
    "notifyOnView": {
      "type": "boolean",
      "default": true
    },
    "notifySlack": {
      "type": "boolean",
      "default": true
    },
    "recipientName": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 255
    },
    "recipientEmail": {
      "type": [
        "string",
        "null"
      ],
      "format": "email",
      "maxLength": 255,
      "description": "Finds the contact with this email or creates one."
    },
    "contactId": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Existing contact in the authenticated workspace."
    },
    "companyId": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Existing company. Mutually exclusive with companyName."
    },
    "companyName": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 255,
      "description": "Company to find by name, ignoring case, or create."
    },
    "companyDomain": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 255,
      "description": "Stored on a new company, or on a matched one that has no domain yet. Requires companyName.",
      "minLength": 1
    }
  },
  "additionalProperties": false,
  "anyOf": [
    {
      "required": [
        "recipientName"
      ],
      "properties": {
        "recipientName": {
          "type": "string"
        }
      }
    },
    {
      "required": [
        "recipientEmail"
      ],
      "properties": {
        "recipientEmail": {
          "type": "string"
        }
      }
    },
    {
      "required": [
        "contactId"
      ],
      "properties": {
        "contactId": {
          "type": "string"
        }
      }
    },
    {
      "required": [
        "companyId"
      ],
      "properties": {
        "companyId": {
          "type": "string"
        }
      }
    },
    {
      "required": [
        "companyName"
      ],
      "properties": {
        "companyName": {
          "type": "string"
        }
      }
    }
  ],
  "allOf": [
    {
      "if": {
        "required": [
          "requireEmail"
        ],
        "properties": {
          "requireEmail": {
            "const": true
          }
        }
      },
      "then": {
        "properties": {
          "accessMode": {
            "const": "open"
          }
        }
      }
    },
    {
      "if": {
        "anyOf": [
          {
            "required": [
              "allowedEmails"
            ],
            "properties": {
              "allowedEmails": {
                "minItems": 1
              }
            }
          },
          {
            "required": [
              "allowedDomains"
            ],
            "properties": {
              "allowedDomains": {
                "minItems": 1
              }
            }
          }
        ]
      },
      "then": {
        "required": [
          "accessMode"
        ],
        "properties": {
          "accessMode": {
            "const": "verified-allowlist"
          }
        }
      }
    },
    {
      "if": {
        "required": [
          "label"
        ],
        "properties": {
          "label": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "then": {
        "required": [
          "accessMode"
        ],
        "properties": {
          "accessMode": {
            "const": "verified-allowlist"
          }
        }
      }
    },
    {
      "if": {
        "required": [
          "accessMode"
        ],
        "properties": {
          "accessMode": {
            "const": "verified-allowlist"
          }
        }
      },
      "then": {
        "anyOf": [
          {
            "required": [
              "allowedEmails"
            ],
            "properties": {
              "allowedEmails": {
                "minItems": 1
              }
            }
          },
          {
            "required": [
              "allowedDomains"
            ],
            "properties": {
              "allowedDomains": {
                "minItems": 1
              }
            }
          }
        ]
      }
    },
    {
      "not": {
        "required": [
          "companyId",
          "companyName"
        ],
        "properties": {
          "companyId": {
            "type": "string"
          },
          "companyName": {
            "type": "string"
          }
        }
      }
    },
    {
      "if": {
        "required": [
          "companyDomain"
        ],
        "properties": {
          "companyDomain": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "then": {
        "required": [
          "companyName"
        ],
        "properties": {
          "companyName": {
            "type": "string",
            "minLength": 1
          }
        }
      }
    }
  ],
  "$defs": {
    "AllowedEmail": {
      "description": "An address, or an address with the person's name.",
      "oneOf": [
        {
          "type": "string",
          "format": "email",
          "maxLength": 255
        },
        {
          "type": "object",
          "properties": {
            "email": {
              "type": "string",
              "format": "email",
              "maxLength": 255
            },
            "name": {
              "type": [
                "string",
                "null"
              ],
              "maxLength": 255
            }
          },
          "required": [
            "email"
          ],
          "additionalProperties": false
        }
      ]
    }
  }
}