API and integrations
API and integrations
Flaree has a REST API for sending recognition and reading people, cards and leaderboards from your own systems. This page covers generating a key, the four endpoints, and what Zapier and Make.com can and cannot do today.
What the API can do
The API lets you send a Flaree from another system, and read your people, your card library and your leaderboard.
These are endpoints you call, not callbacks Flaree sends you. Several paths contain the word webhook for historical reasons, but nothing in Flaree posts to a URL of yours when something happens. There is no event subscription and no callback registration. If you need to react to new recognition, poll on a schedule.
Getting an API key
Go to Settings → Integration and open the API Key tab. Give the key a name and generate it.
The tab is visible to Administrators and the Owner. Editors and employees never see it.
The key stays readable. Unlike most services, Flaree does not hide the key after creation. You can return to this tab at any time and copy it again. Treat it accordingly: anyone who can open that tab can read every key, and a key can send recognition on behalf of your company.
A key is 64 hexadecimal characters with no prefix.
Rotating a key
There is no rotate button. Generate a new key, switch your integration over to it, then deactivate the old one. Deactivating is immediate and cannot be undone, so change the integration first.
Deactivated keys stay listed rather than disappearing.
Authentication
Send your key in the x-api-key header on every request. There is no signature, token exchange or expiry.
x-api-key: your-64-character-key
Add Content-Type: application/json when you POST.
Status | Title | When |
|---|---|---|
401 | Missing API Key | The header was absent or empty. |
401 | Invalid API Key | The key is unknown or has been deactivated. The two are indistinguishable. |
403 | Company Blocked | The account cannot use the API. Contact support. |
The base URL
https://api.flaree.app
Interactive documentation is at https://api.flaree.app/swagger. Note that the leaderboard endpoint below works but is not listed there.
Sending a Flaree
POST https://api.flaree.app/companies/webhook/flaree
Field | Required | Notes |
|---|---|---|
| Yes | Always send it. Omitting it produces a server error rather than a clear message. |
| Yes | Who the recognition is from. Not needed for a system transfer. |
| One of | The card id. Takes priority if you also send a name. |
| One of | The card name, matched without case sensitivity. |
| Yes | A whole number from 1 to 100. |
| No | Reaches the recipient by email and in Slack. |
| No | Attributes the Flaree to the Flaree Assistant instead of a person. |
A success returns 201 with the transfer id, the card id, and how many units of that card remain.
The API follows the same rules as the app
Nothing here is a back door. Every rule that applies in the product applies to the API:
100 points per recipient per day, counted per sender and recipient pair, resetting at midnight in your company timezone. Going over is refused outright rather than trimmed.
Card units are consumed. When a card runs out you get All Kudos Given.
No self-recognition, and no sending to deactivated, removed or not-yet-registered people.
The giver needs permission to send. See Roles and permissions.
Common errors: 400 Daily Points Limit Reached, 400 All Kudos Given, 400 Invalid Transfer for self-sends, 404 Card Not Found, 404 Receiver Not Found, 403 Missing Permission.
Two different error shapes. Business errors return an error object with a title and message. Errors caught by field validation, such as points above 100 or a malformed card id, return a different shape with a message array and no error wrapper. Handle both, or your client will break on the second kind.
Reading your people
GET https://api.flaree.app/companies/webhook/users
Optional search (matches email or name), limit (default 50, maximum 100) and offset. Returns id, email, full name and department for each active member, plus a total that ignores paging.
Only people who can actually receive a Flaree are returned, so anything here is a valid recipient. Department is empty when unassigned.
Reading your cards
GET https://api.flaree.app/companies/webhook/flaree-cards
No parameters. Returns every active card with its id, name, description, tag, image URL and remaining units.
The image URL is time limited. Fetch it fresh when you need it rather than storing it.
Reading the leaderboard
GET https://api.flaree.app/companies/webhook/leaderboard
Optional dateRange (defaults to ALL_TIME), limit (default 10, maximum 100), and sprintDays when using LAST_SPRINT.
Accepted ranges: LAST_WEEK, LAST_SPRINT, LAST_MONTH, CURRENT_MONTH, QUARTERLY_KINGS, BADGE_LOVERS, ALL_TIME, MONTH_1_AGO through MONTH_5_AGO, QUARTER_1_AGO and QUARTER_2_AGO.
Returns rank, email, full name and total points. People with no points are absent.
Checking a key works
GET https://api.flaree.app/companies/validate/api-key
Returns your company id and name. Useful as a connection test.
You can pass an x-email header to check whether that address is an active member. Read the metadata field for the answer, not the status code: an address that is not a member still returns a success.
Rate limits
There are no published rate limits. Poll at a sensible interval rather than continuously.
Zapier and Make.com
Both are listed on the pricing page, and neither is a finished integration today. There is no Flaree app you can install in Make.com, and the Zapier listing is not a supported integration. If you want Flaree connected to another tool now, call the REST API above directly, or talk to us about what you are trying to build.
What the API supports today shapes what any such connector could do: sending a Flaree, and looking up people, cards and rankings. Anything that reacts the moment a Flaree is sent is not possible, because there is no outbound event mechanism.
Plan availability
API access, API key management, webhooks, Zapier and Make.com are listed as part of the Advance plan.
Common questions
My key worked yesterday and now returns Invalid API Key.
Either it was deactivated, or the header is not arriving. The two look identical from the outside. Confirm with the validate endpoint, and check that whatever sits in front of your integration forwards the x-api-key header.
Can Flaree notify my system when someone sends recognition?
Not today. There is no outbound callback. Poll the endpoints instead.
Where is the leaderboard endpoint in the API documentation?
It is missing from the published documentation but the endpoint works. Use the details on this page.
I sent 100 points twice to the same person and the second call failed.
Working as intended. The daily limit is 100 points per recipient per day, and the API enforces it exactly as the app does.
Can I raise the points limit for an automation?
No. The only exception is a system transfer, which attributes the Flaree to the Flaree Assistant rather than a person.
My request failed with a message array instead of an error object.
That is field validation, usually points outside 1 to 100 or a malformed card id. Read the message array for the specific field.
Last updated