Artigo versão em Português
With Birdie, you can leverage your current stack of platforms handling user feedback to create a Feedback River. A constant flow of feedback reaches your Product Teams, allowing you to explore, analyze, and improve your decision-making processes.
You can browse our library of Connectors and find a “ready to use” integration with your feedback platform or use the Birdie API to create feedback records from any source you have available.
1-Authenticate to Birdie API
To use Birdie API you will need a valid Organization ID and a Private API Key, both linked to your Birdie account.
Inside Birdie's platform, click on "Sources" button on the menu:
And get to this session:
Be sure to keep your API key private. All API requests must be made over HTTPS and are authenticated via HTTP Basic Auth.
If you're not seeing this session, make sure to click on the API tab
2-Creating a feedback record
To make your River flow you will need to create an automatic stream of data feeding Birdie. This API allows you to create or update feedback records on demand.
As one of the required Core Fields is a unique Feedback ID, it can be used to avoid duplication and also to allow updated feedback records. Sending a second request with the same Feedback ID will update the existing record in Birdie.
In the feedback list, within your payload, you can send up to 50 feedback records at each request.
Base URL
https://feedback-river.api.services.birdie.ai
Create a Feedback Record in Birdie
Endpoint
POST /api/webhook/create_feedback
Request
curl -X 'POST' \
'https://feedback-river.api.services.birdie.ai/api/webhook/create_feedback' \
-H 'accept: application/json' \
-H 'x-api-key: <YOUR PRIVATE API KEY>' \
-H 'x-organization-id: <YOUR ORGANIZATION_ID>' \
-H 'Content-Type: application/json' \
-d '{
"extraction_name": "Custom Survey Responses",
"data_type": "NPS",
"feedbacks": [
{
"feedback_id": "6fdhgdhfkjkgj",
"text": "You can definitely trust and use it everyday for paying your household bills.",
"posted_at": "2020-01-07 11:18:21",
"title": "Awesome Product",
"rating": 10,
"custom_fields": [
{
"key": "field.key-1",
"type": "field.type-1",
"value": "field.value-1",
"name": "field.name-1"
},
{
"key": "field.key-2",
"type": "field.type-2",
"value": "field.value-2",
"name": "field.name-2"
},
{
"key": "field.key-3",
"type": "field.type-3",
"value": "field.value-3",
"name": "field.name-3"
}
]
}
]
}'
Response
{
"task_id": "4f1362eb-db59-408b-bc17-28948cd7c480"
}
Rate Limit
To keep our API services healthy and provide quality of services to all our users we may rate limit requests in certain extreme usage scenarios. It is very unlikely for you to experience rate limits with normal usage of our API. The most common reasons for you to experience rate limiting are bugs or bulk data requests.
You can send up to 2000 requests at each 60-second interval. Remember that each request may contain a collection of up to 50 feedback records.
If you start receiving 429 HTTP responses, please reduce the frequency of your requests.
HTTP Status codes
These are the possible status codes you may get as a response to your request.
Code | Description |
201 | Indicates that the request was successful and a new resource was created. |
401 | Indicates the API key was invalid. "Not Authorized" |
422 | Indicates the request was invalid. This usually means some of the required parameters were missing. Information about the specific errors will be returned in the response. |
429 | Indicates you exceeded rate limit for requests |
500 | Indicates that we are having trouble on our end. |
Params
These are the Core fields for feedback. Some of them are required and the others are optional.
Name | Description |
feedback_id [string] | a unique identifier for the feedback to avoid duplication as we get updates about it. This is a required field |
text [string] | it is the content of the feedback itself. The comment was published by its author (the user). This is a required field |
posted_at [datetime] | date when the feedback was published by its author |
title [string] | commonly used in Reviews, Support Tickets, and a few other feedback types, it is a summary of the feedback. This is an optional field |
rating [float] | Some score metrics associated with the feedback (NPS, CSAT, CES, Star Rating) |
product_reference [string] | a reference for the target of the feedback. It may be a product name or a product area |
extraction_name [string] | Custom name for this integration. This name will be shown in the Import history |
data_type [string] | Based on the support feedback type list: NPS, CSAT, CES, Support tickets, Reviews |
Custom Fields
Additionally to the Core fields, you can send a collection of Custom Fields. They will become available as filters for feedback exploration and can become very useful for creating segmented analysis.
Examples of Custom Fields would be:
Mobile OS
App Version
Churned user (true/false)
Account ARR
...
Name | Description |
name [string] | Field name. It will be visible to users in the platform |
key [string] | Unique identifier for the key, based on the field name |
type [string] | ALLOWED_TYPES = ["string", "integer", "number", "boolean", "datetime", "array"] |
value [multiple] | Value for the field, following the defined type |
Any more questions? Please call us on chat:
