Lucid Meetings REST API

Please see the full REST API documentation for API implementation details.

Resource: REST Hooks

REST hooks provide a way for API callers to dynamically configure callback requests for events they would like to be notified about. Examples include receiving a notification when a meeting is scheduled or when an Action Item is created.

The Lucid Meetings REST Hook mechanism follows the patterns described by Zapier for their Notification REST Hooks and by resthooks.org for "Skinny Payloads." With skinny payloads we deliver (POST) a notification that an event has occurred, along with a URL for the affected resource. To access the full resource, the recipient must retrieve (GET) the resource via normal, authenticated API calls.

Properties
My Hooks
Getting a Single Hook
Creating a Hook
Deleting a Hook
Sending a Hook

Properties

Field	Type	Notes
hook_id	integer
token_id	integer	Identifies the API token used to create the hook
organization_id	tuple	associated organization: {organization_id, name}
room_id	tuple	associated room: {room_id, name}
event	tuple	trigger event: {event, description}
target_url	URL	The target URL for the notification callback
create_ts	timestamp
update_ts	timestamp

My Hooks

GET /lucid/api/v1/hooks (must be logged in)

Query parameter	Notes
organization_id	(Integer) Restrict to hooks with the specified organization_id.
room_id	(Integer) Restrict to hooks with the specified room_id.
target_url	(String) Restrict to hooks with the specified target_url.
fields	See Field Filtering
envelope	See Enveloping

Sample Request

GET /lucid/api/v1/hooks?fields=hook_id,room_id,event

Content-Type: application/json; charset=utf-8
Content-Length: 653
X-Rate-Limit-Limit: 100
X-Rate-Limit-Remaining: 98
X-Rate-Limit-Reset: 60
X-Rate-Limit-Used: 2
X-Requestor: jtkeith@lucidmeetings.com

[
  {
    "hook_id": 10,
    "room_id": {
      "value": 74,
      "display": "Engineering Team"
    },
    "event": {
      "value": "meeting_scheduled",
      "display": "Meeting scheduled in a room"
    }
  },
  {
    "hook_id": 12,
    "room_id": {
      "value": 74,
      "display": "Engineering Team"
    },
    "event": {
      "value": "meeting_ended",
      "display": "Meeting session ended in a room"
    }
  }
]

Getting a Single Hook

GET /lucid/api/v1/hooks/:hook_id

Query parameter	Notes
fields	See Field Filtering
envelope	See Enveloping

Sample Request

GET /lucid/api/v1/hooks/10

Content-Type: application/json; charset=utf-8
Content-Length: 813
X-Requestor: jtkeith@lucidmeetings.com
X-Rate-Limit-Limit: 100
X-Rate-Limit-Remaining: 99
X-Rate-Limit-Used: 1
X-Rate-Limit-Reset: 60

{
  "id": 10,
  "hook_id": 10,
  "organization_id": null,
  "room_id": {
    "value": 74,
    "display": "Engineering Team"
  },
  "target_url": "https:\/\/zapier.com\/hooks\/standard\/286082\/e139ef7fb5174f42953716e966621fc0\/",
  "event": {
    "value": "meeting_scheduled",
    "display": "Meeting scheduled in a room"
  },
  "create_ts": {
    "value": 1463464721,
    "iso_8601": "2016-05-17T05:58:41Z"
  },
  "update_ts": {
    "value": 1463464721,
    "iso_8601": "2016-05-17T05:58:41Z"
  }
}

Creating a Hook

Note: Hook creation automatically guards against creation of duplicate hooks. If you attempt to create a hook which matches on all four fields with one that already exists (and that belongs to you), the API will return the data for the existing hook, with a 200 (instead of 201) HTTP status.

POST /lucid/api/v1/hooks

Field	Required	Notes
organization_id	no	The organization associated with the event, if any
room_id	no	The room associated with the event, if any
event	yes	The event to monitor
target_url	yes	The URL to callback when the event occurs

Sample Request

POST /lucid/api/v1/hooks
Content-Type: application/json

{
  "event" : "meeting_scheduled",
  "target_url" : "http:\/\/example.com\/api\/events",
  "room_id" : 74
}

201 Created
Location: https://site.lucidmeetings.com/lucid/api/v1/hooks/18
Content-Type: application/json

{
  "id": 18,
  "hook_id": 18,
  "organization_id": null,
  "room_id": {
    "value": 74,
    "display": "Engineering Team"
  },
  "target_url": "http:\/\/example.com\/api\/events",
  "event": {
    "value": "meeting_scheduled",
    "display": "Meeting scheduled in a room"
  },
  "create_ts": {
    "value": 1463540109,
    "iso_8601": "2016-05-18T02:55:09Z"
  },
  "update_ts": {
    "value": 1463540109,
    "iso_8601": "2016-05-18T02:55:09Z"
  }
}

Deleting a Hook

DELETE /lucid/api/v1/hooks/:hook_id

Sample Request

DELETE /lucid/api/v1/hooks/10

204 No Content

Sending a Hook

When the Lucid Meetings service matches an event to a hook subscription, we POST event data to the target_url supplied when the hook was created.

POST data	Notes
resource_url	The URL for the resource associated with the event
event	Hook data: event field
meeting_id	The ID of the meeting associated with the event, if applicable (otherwise null)
meeting_series_id	The ID of the meeting series associated with the event, if applicable (otherwise null)
organization_id	Hook data: organization_id field
room_id	Hook data: room_id field
hook_id	Hook data: the resource identifier for this hook
Additional fields are included for some events:
from_room_id	Event: `meeting_room_changed`. The room_id of the room the meeting was moved from.
to_room_id	Event: `meeting_room_changed`. The room_id of the room the meeting was moved to.

If the target_url responds with a 410 Gone status code we immediately remove the subscription to the failing hook (unsubscribe). Additionally, excessive failures (multiple 4xx or 5xx failures) are logged and eventually unsubscribed as well.

POST target_url
Content-Type: application/json

{
  "resource_url" : "resource_url",
  "event" : "event",
  "organization_id" : organization_id,
  "room_id" : room_id,
  "hook_id" : hook_id
}

Sample Request

POST https://zapier.com/hooks/standard/286082/e139ef7fb5174f42953716e966621fc0/
Content-Type: application/json

{
  "resource_url" : "https://site.lucidmeetings.com/meetings/1489",
  "event" : "meeting_scheduled",
  "organization_id" : null,
  "room_id" : 74,
  "hook_id" : 18
}