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://api.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:

• use HTTPS
• include an HTTP Basic Authentication Header using the API token as username and leaving the password blank.

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://api.givebriq.com/v0/organizations/your-organization/users?per_page=1"

The response will include the appropriate Link HTTP headers if needed

Link: <https://api.givebriq.com/v0/organizations/your-organization/users?page=2&per_page=1>; rel="next", <https://api.givebriq.com/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://api.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://api.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://api.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://api.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://api.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://api.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://api.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://api.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://api.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://api.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://api.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://api.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://api.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://api.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://api.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://api.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://api.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://api.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.