Joan API Documentation

api/v1.0

No fields.

Returns a list of users for the same company.

Fields:

  • id: IntegerField
  • first_name: CharField R
  • last_name: CharField R
  • email: EmailField
  • admin: SerializerMethodField
  • permissions: SerializerMethodField
  • company: SerializerMethodField
  • departments: ManyRelatedField
  • notifications: ListSerializer Array of objects
    • type: ChoiceField R
    • channels: ListField R

api/v1.0

Fields:

  • name: CharField
  • email: CharField R
  • locations: SerializerMethodField
  • status: ChoiceField
  • amenities: ManyRelatedField
  • capacity: IntegerField
  • sync: BooleanField
  • first_failed_sync: DateTimeField

Return a list of active/assigned room resources with events

Fields:

  • room: LegacyApiRoomResourceSerializerCompat
    • name: CharField
    • email: CharField R
    • locations: SerializerMethodField
    • status: ChoiceField
    • amenities: ManyRelatedField
    • capacity: IntegerField
    • sync: BooleanField
    • first_failed_sync: DateTimeField
  • events: SerializerMethodField

Get room resources.

Fields:

  • name: CharField
  • email: CharField R
  • locations: SerializerMethodField
  • status: ChoiceField
  • amenities: ManyRelatedField
  • capacity: IntegerField
  • sync: BooleanField
  • first_failed_sync: DateTimeField

Return a list of owned devices.

Fields:

  • uuid: CharField R
  • wifi: IntegerField
  • battery: IntegerField
  • model: ChoiceField
  • size: ChoiceField
  • roomResources: ListSerializer Array of objects
    • name: CharField
    • email: CharField R
    • locations: SerializerMethodField
    • status: ChoiceField
    • amenities: ManyRelatedField
    • capacity: IntegerField
    • sync: BooleanField
    • first_failed_sync: DateTimeField
  • interface: ChoiceField
  • wifi_quality: IntegerField

Return a list of owned devices.

Fields:

  • uuid: CharField R
  • wifi: IntegerField
  • battery: IntegerField
  • model: ChoiceField
  • size: ChoiceField
  • roomResources: ListSerializer Array of objects
    • name: CharField
    • email: CharField R
    • locations: SerializerMethodField
    • status: ChoiceField
    • amenities: ManyRelatedField
    • capacity: IntegerField
    • sync: BooleanField
    • first_failed_sync: DateTimeField
  • interface: ChoiceField
  • wifi_quality: IntegerField

API view for event termination - finish or cancel Finishing an event shortens it while canceling actually deletes it.

Fields:

  • finish: BooleanField
  • event_id: CharField R
  • timezone: TimeZoneSerializerField R
  • room_id: RoomResourceSlugField R

API View for checking into a meeting

Fields:

  • event_id: CharField R
  • room_id: RoomResourceSlugField R
  • lifetime: IntegerField R

Extending a meeting

Fields:

  • event_id: CharField R
  • room_id: RoomResourceSlugField R
  • extend_until: DateTimeField R

Move event to another room viewset

Fields:

  • event_id: CharField R
  • old_calendar_id: RoomResourceSlugField R
  • new_calendar_id: RoomResourceSlugField R
  • new_calendar_name: CharField R

Book an event in the calendar by providing calendar email or device UUID.

Fields:

  • source: CharField R
  • start: DateTimeField R
  • end: DateTimeField R
  • timezone: CharField
  • organizer: EmailField
  • title: CharField
  • auto_confirm: BooleanField

Find me a free room for the given timeslot.

Fields:

  • eventStart: DateTimeField
  • duration: IntegerField
  • timezone: CharField
  • from_: SerializerMethodField
  • rooms: SerializerMethodField
  • to: SerializerMethodField

API View for inviting user to a meeting

Fields:

  • event_id: CharField R
  • event_name: CharField R
  • room_id: CharField R
  • room_name: CharField R
  • email: EmailField R

API View for confirming user invitation to meeting

No fields.

API View for rejecting users invitation to meeting

No fields.

Getting started

Api GIF

To use the Joan API, you’ll first need a private API client ID and private API secret that is linked to your account.

The mentioned credentials can be obtained by creating a new application on the Joan Portal. When created, you will receive a private API client ID and private API secret. With those you can request an access token, with which you can then call the API endpoint. This is a typical OAuth 2.0 client credential flow.

Access token request example 

curl -u client_id:secret https://portal.getjoan.com/api/token/ -d 'grant_type=client_credentials'

Access token response example

{
   "access_token":access_token,
   "token_type":"Bearer",
   "expires_in":36000,
   "scope":"read write"
}
from oauthlib.oauth2 import BackendApplicationClient
from requests_oauthlib import OAuth2Session

def getToken(client_id, client_secret):
  """
  Access token function which retrieves access token upon providing your Client ID and Client Secret.
  """
  client = BackendApplicationClient(client_id=client_id)
  oauth = OAuth2Session(client=client)
  token = oauth.fetch_token(
    token_url="https://portal.getjoan.com/api/token/",
    client_id=client_id,
    client_secret=client_secret
    )
  return token["access_token"]

Access token response example 

{
  u'access_token':u'access_token',
  u'token_type':u'Bearer',
  u'expires_in':36000,
  u'expires_at':14921.283,
  u'scope':[
    u'read',
    u'write'
  ]
}

API examples

Example request 

curl -H "Authorization: Bearer access_token" -X GET https://portal.getjoan.com/api/v1.0/rooms/

Example response 

{
 "count": 3,
 "next": null,
 "previous": null,
 "results": [
  {
   "id": 11793,
   "name": "Glass Meeting Room",
   "email": "https://calendar.google.com/calendar/ical/visionect-calendar.ics",
   "manualEntry": true
  },
  {
   "id": 21028,
   "name": "Fuzboll Room",
   "email": "[email protected]",
   "manualEntry": false
  },
  {
   "id": 20001,
   "name": "White Board Room",
   "email": "[email protected]",
   "manualEntry": false
  }
 ]
}
import requests

def get_rooms(accessToken):
  response = requests.get(get_rooms_url, headers={'Authorization': 'Bearer '+ accessToken})

  # Checking if access token has expired and calling the same function again after retrieving a new one
  if response.status_code == 401:
      get_rooms(getToken())

  # If API call was successful, printing "success" message and response's text.
  elif response.status_code == 200:
      print "success"
      print response.text

Example response 

{
 "count": 3,
 "next": null,
 "previous": null,
 "results": [
  {
   "id": 11793,
   "name": "Glass Meeting Room",
   "email": "https://calendar.google.com/calendar/ical/visionect-calendar.ics",
   "manualEntry": true
  },
  {
   "id": 21028,
   "name": "Fuzboll Room",
   "email": "[email protected]",
   "manualEntry": false
  },
  {
   "id": 20001,
   "name": "White Board Room",
   "email": "[email protected]",
   "manualEntry": false
  }
 ]
}