Getting Started

1. API Access

To access the Beework API you need an App API key and an App Secret. Contact us to request access.

Your request needs to include a Redirect URI which users will be redirected to after a successful authorization.

2. Authorization

Before you can fetch data from the API, you will need to acquire an OAuth 2 access token. Read more: Authorization Flow.

3. REST API

Our REST API is used to fetch data for the authenticated user, and to set up webhooks. Read more: Requests.

4. Webhook Subscriptions

Webhooks are used to get events when a resource changes. Read more: Subscriptions.

Authorization Details

The Beework API uses parts of the OAuth 2 standard to facilitate authorization. Access to the API is granted on behalf of a Beework user.

Authorize Endpoint

Example URL

https://beework.app/oauth2/authorize
  ?client_id=my_client_id123
  &redirect_uri=https://example.com/auth_success
  &response_type=code
  &scope=feeds colleagues
  &state=my_state123

The authorize endpoint is the URL the user visits to initiate the OAuth 2 authorization flow. The page will show a sign in form is needed, the option to choose which of the requested scopes to be granted, and the option to cancel, or accept the application authorization.

GET https://beework.app/oauth2/authorize

Request Parameters (Query String)

Key	Type	Description
client_id	string	Your App API Key (`client_id`)
redirect_uri	string	Your redirect uri (`redirect_uri`)
response_type	string	Always `"code"`
scope	string	Space separated list of scopes
state	string	(optional) An opaque value echoed back in the response.

Token Endpoint

Request Parameters (Query String)

Example Request

//subtype:+fetch
fetch('https://api.beework.app/v1/oauth2/token?grant_type=authorization_code&code=my_authorzation_token&client_id=my_client_id&client_secret=my_client_secret&redirect_uri=my_redirect_uri', { method: 'GET', headers: { Authorization: 'Bearer my_access_token' } })
  .then(res => res.json())
  .then(json => {
    console.log(json)
  })

//subtype:+axios
axios({
  url: 'https://api.beework.app/v1/oauth2/token?grant_type=authorization_code&code=my_authorzation_token&client_id=my_client_id&client_secret=my_client_secret&redirect_uri=my_redirect_uri',
  method: 'GET',
  headers: { Authorization: 'Bearer my_access_token' }
}).then((res) => {
  console.log(res.data)
});

curl "https://api.beework.app/v1/oauth2/token?grant_type=authorization_code&code=my_authorzation_token&client_id=my_client_id&client_secret=my_client_secret&redirect_uri=my_redirect_uri" \
  -H "Authorization: Bearer my_access_token"

from urllib import request, parse
import json

req = request.Request(
  'https://api.beework.app/v1/oauth2/token',
  data=data
)
res = json.load(request.urlopen(req))
print(res)

Example Response

{
  "access_token": "my_access_token123",
  "refresh_token": "my_refresh_token123",
  "scope": ["feeds", "colleagues"],
  "token_type": "bearer",
  "expires_in": 84600,
  "state": "my_state123"
}

The token endpoint is used to get an access_token and refresh_token. Either by using an authorization code (code) from the Authorize Endpoint, or a refresh_token from a previous request to this endpoint.

GET https://api.beework.app/v1/token

Request Parameters (Query String)

Parameter	Type	Description
grant_type	string	`"authorization_code"` or `"refresh_token"`
code	string	Required if `grant_type` is `"authorization_code"` The authorization code (`code`)
refresh_token	string	Required if `grant_type` is `"refresh_token"` The refresh token (`refresh_token`)
client_id	string	Your App API key (`client_id`)
client_secret	string	Your App secret (`client_secret`)
redirect_uri	string	Your redirect uri (`redirect_uri`)

Response Data (JSON Encoded)

Parameter	Type	Description
access_token	string	The authorization token, used to authorize requests.
refresh_token	string	The refresh token, used to acquire a new access_token after expiration.
scope	string[]	The scopes accepted by the user.
token_type	string	Always `"bearer"`
expires_in	number	Seconds left until the token expires.

Redirect URI

The redirect_uri is a unique URL in your application which the user is redirected to after a successful authorization. It will receive an authorization code (code) as a query parameter, which your server will use to get an access_token that will be used to authenticate future requests.

Each application has a single redirect_uri. Your desired redirect_uri must be included when contacting us for API Access since it's part of your application details.

Scopes

Scopes specify which permissions the user grants your application. You may specify which scopes you want to request, but the user may choose which scopes to grant your application during authorization.

User scope

The user scope grants access to basic user information (name, email, etc)

Feeds scope

The feeds scope grants access to feeds and feed posts.

Event Lists scope

The event_lists scope grants access to event lists and events.

Workplaces scope

The workplaces scope grants access to basic information about workplaces.

Colleagues scope

The colleagues scope grants access to the user data in your organization. The data includes but is not limited to: Name, Avatar, Birthday Date, Status, Title and E-mail.

Application Credentials

After API access for your app has been granted you will receive an App API key (client_id) and an App Secret (client_secret) which will be used to identify your application when calling our API.

The client_secret is secret! Treat it like a password.

Authorization Guide

Flow Summary

Sign in
- Your application displays a "Connect Beework" button.
- The user clicks the button and is sent to the authorize page.
- The user signs in and accepts the authorization.
Redirect
- Our server redirects the user to your redirect URI with an authorization code (?code=xxx).
Get access token
- Get access token Your server sends the authorization code to our token endpoint.
- Our server responds with an access_token and a refresh_token.
- Your server uses the access_token to authorize requests to our API.
Token Refresh
- The access_token expires, causing an API call to fail.
- Your server uses the refresh_token to get a new access_token.

The access_token and refresh_token are secret! Treat them like passwords.

Example URL

https://beework.app/oauth2/authorize
  ?client_id=my_client_id123
  &redirect_uri=my_redirect_uri
  &response_type=code
  &scope=feeds colleagues

Send the user to the authorization page, Beework will allow the user to sign in and choose whether to authorize your application.

2. Redirect

Example URL

https://example.com/auth_success
  ?code=8ObN6So26NKul4RVjvpi2cU5l9vQ76
  &scope=feeds colleagues

Once the user has authorized your application, they are redirected to your redirect_uri with an authorization code (code) and the accepted scopes.

3. Get Access Token

Example Request

//subtype:+fetch
fetch('https://api.beework.app/v1/oauth2/token?grant_type=authorization_code&code=my_authorzation_token&client_id=my_client_id&client_secret=my_client_secret&redirect_uri=my_redirect_uri', { method: 'GET', headers: { Authorization: 'Bearer my_access_token' } })
  .then(res => res.json())
  .then(json => {
    console.log(json)
  })

//subtype:+axios
axios({
  url: 'https://api.beework.app/v1/oauth2/token?grant_type=authorization_code&code=my_authorzation_token&client_id=my_client_id&client_secret=my_client_secret&redirect_uri=my_redirect_uri',
  method: 'GET',
  headers: { Authorization: 'Bearer my_access_token' }
}).then((res) => {
  console.log(res.data)
});

curl "https://api.beework.app/v1/oauth2/token?grant_type=authorization_code&code=my_authorzation_token&client_id=my_client_id&client_secret=my_client_secret&redirect_uri=my_redirect_uri" \
  -H "Authorization: Bearer my_access_token"

from urllib import request, parse
import json

req = request.Request(
  'https://api.beework.app/v1/oauth2/token',
  data=data
)
res = json.load(request.urlopen(req))
print(res)

Example Response

{
  "access_token": "my_access_token123",
  "refresh_token": "my_refresh_token123",
  "scope": ["feeds", "colleagues"],
  "token_type": "bearer",
  "expires_in": 84600
}

From your server, send the authorization code (code) to the token endpoint to get an access_token and a refresh_token.

4. Token Refresh

Example Request

//subtype:+fetch
fetch('https://api.beework.app/v1/oauth2/token', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer my_access_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    grant_type: 'refresh_token',
    refresh_token: 'my_refresh_token',
    client_id: 'my_client_id',
    client_secret: 'my_client_secret'
  })
})
  .then(res => res.json())
  .then(json => {
    console.log(json)
  })

//subtype:+axios
axios({
  url: 'https://api.beework.app/v1/oauth2/token',
  method: 'POST',
  data: {
    grant_type: 'refresh_token',
    refresh_token: 'my_refresh_token',
    client_id: 'my_client_id',
    client_secret: 'my_client_secret'
  },
  headers: { Authorization: 'Bearer my_access_token' }
}).then((res) => {
  console.log(res.data)
});

curl "https://api.beework.app/v1/oauth2/token" \
  -H "Authorization: Bearer my_access_token" \
  -X POST \
  -F "grant_type"="refresh_token" \
  -F "refresh_token"="my_refresh_token" \
  -F "client_id"="my_client_id" \
  -F "client_secret"="my_client_secret"

from urllib import request, parse
import json

data = parse.urlencode(
  {
    "grant_type": "refresh_token",
    "refresh_token": "my_refresh_token",
    "client_id": "my_client_id",
    "client_secret": "my_client_secret"
  }
).encode()
req = request.Request(
  'https://api.beework.app/v1/oauth2/token',
  data=data, method="POST"
)
res = json.load(request.urlopen(req))
print(res)

Example Response

{
  "access_token": "my_access_token123",
  "refresh_token": "my_refresh_token123",
  "scope": ["feeds", "colleagues"],
  "token_type": "bearer",
  "expires_in": 84600
}

The access token will eventually expire, and you will need to refresh it by passing the refresh_token to the token endpoint.

Request Parameters (Query String)

Parameter	Type	Description
grant_type	string	Always `"refresh_token"`
refresh_token	string	The `refresh_token`
client_id	string	Your App API key (`client_id`)
client_secret	string	Your App secret (`client_secret`)

Response Data (JSON encoded)

Parameter	type	Description
access_token	string	The authorization token, used to authorize requests.
refresh_token	string	The refresh token, used to acquire a new access_token after expiration.
scope	string[]	The scopes accepted by the user.
token_type	string	Always `"bearer"`
expires_in	number	Seconds left until the token expires.

Requests

This section covers the REST routes and does not apply to the OAuth API.

Authorization Header

Example Request (abbr)

GET /v1/feeds HTTP/1.1
Host: api.beework.app
Authorization: Bearer my_access_token123

All requests requires an access_token passed via the Authorization header:

Authorization: Bearer {access_token}

The required OAuth scopes are listed under the documentation for each endpoint, and needs to be specified when authorizing your app.

Request Format

Example body parameter request (abbr)

PUT /v1/foo/bar HTTP/1.1
Host: api.beework.app
Content-Type: application/json
Authorization: Bearer my_OAuth_access_token123
{
  "parameter": "value"
}

Some routes accept parameters, they are sent in the request body as a JSON Object (Content-Type: application/json) or as form encoded data (Content-Type: multipart/form-data).

Response Format

Example Response (abbr)

HTTP/1.1 200 Success
Content-Type: application/json

{
  "meta": {
    "resume_key": 458934864352
  },
  "data": {
    "f1VMhYZV8O": {
      "like_count": 8,
      "comment_count": 8,
      "author_name": "John Doe",
      "author_id": "my_user_id123",
      "created_date": 160123454,
      "body": "Hello!\n\nExample feed post body."
    }
  }
}

Successful requests which do not have any data to return will send status code 204 No Content, and an empty response body.

Successful requests with a data reponse will send status code 200 OK, and a JSON encoded (Content-Type: application/json) body in the following format:

Key	Description	Optional
data	Response data	no
meta	Response metadata	yes

When fetching multiple resources, data will generally be an Object where the keys represent resource IDs, and the values are the resources.

Unsuccessful requests will send an error response.

Errors

Error response example

{
  "code": "invalid_access_token",
  "message": "Invalid access token."
}

Error responses use an HTTP status code to indicate the type of error, and a JSON object in the response body to specify the error code and message.

HTTP Status Code	Error Code	Description
400	syntax_error	The request body contains a formatting error.
400	validation_error	The request body has missing, unknown or invalid parameters.
401	invalid_credentials	The OAuth2 token is invalid.
403	missing_scope	The OAuth2 token does not have the required scope.
404	not_found	The requested resource was not found.
405	invalid_method	The HTTP method is not available for the requested resource.
429	rate_limited	You have reached the rate limit.
500	server_error	Something went wrong. We don't know what or why, but it's our fault.

Rate Limiting

GET requests are heavily throttled to discourage polling, use webhooks to get up to date data.

Subscriptions

If you need up to date data, you can subscribe to webhook events to get events immediately when a resource changes.

Webhook events will be emitted when a resource is created, updated, or deleted, and will only contain the data which was changed. By fetching the initial data using a GET request, and subscribing to change events you will have an up to date version of the data.

Data Consistency

Webhooks will usually fire once and in order, but may occasionally be delivered twice or out of order. Events may also be lost due to outages or bad luck.

Every GET request will include an initial resume key, and every change event will include a next resume key and a previous resume key. Resume keys are valid if:

The previous resume key matches the last resume key you received in the previous call/event
The next resume key is greater than the resume key you received in the previous call/event.

If you detect an invalid resume key, send a new GET request to replace your current state, and keep listening for change events.

Irrelevant requests

Unlike GET requests, it's not possible to limit the scope of a subscription to only the latest N resources. Hence, you may sometimes get events about resources which your application doesn't care about.

If an event is irrelevant, you can safely ignore the data and just save the resume_key if needed for future data consistency.

User

Get user info

Example Request

//subtype:+fetch
fetch('https://api.beework.app/v1/me', { method: 'GET', headers: { Authorization: 'Bearer my_access_token' } })
  .then(res => res.json())
  .then(json => {
    console.log(json)
  })

//subtype:+axios
axios({
  url: 'https://api.beework.app/v1/me',
  method: 'GET',
  headers: { Authorization: 'Bearer my_access_token' }
}).then((res) => {
  console.log(res.data)
});

curl "https://api.beework.app/v1/me" \
  -H "Authorization: Bearer my_access_token"

from urllib import request, parse
import json

req = request.Request(
  'https://api.beework.app/v1/me',
  data=data
)
res = json.load(request.urlopen(req))
print(res)

Example Response

{
  "data": {
    "user": {
      "avatar_url": "https://example.com/my_avatar123.jpg",
      "email": "john@example.com",
      "status": "available",
      "birthday": "12-31",
      "full_name": "John Doe",
      "given_name": "John",
      "family_name": "Doe",
      "workplace_id": "my_workplace_id123",
      "title": "Assistant to the regional manager",
      "status_text": "I'm vabbing today"
    },
    "organization": {
      "name": "ACME",
    }
  },
  "meta": {
    "organization_id": "my_organization_id123",
    "user_id": "my_user_id123"
  }
}

Returns details about the authenticated user.


Required Scope:	user
Rate Limit:	10 requests per user, 24 hours (rolling)

Request

GET /v1/me

Response Data

Field	Type	Description
user.avatar_url	string \| null	User avatar URL
user.birthday	string \| null	Birthday in MM-dd format
user.email	string	E-mail address
user.family_name	string \| null	Last name
user.full_name	string \| null	Full name or e-mail
user.given_name	string \| null	First name
user.status	Status	The user's current status
user.status_text	string \| null	Status text
user.title	string \| null	Profession
workplace_id	string \| null	ID of user workplace
organization.name	string	Organization name

Response Metadata

Key	Type	Description
organization_id	string	Organization ID
user_id	string	User ID

Feeds

List Feeds

Example Request

//subtype:+fetch
fetch('https://api.beework.app/v1/feeds', { method: 'GET', headers: { Authorization: 'Bearer my_access_token' } })
  .then(res => res.json())
  .then(json => {
    console.log(json)
  })

//subtype:+axios
axios({
  url: 'https://api.beework.app/v1/feeds',
  method: 'GET',
  headers: { Authorization: 'Bearer my_access_token' }
}).then((res) => {
  console.log(res.data)
});

curl "https://api.beework.app/v1/feeds" \
  -H "Authorization: Bearer my_access_token"

from urllib import request, parse
import json

req = request.Request(
  'https://api.beework.app/v1/feeds',
  data=data
)
res = json.load(request.urlopen(req))
print(res)

Example Response

{
  "data": {
    "hbumhFhHw3": {
      "name": "News",
      "description": "Reminders to change your password",
      "avatar_url": "https://example.com/GzEZBJ1FyY.png",
      "admin": true,
      "subscribed": true
    }
  }
}

Returns all feeds which the authenticated user has access to read (public feeds and subscribed feeds).


Required Scope:	feeds
Rate Limit:	200 requests per user, 24 hours (rolling)

Request

GET /v1/feeds

Response Data

An Object with feed ID as keys, and feed information as values:

Field	Type	Example	Description
name	string	`"News"`	The name of the feed
description	string	`"Company news and current events"`	Feed description
avatar_url	string \| null	`"https://example.com/foo.png"`	URL to feed image
subscribed	boolean	`true`	User is subscribed to the feed
admin	boolean	`true`	User has admin permissions for the feed

Get Feed

Example Request

//subtype:+fetch
fetch('https://api.beework.app/v1/feeds/my_feed_id', { method: 'GET', headers: { Authorization: 'Bearer my_access_token' } })
  .then(res => res.json())
  .then(json => {
    console.log(json)
  })

//subtype:+axios
axios({
  url: 'https://api.beework.app/v1/feeds/my_feed_id',
  method: 'GET',
  headers: { Authorization: 'Bearer my_access_token' }
}).then((res) => {
  console.log(res.data)
});

curl "https://api.beework.app/v1/feeds/my_feed_id" \
  -H "Authorization: Bearer my_access_token"

from urllib import request, parse
import json

req = request.Request(
  'https://api.beework.app/v1/feeds/my_feed_id',
  data=data
)
res = json.load(request.urlopen(req))
print(res)

Example Response

{
  "data": {
    "name": "IT",
    "description": "Reminders to change your password",
    "avatar_url": "https://example.com/TM5roaR49.png",
    "admin": true,
    "subscribed": true
  }
}

Returns details for a given feed ID.


Required Scope:	feeds
Rate Limit:	200 requests per user, 24 hours (rolling)

Request

GET /v1/feeds/:feed_id

Response Data

Field	Type	Example	Description
name	string	`"News"`	Feed name
description	string	`"Company news and current events"`	Feed description
avatar_url	string \| null	`"https://example.com/foo.png"`	Feed image URL
subscribed	boolean	`true`	User is subscribed to feed
admin	boolean	`true`	User has admin permissions admin for feed

List Posts

Example Request

//subtype:+fetch
fetch('https://api.beework.app/v1/feeds/my_feed_id/posts?limit=10', { method: 'GET', headers: { Authorization: 'Bearer my_access_token' } })
  .then(res => res.json())
  .then(json => {
    console.log(json)
  })

//subtype:+axios
axios({
  url: 'https://api.beework.app/v1/feeds/my_feed_id/posts?limit=10',
  method: 'GET',
  headers: { Authorization: 'Bearer my_access_token' }
}).then((res) => {
  console.log(res.data)
});

curl "https://api.beework.app/v1/feeds/my_feed_id/posts?limit=10" \
  -H "Authorization: Bearer my_access_token"

from urllib import request, parse
import json

req = request.Request(
  'https://api.beework.app/v1/feeds/my_feed_id/posts',
  data=data
)
res = json.load(request.urlopen(req))
print(res)

Example Response

{
  "meta": {
    "resume_key": 458934864352
  },
  "data": {
    "f1VMhYZV8O": {
      "like_count": 8,
      "comment_count": 8,
      "author_name": "John Doe",
      "author_id": "my_user_id123",
      "created_date": 160123454,
      "body": "Hello!\n\nExample feed post body."
    },
    "dMjGfphbOF": {
      "like_count": 8,
      "comment_count": 8,
      "author_name": "John Doe",
      "author_id": "my_user_id123",
      "created_date": 160123454,
      "body": "Hello!\n\nExample feed post body."
    }
  }
}

Get feed posts (sorted by timestamp descending)


Required Scope:	feeds
Rate Limit:	15 requests per user, 24 hours (rolling)

Request

GET /v1/feeds/:feed_id/posts?limit=10

Query String Parameters:

Field	Type	Description
limit	int (max 25)	Max number of feed posts to return

Response Metadata

Key	Type	Description
resume_key	number	A key which can be used to verify data consistency

Response Data

An Object with post ID as keys, and post details as values:

Key	Type	Description
body	string	Body text
author_name	string	Full name of the author
like_count	number	Number of likes ("energy")
comment_count	number	Number of comments
created_date	number	The creation time as a Unix Timestamp

Example Request

//subtype:+fetch
fetch('https://api.beework.app/v1/subscriptions/feeds/my_feed_id/posts', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer my_access_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ url: 'https://example.com/webhooks/feeds/my_feed_id/posts' })
})
  .then(res => res.json())
  .then(json => {
    console.log(json)
  })

//subtype:+axios
axios({
  url: 'https://api.beework.app/v1/subscriptions/feeds/my_feed_id/posts',
  method: 'PUT',
  data: { url: 'https://example.com/webhooks/feeds/my_feed_id/posts' },
  headers: { Authorization: 'Bearer my_access_token' }
}).then((res) => {
  console.log(res.data)
});

curl "https://api.beework.app/v1/subscriptions/feeds/my_feed_id/posts" \
  -H "Authorization: Bearer my_access_token" \
  -X PUT \
  -F "url"="https://example.com/webhooks/feeds/my_feed_id/posts"

from urllib import request, parse
import json

data = parse.urlencode(
  {
    "url": "https://example.com/webhooks/feeds/my_feed_id/posts"
  }
).encode()
req = request.Request(
  'https://api.beework.app/v1/subscriptions/feeds/my_feed_id/posts',
  data=data, method="PUT"
)
res = json.load(request.urlopen(req))
print(res)

Subscribe to changes of posts in a feed using webhooks.


Required Scope:	feeds
Rate Limit:	50 requests per user, 24 hours (rolling)

Request Data

PUT /api/v1/subscriptions/feeds/:feed_id/posts

Key	Type	Description
url	string	Your webhook URL

Webhook event format

Example event

{
  "meta": {
    "resume_key": 8934567894,
    "action": "PUT",
    "event_id": "my_event_id123"
  },
  "data": {
    "like_count": 8,
    "comment_count": 8,
    "author_name": "John Doe",
    "author_id": "my_user_id123",
    "created_date": 160123454,
    "body": "Hello!\n\nExample feed post body."
  }
}

The request which is sent to your url.

Webhook Request Metadata

Key	Type	Description
resume_key	number	A key which can be used to verify data consistency
action	string	`"PUT"` or `"DELETE"`
post_id	string	ID of the affected post

Webhook Request Data

null if action is "DELETE". Object of event details if action is "PUT":

Key	Type	Description
body	string	Body text
author_name	string	Full name of the author
like_count	number	Number of likes ("energy")
comment_count	number	Number of comments
created_date	number	The creation time as a Unix Timestamp

Unsubscribe From Feed Posts

Example Request

//subtype:+fetch
fetch('https://api.beework.app/v1/subscriptions/feeds/my_feed_id/posts', {
  method: 'DELETE',
  headers: { Authorization: 'Bearer my_access_token' }
})
  .then(res => res.json())
  .then(json => {
    console.log(json)
  })

//subtype:+axios
axios({
  url: 'https://api.beework.app/v1/subscriptions/feeds/my_feed_id/posts',
  method: 'DELETE',
  headers: { Authorization: 'Bearer my_access_token' }
}).then((res) => {
  console.log(res.data)
});

curl "https://api.beework.app/v1/subscriptions/feeds/my_feed_id/posts" \
  -H "Authorization: Bearer my_access_token" \
  -X DELETE

from urllib import request, parse
import json

req = request.Request(
  'https://api.beework.app/v1/subscriptions/feeds/my_feed_id/posts',
  data=data, method="DELETE"
)
res = json.load(request.urlopen(req))
print(res)

Remove webhooks subscription for the specified feed.

Request

DELETE /api/v1/subscriptions/feeds/:feed_id/posts

Event Lists

List Event Lists

Example Request

//subtype:+fetch
fetch('https://api.beework.app/v1/event_lists', { method: 'GET', headers: { Authorization: 'Bearer my_access_token' } })
  .then(res => res.json())
  .then(json => {
    console.log(json)
  })

//subtype:+axios
axios({
  url: 'https://api.beework.app/v1/event_lists',
  method: 'GET',
  headers: { Authorization: 'Bearer my_access_token' }
}).then((res) => {
  console.log(res.data)
});

curl "https://api.beework.app/v1/event_lists" \
  -H "Authorization: Bearer my_access_token"

from urllib import request, parse
import json

req = request.Request(
  'https://api.beework.app/v1/event_lists',
  data=data
)
res = json.load(request.urlopen(req))
print(res)

Example Response

{
  "data": {
    "my_event_list_id123": {
      "subscribed": true,
      "admin": false,
      "name": "Company Events",
      "description": "Reminders to change your password",
      "avatar_url": "https://example.com/my_event_list_avatar123.jpg"
    }
  }
}

Fetch a list of all event lists which the authenticated user has access to read.

Request

GET /v1/event_lists

Response

Key	Type	Description
name	string	Event list name
description	string	`"Company news and current events"`
avatar_url	string \| null	Event list image URL
subscribed	boolean	User is subscribed to the event list
admin	boolean	User has admin

Get Event List

Example Request

//subtype:+fetch
fetch('https://api.beework.app/v1/event_lists/my_event_list_id', { method: 'GET', headers: { Authorization: 'Bearer my_access_token' } })
  .then(res => res.json())
  .then(json => {
    console.log(json)
  })

//subtype:+axios
axios({
  url: 'https://api.beework.app/v1/event_lists/my_event_list_id',
  method: 'GET',
  headers: { Authorization: 'Bearer my_access_token' }
}).then((res) => {
  console.log(res.data)
});

curl "https://api.beework.app/v1/event_lists/my_event_list_id" \
  -H "Authorization: Bearer my_access_token"

from urllib import request, parse
import json

req = request.Request(
  'https://api.beework.app/v1/event_lists/my_event_list_id',
  data=data
)
res = json.load(request.urlopen(req))
print(res)

Example Response

{
  "data": {
    "subscribed": true,
    "admin": false,
    "name": "Company Events",
    "avatar_url": "https://example.com/my_event_list_avatar123.jpg",
    "description": "Upcoming company events"
  }
}

Request

GET /v1/event_lists/:event_list_id

Response Data

An Object describing an event list

Key	Type	Description
name	string	Event list name
description	string	Event list description
avatar_url	string \| null	Event list image URL
subscribed	boolean	User is subscribed
admin	boolean	User has admin permissions

List Events

Example Request

//subtype:+fetch
fetch('https://api.beework.app/v1/event_lists/my_event_list_id/my_event_id/events', { method: 'GET', headers: { Authorization: 'Bearer my_access_token' } })
  .then(res => res.json())
  .then(json => {
    console.log(json)
  })

//subtype:+axios
axios({
  url: 'https://api.beework.app/v1/event_lists/my_event_list_id/my_event_id/events',
  method: 'GET',
  headers: { Authorization: 'Bearer my_access_token' }
}).then((res) => {
  console.log(res.data)
});

curl "https://api.beework.app/v1/event_lists/my_event_list_id/my_event_id/events" \
  -H "Authorization: Bearer my_access_token"

from urllib import request, parse
import json

req = request.Request(
  'https://api.beework.app/v1/event_lists/my_event_list_id/my_event_id/events',
  data=data
)
res = json.load(request.urlopen(req))
print(res)

Example Response

{
  "meta": {
    "resume_key": 32476293
  },
  "data": {
    "my_event_id123": {
      "title": "Putt-putt",
      "body": "The annual Miniature Golf competition",
      "interested_count": 49,
      "comment_count": 8,
      "author_name": "John Doe",
      "author_id": "my_user_id123",
      "created_date": 12498234598,
      "location": "Habo",
      "start_date": 1612134000,
      "end_date": 1612220400,
      "cover_image_url": https://example.com/banner.jpg
    }
  }
}

Get events from the specified event list. Events which ended more than 14 days ago will not be included.

Request

GET /v1/event_lists/:event_list_id/events

Response Metadata

Key	Type	Description
resume_key	number	A key which can be used to verify data consistency

Response data

An Object with event ID as key, event details as value:

Key	Type	Description
title	string	Event title
body	string	Body text
author_name	string	Full name of the author
interested_count	number	Number of interested users
comment_count	number	Number of comments
created_date	number	The creation time as a Unix Timestamp
author_id	string	Author's user ID
location	string	Event location
start_date	number	Event start date as a Unix Timestamp
end_date	number	Event start date as a Unix Timestamp
cover_image_url	string \| null	URL of the event cover image

Example Request

//subtype:+fetch
fetch('https://api.beework.app/v1/subscriptions/event_lists/my_event_list_id/events', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer my_access_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com/webhooks/event_lists/my_event_list_id/events'
  })
})
  .then(res => res.json())
  .then(json => {
    console.log(json)
  })

//subtype:+axios
axios({
  url: 'https://api.beework.app/v1/subscriptions/event_lists/my_event_list_id/events',
  method: 'PUT',
  data: {
    url: 'https://example.com/webhooks/event_lists/my_event_list_id/events'
  },
  headers: { Authorization: 'Bearer my_access_token' }
}).then((res) => {
  console.log(res.data)
});

curl "https://api.beework.app/v1/subscriptions/event_lists/my_event_list_id/events" \
  -H "Authorization: Bearer my_access_token" \
  -X PUT \
  -F "url"="https://example.com/webhooks/event_lists/my_event_list_id/events"

from urllib import request, parse
import json

data = parse.urlencode(
  {
    "url": "https://example.com/webhooks/event_lists/my_event_list_id/events"
  }
).encode()
req = request.Request(
  'https://api.beework.app/v1/subscriptions/event_lists/my_event_list_id/events',
  data=data, method="PUT"
)
res = json.load(request.urlopen(req))
print(res)

Request Data

PUT /api/v1/subscriptions/event_lists/:event_list_id/events

Key	Type	Description
url	string	Your webhook URL

Webhook event format

Example event

{
  "meta": {
    "resume_key": 8934567894,
    "action": "PUT",
    "event_id": "my_event_id123"
  },
  "data": {
    "title": "Putt-putt",
    "body": "The annual Miniature Golf competition",
    "interested_count": 49,
    "comment_count": 8,
    "author_name": "John Doe",
    "author_id": "my_user_id123",
    "created_date": 12498234598,
    "location": "Habo",
    "start_date": 1612134000,
    "end_date": 1612220400,
    "cover_image_url": https://example.com/my_avatar123.jpg
  }
}

The request which is sent to your url.

Webhook Request Metadata

Key	Type	Description
resume_key	number	A key which can be used to verify data consistency
action	string	`"PUT"` or `"DELETE"`
event_id	string	ID of the affected event

Webhook Request Data

null if action is "DELETE". Object of event details if action is "PUT":

Key	Type	Description
title	string	Event title
description	string	Body text
author_name	string	Full name of the author
interested_count	number	Number of interested users
comment_count	number	Number of comments
created_date	number	The creation time as a Unix Timestamp

Unsubscribe From Events

Example Request

//subtype:+fetch
fetch('https://api.beework.app/v1/subscriptions/event_lists/my_event_list_id/events', {
  method: 'DELETE',
  headers: { Authorization: 'Bearer my_access_token' }
})
  .then(res => res.json())
  .then(json => {
    console.log(json)
  })

//subtype:+axios
axios({
  url: 'https://api.beework.app/v1/subscriptions/event_lists/my_event_list_id/events',
  method: 'DELETE',
  headers: { Authorization: 'Bearer my_access_token' }
}).then((res) => {
  console.log(res.data)
});

curl "https://api.beework.app/v1/subscriptions/event_lists/my_event_list_id/events" \
  -H "Authorization: Bearer my_access_token" \
  -X DELETE

from urllib import request, parse
import json

req = request.Request(
  'https://api.beework.app/v1/subscriptions/event_lists/my_event_list_id/events',
  data=data, method="DELETE"
)
res = json.load(request.urlopen(req))
print(res)

Removes the webhook subscription for the specified event list.

Request

DELETE /api/v1/subscriptions/event_lists/:event_list_id/events

Birthday Users

Example Request

//subtype:+fetch
fetch('https://api.beework.app/v1/birthdays/08-26', { method: 'GET', headers: { Authorization: 'Bearer my_access_token' } })
  .then(res => res.json())
  .then(json => {
    console.log(json)
  })

//subtype:+axios
axios({
  url: 'https://api.beework.app/v1/birthdays/08-26',
  method: 'GET',
  headers: { Authorization: 'Bearer my_access_token' }
}).then((res) => {
  console.log(res.data)
});

curl "https://api.beework.app/v1/birthdays/08-26" \
  -H "Authorization: Bearer my_access_token"

from urllib import request, parse
import json

req = request.Request(
  'https://api.beework.app/v1/birthdays/08-26',
  data=data
)
res = json.load(request.urlopen(req))
print(res)

Example Response

{
  "data": {
    "my_user_id123": {
      "avatar_url": "https://example.com/my_avatar123.jpg",
      "email": "john@example.com",
      "status": "available",
      "birthday": "12-31",
      "full_name": "John Doe",
      "given_name": "John",
      "family_name": "Doe",
      "workplace_id": "my_workplace_id123",
      "title": "Assistant to the regional manager",
      "status_text": "I'm vabbing today"
    }
  }
}

Get a list of birthday celebrants for the specified date. It's not possible to subscribe to this data, but you are able to fetch a few days in advance if you need to.


Required Scope:	colleagues
Rate Limit:	15 requests per 24 hours (rolling)

Workplaces

Example Request

//subtype:+fetch
fetch('https://api.beework.app/v1/workplaces', { method: 'GET', headers: { Authorization: 'Bearer my_access_token' } })
  .then(res => res.json())
  .then(json => {
    console.log(json)
  })

//subtype:+axios
axios({
  url: 'https://api.beework.app/v1/workplaces',
  method: 'GET',
  headers: { Authorization: 'Bearer my_access_token' }
}).then((res) => {
  console.log(res.data)
});

curl "https://api.beework.app/v1/workplaces" \
  -H "Authorization: Bearer my_access_token"

from urllib import request, parse
import json

req = request.Request(
  'https://api.beework.app/v1/workplaces',
  data=data
)
res = json.load(request.urlopen(req))
print(res)

Example Response

{
  "data": {
    "my_workplace_id123": {
      "avatar_url": "https://example.com/my_avatar123.jpg",
      "name": "Development",
      "email": "development@example.com",
      "phone": null,
      "address": "Fake Street 123"
    }
  }
}

List all workplaces on the organization.


Required Scope:	workplaces
Rate Limit:	15 requests per 24 hours (rolling)

Workplace

Example Request

//subtype:+fetch
fetch('https://api.beework.app/v1/workplaces/my_workplace_id', { method: 'GET', headers: { Authorization: 'Bearer my_access_token' } })
  .then(res => res.json())
  .then(json => {
    console.log(json)
  })

//subtype:+axios
axios({
  url: 'https://api.beework.app/v1/workplaces/my_workplace_id',
  method: 'GET',
  headers: { Authorization: 'Bearer my_access_token' }
}).then((res) => {
  console.log(res.data)
});

curl "https://api.beework.app/v1/workplaces/my_workplace_id" \
  -H "Authorization: Bearer my_access_token"

from urllib import request, parse
import json

req = request.Request(
  'https://api.beework.app/v1/workplaces/my_workplace_id',
  data=data
)
res = json.load(request.urlopen(req))
print(res)

Example Response

{
  "data": {
    "avatar_url": "https://example.com/my_avatar123.jpg",
    "name": "Development",
    "email": "development@example.com",
    "phone": null,
    "address": "Fake Street 123"
  }
}

Get info about given workplace.


Required Scope:	workplaces
Rate Limit:	15 requests per 24 hours (rolling)

Request

GET /v1/workplace/:workplace_id

Response data

An object with workplace data.

Key	Type	Description
name	string	Workplace name
avatar_url	string \| null	Workplace image URL
email	string \| null	Email
phone	string \| null	Phone no.
address	string \| null	Workplace address

User Availability

List Users With Given Availability Status

Example Request

//subtype:+fetch
fetch('https://api.beework.app/v1/availability/available', { method: 'GET', headers: { Authorization: 'Bearer my_access_token' } })
  .then(res => res.json())
  .then(json => {
    console.log(json)
  })

//subtype:+axios
axios({
  url: 'https://api.beework.app/v1/availability/available',
  method: 'GET',
  headers: { Authorization: 'Bearer my_access_token' }
}).then((res) => {
  console.log(res.data)
});

curl "https://api.beework.app/v1/availability/available" \
  -H "Authorization: Bearer my_access_token"

from urllib import request, parse
import json

req = request.Request(
  'https://api.beework.app/v1/availability/available',
  data=data
)
res = json.load(request.urlopen(req))
print(res)

Example Response

{
  "meta": {
    "resume_key": 347528965
  },
  "data": {
    "my_user_id123": {
      "avatar_url": "https://example.com/my_avatar123.jpg",
      "email": "john@example.com",
      "status": "available",
      "birthday": "12-31",
      "full_name": "John Doe",
      "given_name": "John",
      "family_name": "Doe",
      "workplace_id": "my_workplace_id123",
      "title": "Assistant to the regional manager",
      "status_text": "I'm vabbing today"
    }
  }
}

Get a list of the 20 users who last changed their availability with an optional filter: ("available" | "unavailable" | "busy" | "absent" | "vacation").

Request

GET /v1/availability/:filter?

Response Metadata

Key	Type	Description
resume_key	number	A key which can be used to verify data consistency

Response Data

Key	Type	Description
avatar_url	string \| null	User avatar URL
birthday	string \| null	Birthday in MM-dd format
email	string	E-mail address
family_name	string \| null	Last name
full_name	string \| null	Full name or e-mail
given_name	string \| null	First name
status	Status	The user's current status
status_text	string \| null	Status text
title	string \| null	Profession
workplace_id	string \| null	ID of user workplace

Example Request

//subtype:+fetch
fetch('https://api.beework.app/v1/subscriptions/availability/available', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer my_access_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ url: 'https://example.com/webhooks/availability/available' })
})
  .then(res => res.json())
  .then(json => {
    console.log(json)
  })

//subtype:+axios
axios({
  url: 'https://api.beework.app/v1/subscriptions/availability/available',
  method: 'PUT',
  data: { url: 'https://example.com/webhooks/availability/available' },
  headers: { Authorization: 'Bearer my_access_token' }
}).then((res) => {
  console.log(res.data)
});

curl "https://api.beework.app/v1/subscriptions/availability/available" \
  -H "Authorization: Bearer my_access_token" \
  -X PUT \
  -F "url"="https://example.com/webhooks/availability/available"

from urllib import request, parse
import json

data = parse.urlencode(
  {
    "url": "https://example.com/webhooks/availability/available"
  }
).encode()
req = request.Request(
  'https://api.beework.app/v1/subscriptions/availability/available',
  data=data, method="PUT"
)
res = json.load(request.urlopen(req))
print(res)

Subscribe to webhook events for user availability changes to or from an optional filter: ("available" | "unavailable" | "busy" | "absent" | "vacation").

Request Data

PUT /api/v1/subscriptions/availability/:filter?

Key	Type	Description
url	string	Your webhook URL

Webhook event format

Example event

{
  "meta": {
    "resume_key": 4335902904,
    "action": "PUT",
    "user_id": "my_user_id123"
  },
  "data": {
    "avatar_url": "https://example.com/my_avatar123.jpg",
    "birthday": "12-31",
    "email": "john@example.com",
    "family_name": "Doe",
    "full_name": "John Doe",
    "given_name": "John",
    "status": "available",
    "status_text": "I'm vabbing today",
    "title": "Assistant to the regional manager",
    "workplace_id": "my_workplace_id123"
  }
}

The request which is sent to your url.

Webhook Request Metadata

Key	Type	Description
resume_key	number	A key which can be used to verify data consistency
action	string	`"PUT"` or `"DELETE"`
user_id	string	ID of the affected user

Webhook Request Data

null if action is "DELETE". Object of user details if action is "PUT":

Key	Type	Description
avatar_url	string \| null	User avatar URL
birthday	string \| null	Birthday in MM-dd format
email	string	E-mail address
family_name	string \| null	Last name
full_name	string \| null	Full name or e-mail
given_name	string \| null	First name
status	Status	The user's current status
status_text	string \| null	Status text
title	string \| null	Profession
workplace_id	string \| null	ID of user workplace

Unsubscribe from user availability changes

Example Request

//subtype:+fetch
fetch('https://api.beework.app/v1/subscriptions/availability/available', {
  method: 'DELETE',
  headers: { Authorization: 'Bearer my_access_token' }
})
  .then(res => res.json())
  .then(json => {
    console.log(json)
  })

//subtype:+axios
axios({
  url: 'https://api.beework.app/v1/subscriptions/availability/available',
  method: 'DELETE',
  headers: { Authorization: 'Bearer my_access_token' }
}).then((res) => {
  console.log(res.data)
});

curl "https://api.beework.app/v1/subscriptions/availability/available" \
  -H "Authorization: Bearer my_access_token" \
  -X DELETE

from urllib import request, parse
import json

req = request.Request(
  'https://api.beework.app/v1/subscriptions/availability/available',
  data=data, method="DELETE"
)
res = json.load(request.urlopen(req))
print(res)

Removes the webhook subscription for availability changes affected by the specified filter.

Request

DELETE /api/v1/subscriptions/availability/:filter

Getting Started

1. API Access

2. Authorization

3. REST API

4. Webhook Subscriptions

Authorization Details

Authorize Endpoint

Request Parameters (Query String)

Token Endpoint

Request Parameters (Query String)

Request Parameters (Query String)

Response Data (JSON Encoded)

Redirect URI

Scopes

User scope

Feeds scope

Event Lists scope

Workplaces scope

Colleagues scope

Application Credentials

Authorization Guide

Flow Summary

1. Sign In

2. Redirect

3. Get Access Token

4. Token Refresh

Request Parameters (Query String)

Response Data (JSON encoded)

Requests

Authorization Header

Request Format

Response Format

Errors

Rate Limiting

Subscriptions

Data Consistency

Irrelevant requests

User

Get user info

Request

Response Data

Response Metadata

Feeds

List Feeds

Request

Response Data

Get Feed

Request

Response Data

List Posts

Request

Response Metadata

Response Data

Subscribe To Feed Posts

Request Data

Webhook event format

Webhook Request Metadata

Webhook Request Data

Unsubscribe From Feed Posts

Request

Event Lists

List Event Lists

Request

Response

Get Event List

Request

Response Data

List Events

Request

Response Metadata

Response data

Subscribe To Events

Request Data

Webhook event format

Webhook Request Metadata

Webhook Request Data

Unsubscribe From Events

Request

Birthday Users

Workplaces