NAV Navbar
javascript shell

Introduction

Welcome to the Briq API. Briq lets you send Briqs to teammates, small tokens of appreciation to say thanks or congrats.

This API lets you create, read, update and delete (OMG, CRUD) users, user groups, transactions and messages.

We have a client library in node.js that will help you craft the perfect requests.

Authentication

Use the token to make authenticated calls to the API

const Briq = require('briq-api').Client;
const briq = new Briq('briq_api_token');
#Pass the token as the username in a Basic HTTP Authorization header
curl -u briq_api_token: https://www.givebriq.com/v0/organizations/your-organization

Make sure to replace briq_api_token with your API key.

Briq uses API tokens to allow access to the API. You can get your token by creating a new custom application in the Briq admin section.

Briq only accepts API requests that:

This is supported out of the box by our API client libraires, see this MDN page for manual implementation.

Pagination

const Briq = require('briq-api').Client;
const briq = new Briq('briq_api_token');
const users = await briq.organization('your-organization').users({ per_page: 1 });
curl -i -u briq_api_token "https://www.givebriq.com/v0/organizations/your-organization/users?per_page=1"

The response will include the appropriate Link HTTP headers if needed

Link: <http://briq.localhost:3000/v0/organizations/your-organization/users?page=2&per_page=1>; rel="next", <http://briq.localhost:3000/v0/organizations/your-organization/users?page=2&per_page=1>; rel="last"

Endpoints that return arrays of results are paginated. first, previous, next and last pages are added as Link HTTP headers if needed.

Parameter Default Description
page 1 The page number
per_page 100 The maximum number of results per page

Organization

Get details of your organization

const Briq = require('briq-api').Client;
const briq = new Briq('briq_api_token');
const organization = await briq.organization('your-organization').info();
curl -u briq_api_token "https://www.givebriq.com/v0/organizations/your-organization"

Replace your-organization with the name of your organization (find it in your Briq settings). The above command will resolve to a JSON structured like this:

{
    "id": "c5e91a81-0c92-4069-b002-26e8df8aa556",
    "key": "your-organization",
    "created_at": "2018-10-17T09:31:27.907Z"
}

This endpoint retrieves information about the current organization.

HTTP Request

GET https://www.givebriq.com/v0/organizations/<organization_name>

URL Parameters

Parameter Description
organization_name The name of your organization

Users

List all users of organization

const Briq = require('briq-api').Client;
const briq = new Briq('briq_api_token');
const users = await briq.organization('your-organization').users();
curl -u briq_api_token "https://www.givebriq.com/v0/organizations/your-organization/users"

The above command returns JSON structured like this:

[
  {
    "id": "ddfdb19c-e3ad-4300-8ed7-d79e10b9f124",
    "username": "alice@your-organization.com",
    "displayName": "Alice",
    "email": "alice@your-organization.com",
    "externalRef": null,
    "firstName": null,
    "lastName": null,
    "inactiveBalance": 6,
    "activeBalance": 1,
    "role": "user",
    "created_at": "2018-10-17T09:55:16.829Z",
    "image": null
  },
  {
    "id": "eb17a3df-c384-46a9-96a1-d7f58912e19a",
    "username": "laurent@your-organization.com",
    "displayName": "Laurent",
    "email": "laurent@your-organization.com",
    "externalRef": null,
    "firstName": null,
    "lastName": null,
    "inactiveBalance": 5,
    "activeBalance": 0,
    "role": "admin",
    "created_at": "2018-10-17T09:32:19.736Z",
    "image": null
  }
]

This endpoint lists all the users of the organization (paginated).

HTTP Request

GET https://www.givebriq.com/v0/organizations/<organization_name>/users

URL Parameters

Parameter Description
organization_name The name of your organization

Results

This endpoint returns an array of users. See this section for a description of a user.

Get details of a user

const Briq = require('briq-api').Client;
const briq = new Briq('briq_api_token');
const user = await briq.organization('your-organization').user('user-id');
curl -u briq_api_token "https://www.givebriq.com/v0/organizations/your-organization/users/user-id"

Replace user-id with the id of the user The above command returns JSON structured like this:

{
  "id": "ddfdb19c-e3ad-4300-8ed7-d79e10b9f124",
  "username": "alice",
  "displayName": "Alice",
  "email": "alice@your-organization.com",
  "externalRef": null,
  "firstName": null,
  "lastName": null,
  "inactiveBalance": 6,
  "activeBalance": 1,
  "role": "user",
  "created_at": "2018-10-17T09:55:16.829Z",
  "image": null,
  "invitedAt": "2018-10-17T09:54:56.381Z",
  "onboardedAt": "2018-10-17T09:55:16.816Z",
  "timezone": "Europe/Brussels",
  "platform": "web",
  "suspended": false
}

This endpoint retrieves the details of a user.

HTTP Request

GET https://www.givebriq.com/v0/organizations/<organization_name>/users/<user_id>

URL Parameters

Parameter Description
organization_name The name of your organization
user_id The id of the user to fetch (username and externalRef can be used too)

Results

This endpoint returns a JSON user with the following attributes:

Parameter Description
id The unique identifier of the user
username The username of the user, must be unique per organization
email The email of the user, must be unique per organization
displayName The name to use for the user in the interface,
externalRef A string referencing the user in another data source
firstName The first name of the user
lastName The last name of the user
inactiveBalance The balance of Briqs to give
activeBalance The balance of Briqs to redeem
role The role of the user (values: user, admin)
image A URL for an image to be used as avatar for the user
created_at The timestamp at which this user was created
invitedAt The timestamp at which this user was invited to participate to Briq
onboardedAt The timestamp at which this user completed their onboarding
timezone The timezone configured for this user
platform The plaform from which this user was created (can be slack or web)
suspended A flag that is true if the user has been suspended

User Groups

List existing User Groups

const Briq = require('briq-api').Client;
const briq = new Briq('briq_api_token');
const groups = await briq.organization('your-organization').groups();
curl -u briq_api_token "https://www.givebriq.com/v0/organizations/your-organization/groups"

The above command returns JSON structured like this:

[
    {
        "id": "ddc1dad7-d323-46d0-97a3-ae806e70e94a",
        "externalRef": null,
        "name": "Team engineering",
        "platform": "briq",
        "created_at": "2018-10-23T13:25:56.670Z",
        "users": [
            {
                "id": "ddfdb19c-e3ad-4300-8ed7-d79e10b9f124",
                "role": "user",
                "displayName": "Alice",
                "username": "alice",
                "externalRef": null,
                "email": "alice@your-organization.com",
                "firstName": null,
                "lastName": null,
                "inactiveBalance": 6,
                "activeBalance": 1,
                "platform": "web",
                "image": null,
                "suspended": false,
                "onboardedAt": "2018-10-17T09:55:16.816Z",
                "invitedAt": "2018-10-17T09:54:56.381Z",
                "timezone": "Europe/Brussels",
                "created_at": "2018-10-17T09:55:16.829Z",
            },
            {
                "id": "eb17a3df-c384-46a9-96a1-d7f58912e19a",
                "role": "admin",
                "displayName": "Laurent",
                "username": "laurent",
                "externalRef": null,
                "email": "laurent@your-organization.com",
                "firstName": null,
                "lastName": null,
                "inactiveBalance": 5,
                "activeBalance": 0,
                "platform": "web",
                "image": null,
                "suspended": false,
                "onboardedAt": "2018-10-17T09:32:19.722Z",
                "invitedAt": "2018-10-17T09:31:53.883Z",
                "timezone": "Europe/Brussels",
                "created_at": "2018-10-17T09:32:19.736Z",
            }
        ]
    },
]

This endpoint lists all the user groups of the organization (paginated)

HTTP Request

GET https://www.givebriq.com/v0/organizations/<organization_name>/groups

URL Parameters

Parameter Description
organization_name The name of your organization

Results

This endpoint returns an array of user groups. See this section for a description of a user group.

Get details of a User Group

const Briq = require('briq-api').Client;
const briq = new Briq('briq_api_token');
const group = await briq.organization('your-organization').group('group-id');
curl -u briq_api_token "https://www.givebriq.com/v0/organizations/your-organization/groups/group-id"

Replace group-id by the id of the group of which you're getting the details The above command returns JSON structured like this:

{
    "id": "ddc1dad7-d323-46d0-97a3-ae806e70e94a",
    "externalRef": null,
    "name": "Team engineering",
    "platform": "briq",
    "created_at": "2018-10-23T13:25:56.670Z",
    "users": [
        {
            "id": "ddfdb19c-e3ad-4300-8ed7-d79e10b9f124",
            "role": "user",
            "displayName": "Alice",
            "username": "alice",
            "externalRef": null,
            "email": "alice@your-organization.com",
            "firstName": null,
            "lastName": null,
            "inactiveBalance": 6,
            "activeBalance": 1,
            "platform": "web",
            "image": null,
            "suspended": false,
            "onboardedAt": "2018-10-17T09:55:16.816Z",
            "invitedAt": "2018-10-17T09:54:56.381Z",
            "timezone": "Europe/Brussels",
            "created_at": "2018-10-17T09:55:16.829Z",
        },
        {
            "id": "eb17a3df-c384-46a9-96a1-d7f58912e19a",
            "role": "admin",
            "displayName": "Laurent",
            "username": "laurent",
            "externalRef": null,
            "email": "laurent@your-organization.com",
            "firstName": null,
            "lastName": null,
            "inactiveBalance": 5,
            "activeBalance": 0,
            "platform": "web",
            "image": null,
            "suspended": false,
            "onboardedAt": "2018-10-17T09:32:19.722Z",
            "invitedAt": "2018-10-17T09:31:53.883Z",
            "timezone": "Europe/Brussels",
            "created_at": "2018-10-17T09:32:19.736Z",
        }
    ]
}

This endpoint returns the details for one user groups of the organization.

HTTP Request

GET https://www.givebriq.com/v0/organizations/<organization_name>/groups/<group_id>

URL Parameters

Parameter Description
organization_name The name of your organization
group_id The id of the group

Results

This endpoint returns an object representing a user group, which has the following properties:

Parameter Description
id The id of the group
name The name of the group
platform The platform on which this group was created and is managed (can be slack or briq)
externalRef If the user group is not a briq group, this is the identifier of the group on its original platform
created_at The creation date of the group
users An array of users in the group

Transactions

List transactions

const Briq = require('briq-api').Client;
const briq = new Briq('briq_api_token');
const transactions = await briq.organization('your-organization').transactions();
curl -u briq_api_token "https://www.givebriq.com/v0/organizations/your-organization/transactions"

The above command returns JSON structured like this:

[
        {
        "id": "8f49eb2e-2184-4966-be36-9a86db95bd0d",
        "from": "Laurent",
        "to": "Alice",
        "amount": 1,
        "comment": "Hello Alice  #TeamSpirit #Teamwork",
        "app": "give",
        "created_at": "2018-10-18T08:54:02.853Z",
        "reaction": null,
        "reactedAt": null,
        "user_from_id": "eb17a3df-c384-46a9-96a1-d7f58912e19a",
        "user_to_id": "ddfdb19c-e3ad-4300-8ed7-d79e10b9f124"
    }
]

This endpoint lists all the transactions of the organization (paginated)

HTTP Request

GET https://www.givebriq.com/v0/organizations/<organization_name>/transactions

URL Parameters

Parameter Description
organization_name The name of your organization

Results

This endpoint returns an array of transactions. See this section for a description of a transaction.

Get details of a transaction

const Briq = require('briq-api').Client;
const briq = new Briq('briq_api_token');
const transaction = await briq.organization('your-organization').transaction('transaction-id');
curl -u briq_api_token "https://www.givebriq.com/v0/organizations/your-organization/transactions/transaction-id"

Replace transaction-id with the id of the transaction The above command returns JSON structured like this:

{
    "id": "8f49eb2e-2184-4966-be36-9a86db95bd0d",
    "from": "Laurent",
    "to": "Alice",
    "amount": 1,
    "comment": "Hello Alice  #TeamSpirit #Teamwork",
    "app": "give",
    "created_at": "2018-10-18T08:54:02.853Z",
    "reaction": null,
    "reactedAt": null,
    "user_from_id": "eb17a3df-c384-46a9-96a1-d7f58912e19a",
    "user_to_id": "ddfdb19c-e3ad-4300-8ed7-d79e10b9f124",
    "userFrom": {
        "id": "eb17a3df-c384-46a9-96a1-d7f58912e19a",
        "username": "laurent",
        "displayName": "Laurent",
        "email": "laurent@your-organization.com",
        "externalRef": null,
        "firstName": null,
        "lastName": null,
        "inactiveBalance": 5,
        "activeBalance": 0,
        "role": "admin",
        "created_at": "2018-10-17T09:32:19.736Z",
        "image": null,
        "invitedAt": "2018-10-17T09:31:53.883Z",
        "onboardedAt": "2018-10-17T09:32:19.722Z",
        "timezone": "Europe/Brussels",
        "platform": "web",
        "suspended": false
    },
    "userTo": {
        "id": "ddfdb19c-e3ad-4300-8ed7-d79e10b9f124",
        "username": "alice",
        "displayName": "Alice",
        "email": "alice@your-organization.com",
        "externalRef": null,
        "firstName": null,
        "lastName": null,
        "inactiveBalance": 6,
        "activeBalance": 1,
        "role": "user",
        "created_at": "2018-10-17T09:55:16.829Z",
        "image": null,
        "invitedAt": "2018-10-17T09:54:56.381Z",
        "onboardedAt": "2018-10-17T09:55:16.816Z",
        "timezone": "Europe/Brussels",
        "platform": "web",
        "suspended": false
    }
}

This endpoint retrieves the details of a transaction.

HTTP Request

GET https://www.givebriq.com/v0/organizations/<organization_name>/transactions/<transaction_id>

URL Parameters

Parameter Description
organization_name The name of your organization
transaction_id The id of the transaction to fetch

Results

This endpoint returns a JSON transaction with the following attributes:

Parameter Description
id The unique identifier of the transaction
from The name of the user who gave Briqs for this transaction
to The name of the user who received Briqs for this transaction
amount The number of Briqs moved by the transaction
comment The comment on the transaction (usually the reason for the give to take place)
app The name of the app that created the transaction
created_at The creation date of the transaction
reaction The reaction that has been added to the transaction
reactedAt The timestamp when the reaction was added
user_from_id The id of the user who gave Briqs
user_to_id The id of the user who received Briqs
userFrom The user who gave Briqs, as a JSON object (see this section for details)
userTo The user who received Briqs, as a JSON object (see this section for details)

Create a transaction

const Briq = require('briq-api').Client;
const briq = new Briq('briq_api_token');
const transaction = await briq.organization('your-organization').createTransaction({
  amount: 2,
  comment: 'Thanks for your help with the presentation #teamspirit',
  from: 'alice',
  to: 'laurent'
});
curl -i -u briq_api_token
  --header "Content-Type: application/json" \
  --request POST \
  --data '{ "amount": 2, "comment": "Thanks for your help with the presentation #teamspirit", "from": "alice", "to": "laurent" }' \
  "https://www.givebriq.com/v0/organizations/your-organization/transactions"

The above command returns an HTTP 201 Created response and includes a Location header with the URL of the created transaction. It also includes the created transaction as JSON in the response

{
    "id": "e9758206-8f81-4292-a225-c4e7dab25cf8",
    "from": "Alice",
    "to": "Laurent",
    "amount": 1,
    "comment": "Thanks for your help with the presentation #teamspirit",
    "app": "API Documentation",
    "created_at": "2018-10-25T14:47:40.597Z",
    "reaction": null,
    "reactedAt": null,
    "user_from_id": "ddfdb19c-e3ad-4300-8ed7-d79e10b9f124",
    "user_to_id": "eb17a3df-c384-46a9-96a1-d7f58912e19a"
}

This endpoint creates a transaction.

HTTP Request

POST https://www.givebriq.com/v0/organizations/<organization_name>/transactions

URL Parameters

Parameter Description
organization_name The name of your organization

Body

A transaction can be created with the following attributes

Parameter Description
from The id, username, email or externalRef of the user who gave Briqs for this transaction. It can be empty, meaning that the user to will receive Briqs from the bank
to The id, username, email or externalRef of the user who receives Briqs for this transaction. It can be empty, meaning that the user from will spend Briqs from their active balance (redemption)
amount The number of Briqs moved by the transaction
comment The comment on the transaction (usually the reason for giving/redeeming briqs)

Results

The created transaction is returned as JSON in the body of the response. See this section for more details

Revert a transaction

const Briq = require('briq-api').Client;
const briq = new Briq('briq_api_token');
const transaction = await briq.organization('your-organization').refundTransaction('transaction-id');
curl -i -u briq_api_token --request DELETE "https://www.givebriq.com/v0/organizations/your-organization/transactions/transaction-id"

Replace transaction-id with the id of the transaction The above command returns an HTTP 204 No Content and an empty body when the revert is successful

This endpoint reverts a transaction.

HTTP Request

DELETE https://www.givebriq.com/v0/organizations/<organization_name>/transactions/<transaction_id>

URL Parameters

Parameter Description
organization_name The name of your organization
transaction_id The id of the transaction to revert

Results

If the revert is successful, an HTTP 204 No content response is sent.

Messages

Create a message

const Briq = require('briq-api').Client;
const briq = new Briq('briq_api_token');
const message = await briq.organization('your-organization').createMessage({
  header: 'Alice just earned 3 briqs for outstanding customer service',
  body: '5 ⭐ rating 5 days in a row 🔥',
  channel: '#general'
});

WIP

Errors

Briq API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
404 Not Found -- The specified model could not be found.