Buenno API Reference
The Buenno API s organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Authentication
The Buenno API uses API keys to authenticate requests. To send any request to our api, include api-auth-token to the request header.
Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
Get token info
Test that your api-auth-token is valid. Token info includes information of accessible forms.
GET /api/v01/token-info
# Include your api-auth-token to each request
curl --location --request GET 'https://webreport.buenno.fi/api/v01/token-info' \
--header 'api-auth-token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
Response:
{
"api_token":
{
"name": "Example CRM token",
"forms": [
{
"id": 1,
"name": "Example Form 2021",
"company_name": "Example Company Ltd"
}
]
}
}
Errors
The Buenno API uses following HTTP status codes on errors.
| Code | Possible cause |
|---|---|
| 401 | api-auth-token not found or invalid |
| 403 | Action is not allowed to perform right now. |
| 404 | Given id not found or invalid |
| 404 | Method (GET/PUT/POST/PATCH/DELETE) is not allowed |
| 409 | Created item with a given key already exists |
Example of json error response:
{
"error_message": "Whoops! Something went wrong."
}
Invitations
Use following endpoints to invite users to answer question form. Message content to email or SMS is created automatically by Buenno.
Create invitation
Invite customers to answer to a survey. Use either email or phone to specify how user should receive the invitation. Use prefilled parameters (pf_) to fill required questions for the customer. If prefilled field is missing, the corresponding question will be asked from the customer.
POST /api/v01/invitations
curl --location --request POST 'https://webreport.buenno.fi/api/v01/invitations/' \
--header 'api-auth-token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
-d 'phone=00358441234567'
Response
{
"invitation": {
"id": 1,
"email": null,
"phone": "00358441234567",
"first_name": null,
"last_name": null,
"form_id": 1,
"pf_timestamp": null,
"pf_store": null,
"pf_seller_name": null,
"pf_product_category": null,
"pf_target": null,
"pf_gender": null,
"pf_age": null,
"pf_external_id": null,
"invitation_link": "https://buenno.fi/i/0b6a5ed887f3b89acd08",
"scheduled_at": "2020-12-18T00:00:00+00:00",
"sent_at": "2020-12-18T00:00:00+00:00",
"opened_at": "2020-12-19T00:00:00+00:00",
"answered_at": null,
"created_at": "2020-12-18T00:00:00+00:00",
"updated_at": "2020-12-18T00:00:00+00:00"
}
}
Exceptions
Returns 409 if invitation with given identifier exists.
Returns 403 if no active form is present.
Returns 404 if form_id is invalid.
URL Parameters
| Parameter | Description | Type | Mandatory |
|---|---|---|---|
| phone | Phone number to send survey invitation. Phone or Email is mandatory. Phone number should include country code where + is replaced with 00. E.g +358441234567 becomes 00358441234567 | String | - |
| Email to send survey invitation. Phone or Email is mandatory. | String | - | |
| first_name | Customer first name | String | No |
| last_name | Customer last name | String | No |
| pf_timestamp | Time of the customer visit, purchase or interaction (seconds since January 1st, 1970). | Integer | No |
| pf_store | Name of the store where interaction happened | String | No |
| pf_seller_name | Salesperson name | String | No |
| pf_seller_id | Salesperson ID | String | No |
| pf_product_category | Product category | String | No |
| pf_target | Acquisition target | String | No |
| pf_gender | Customer gender | String | No |
| pf_age | Customer age | Integer | No |
| pf_external_id | External user id | String | No |
| preferred_language | Language to use for this invitation, ISO 639‑1 code | String | No |
List invitations
Lists created invitations.
GET /api/v01/invitations
curl --location --request GET 'https://webreport.buenno.fi/api/v01/invitations/' \
--header 'api-auth-token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
Response
{
"invitations": [
{
"id": 1,
"email": null,
"phone": "00358441234567",
"first_name": null,
"last_name": null,
"form_id": 1,
"pf_timestamp": null,
"pf_store": null,
"pf_seller_name": null,
"pf_product_category": null,
"pf_target": null,
"pf_gender": null,
"pf_age": null,
"pf_external_id": null,
"scheduled_at": "2020-12-18T00:00:00+00:00",
"sent_at": "2020-12-18T00:00:00+00:00",
"opened_at": "2020-12-19T00:00:00+00:00",
"answered_at": null,
"created_at": "2020-12-18T00:00:00+00:00",
"updated_at": "2020-12-18T00:00:00+00:00"
}
]
}
URL Parameters
| Parameter | Description | Type | Mandatory |
|---|---|---|---|
| created_after | Invitations created after date | Date time ISO 8601 | No |
| created_before | Invitations created before date | Date time ISO 8601 | No |
| limit | Max number of rows to return, Default = 100, Max = 250 | Integer | No |
| offset | Row number to start from. Default = 0 | Integer | No |
| form_id | Field to identify form in a case when api-auth-token has access to more than one form. If not filled first active survey form will be used. | Integer | No |
Replies
List
Get a list of replies and their answers.
GET /api/v01/replies
curl --location --request GET 'https://webreport.buenno.fi/api/v01/replies' \
--header 'api-auth-token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
-d 'from=2020-12-17T00:00:00+00:00' \
-d 'to=2020-12-19T00:00:00+00:00' \
-d 'limit=1000'
Response
{
"replies": [
{
"id": 1,
"name": "Example Survey 12/2020",
"email": "",
"phone": "00358441234567",
"first_name": null,
"last_name": null,
"pf_timestamp": null,
"pf_store": null,
"pf_seller_name": null,
"pf_seller_id": null,
"pf_product_category": null,
"pf_target": null,
"pf_gender": null,
"pf_age": null,
"pf_external_id": null,
"preferred_language": null,
"question_count": 2,
"score_sum": 125,
"avg_score": 62.5,
"answers": [
{
"question": "Lorem ipsum",
"points": 50,
"answer": "Sed ut perspiciatis, unde omnis iste natus error sit voluptatem accusantium doloremque laudantium.",
"question_id": 1234,
"question_type_id": 1
},
{
"question": "Lorem ipsum 2",
"points": 75,
"answer": null,
"question_id": 1237,
"question_type_id": 1
},
{
"question": "De finibus bonorum et malorum",
"points": 0,
"answer": "qui ratione voluptatem sequi nesciunt, neque porro quisquam est, qui do.",
"question_id": 2345,
"question_type_id": 13
}
],
"updated_at": "2020-12-19T00:00:00Z",
"created_at": "2020-12-18T00:00:00Z"
}
],
"total": "2225",
"limit": "500",
"offset": "0"
}
URL Parameters
| Parameter | Description | Type | Mandatory |
|---|---|---|---|
| from | Answers from date | Date time ISO 8601 | Yes |
| to | Answers to date | Date time ISO 8601 | Yes |
| limit | Max number of answers to return, Default = 500, Max = 1000 | Integer | No |
| offset | Answer number to start from. Default = 0 | Integer | No |
| locale | Locale used in question names | string | No |
Server is in UTC time. If you want to use local time for api calls use the +00:00 part to provide the offset to UTC.
Each reply contains question_count, score_sum, and avg_score, these 3 belong together:
| Name | Meaning |
|---|---|
| question_count | The amount of main questions that have points. |
| score_sum | The sum of all those main questions' points. |
| avg_score | The average score for this reply; score_sum / question_count. |
Each question includes a question_id and question_type_id. question_id is a unique identifier for that question while question_type_id indicates which kind of question it is. The possible question types are:
| question_type_id | Question type |
|---|---|
| 1 | Main question |
| 2 | Other question |
| 4 | Admin |
| 5 | Offered product |
| 6 | Shopping goal |
| 7 | Answerer |
| 8 | Age |
| 9 | Gender |
| 10 | Seller's name |
| 11 | Visit date |
| 12 | Visit time |
| 13 | NPS |
| 48 | Product category |
| 49 | Seller's ID |