Beamer API API Reference
These are the developer docs for the Beamer API.
You can find your API key under Settings > API .
For more information on how to use Beamer in your site, check out our web Documentation. For any other doubts you may have about how Beamer works, check out our Help Center.
Rate limit
Our API currently enforces a rate limit of 30 requests per second for paid accounts, in addition to a monthly limit of 1,000 requests in total for the Free plan and 20,000 for Startup. If you need an extension, please contact us on our Support chat.API Endpoint
https://api.getbeamer.com/v0Contact: info@getbeamer.com
Schemes: https
Version: 0.1.0
Authentication
Beamer-Api-Key
Feed
Operations on your feed
Get the URL for your feed
Use /url to retrieve the URL for your feed.
Retrieve the URL for your feed in a specific language. The language must follow the ISO-639 two-letter code format. [Only available on the Startup plan (and up)]
Whether to apply URL filtering to the feed. [Only available on the Pro plan (and up)]
Retrieve posts with a matching segmentation filter. [Only available on the Pro plan (and up)]
Only retrieve posts that match this segmentation filter. [Only available on the Pro plan (and up)]
First name of the user viewing the feed (for Analytics).
Last name of the user viewing the feed (for Analytics).
Email of the user viewing the feed (for Analytics).
ID of the user viewing the feed (for Analytics).
Request authenticated. The request returns a JSON object containing the URL for your standalone feed.
Either no API key was provided or the provided API key is invalid
Not allowed to access this resource.
This method is not allowed on this resource.
You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.
Something went wrong on our side.
Response Content-Types: application/json
Response Example (200 OK)
{
"url": "https://app.getbeamer.com/beamer/"
}
Ping
Ping the Beamer API
Ping the API
Use /ping to check you are correctly authenticating your requests with your API key.
Request authenticated. The request returns a JSON object containing the name of your product on Beamer.
Either no API key was provided or the provided API key is invalid
Not allowed to access this resource.
This method is not allowed on this resource.
You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.
Something went wrong on our side.
Response Content-Types: application/json
Response Example (200 OK)
{
"name": "Beamer"
}
Posts
Operations on your posts
Get existing posts
Use the GET method to query and retrieve existing posts from your account.
Retrieve posts with a matching segmentation filter. [Only available on the Pro plan (and up)]
Only retrieve posts that match this segmentation filter. [Only available on the Pro plan (and up)]
If URL segmentation is enabled, include posts with a matching segmentation URL. [Only available on the Pro plan (and up)]
Retrieve posts published after this date. The date must follow the ISO-8601 format.
Retrieve posts published before this date. The date must follow the ISO-8601 format.
Retrieve posts with translations in this language. The language must follow the ISO-639 two-letter code format.
Retrieve posts with this category.
Retrieve only published (or draft) posts. If unspecified, both types of posts will be retrieved.
Retrieve only archived (or not archived) posts. If unspecified, both types of posts will be retrieved.
Retrieve only expired (or not expired) posts; posts without an expiration date are considered not expired. If unspecified, both types of posts will be retrieved. [Only available on the Startup plan (and up)]
If true, single-user posts will be retrieved when matching the userId parameter. If false (or if no userId is provided), single-user posts will not be retrieved. [Only available on the Enterprise plan]
First name of the user viewing these posts (for Analytics).
Last name of the user viewing these posts (for Analytics).
Email of the user viewing these posts (for Analytics).
ID of the user viewing these posts (for Analytics).
Whether to save views for the posts retrieved (for Analytics). If unspecified, views are saved.
Retrieve this many posts (at most). The max number of posts returned is 10.
Combined with the value of 'maxResults' (or its default value), paginate the retrieval of posts.
Posts retrieved.
Some parameter is missing or doesn't follow the API specification.
Either no API key was provided or the provided API key is invalid
Not allowed to access this resource.
This method is not allowed on this resource.
You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.
Something went wrong on our side.
Response Content-Types: application/json
Response Example (200 OK)
[
{
"id": "123",
"date": "2018-12-31T00:00:00Z",
"dueDate": "2019-12-31T00:00:00Z",
"published": "true",
"pinned": "false",
"showInWidget": "true",
"showInStandalone": "true",
"category": "new",
"boostedAnnouncement": "snippet",
"translations": [
{
"title": "Title of the post.",
"content": "Content of the post.",
"contentHtml": "<p>Content of the post.</p>",
"language": "EN",
"category": "Category",
"linkUrl": "https://www.getbeamer.com/",
"linkText": "Click here!",
"images": [
"https://app.getbeamer.com/pictures?id=123"
]
}
],
"filter": "admins",
"filterUrl": "https://app.getbeamer.com/*",
"autoOpen": "false",
"editionDate": "2018-12-31T10:00:00Z",
"feedbackEnabled": "true",
"reactionsEnabled": "true"
}
]
Create a new post
Use the POST method to create a new post on your account.
Send a JSON object in the body of the request containing the details of the post to create.
All the main content fields of the post (such as title and content) are arrays of strings, in order to allow the creation of several translations simultaneously.
If you are creating a post with several translations, keep the same order when completing all of the translation-specific fields ( title, content, language, link text and link URL).
The first translation will be created from the first language, the first title, the first content, the first link text, and the first link URL (if any).
Likewise, the second translation will be created from the second title, the second content, and so on.
Multiple translations are only available on the Startup plan (and up).
Request Content-Types: application/json
Request Example
{
"title": [
"Title of your post"
],
"content": [
"Content of your post"
],
"category": "new",
"publish": true,
"archive": false,
"pinned": "false",
"showInWidget": "true",
"showInStandalone": "true",
"boostedAnnouncement": "snippet",
"linkUrl": [
"https://www.getbeamer.com/"
],
"linkText": [
"https://www.getbeamer.com/"
],
"linksInNewWindow": true,
"date": "2018-12-31T00:00:00",
"dueDate": "2019-12-31T00:00:00Z",
"language": [
"EN"
],
"filter": "admins",
"filterUserId": "1234",
"filterUrl": "https://www.getbeamer.com/*",
"enableFeedback": true,
"enableReactions": true,
"enableSocialShare": true,
"autoOpen": true,
"sendPushNotification": true,
"userEmail": "example@getbeamer.com"
}
Post created.
The request returns a JSON object containing the details of the post.
Some parameter is missing or doesn't follow the API specification.
Either no API key was provided or the provided API key is invalid
Not allowed to access this resource.
This method is not allowed on this resource.
You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.
Something went wrong on our side.
Response Content-Types: application/json
Response Example (201 Created)
{
"id": "123",
"date": "2018-12-31T00:00:00Z",
"dueDate": "2019-12-31T00:00:00Z",
"published": "true",
"pinned": "false",
"showInWidget": "true",
"showInStandalone": "true",
"category": "new",
"boostedAnnouncement": "snippet",
"translations": [
{
"title": "Title of the post.",
"content": "Content of the post.",
"contentHtml": "<p>Content of the post.</p>",
"language": "EN",
"category": "Category",
"linkUrl": "https://www.getbeamer.com/",
"linkText": "Click here!",
"images": [
"https://app.getbeamer.com/pictures?id=123"
]
}
],
"filter": "admins",
"filterUrl": "https://app.getbeamer.com/*",
"autoOpen": "false",
"editionDate": "2018-12-31T10:00:00Z",
"feedbackEnabled": "true",
"reactionsEnabled": "true"
}
Count existing posts
Use the GET method to count existing posts from your account.
Count posts with a matching segmentation filter. [Only available on the Pro plan (and up)]
Only count posts that match this segmentation filter. [Only available on the Pro plan (and up)]
If URL segmentation is enabled, include posts with a matching segmentation URL. [Only available on the Pro plan (and up)]
Count posts published after this date. The date must follow the ISO-8601 format.
Count posts published before this date. The date must follow the ISO-8601 format.
Count posts with translations in this language. The language must follow the ISO-639 two-letter code format. [Only available on the Startup plan (and up)]
Count posts with this category.
Count only published (or draft) posts. If unspecified, both types of posts will be counted.
Count only archived (or not archived) posts. If unspecified, both types of posts will be counted.
Count only expired (or not expired) posts; posts without an expiration date are considered not expired. If unspecified, both types of posts will be counted.
If true, single-user posts will be counted when matching the userId parameter. If false (or if no userId is provided), single-user posts will not be counted. [Only available on the Enterprise plan]
For using with the filterByUserId parameter only.
Posts count.
Some parameter is missing or doesn't follow the API specification.
Either no API key was provided or the provided API key is invalid
Not allowed to access this resource.
This method is not allowed on this resource.
You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.
Something went wrong on our side.
Response Content-Types: application/json
Response Example (200 OK)
{
"count": 99
}
Get post by ID
Returns a post.
ID of the post to retrieve.
First name of the user viewing these posts (for Analytics).
Last name of the user viewing these posts (for Analytics).
Email of the user viewing these posts (for Analytics).
ID of the user viewing these posts (for Analytics).
ID of the user viewing these posts (for Analytics).
Post retrieved.
Some parameter is missing or doesn't follow the API specification.
Either no API key was provided or the provided API key is invalid
Not allowed to access this resource.
Post not found.
This method is not allowed on this resource.
You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.
Something went wrong on our side.
Response Content-Types: application/json
Response Example (200 OK)
{
"id": "123",
"date": "2018-12-31T00:00:00Z",
"dueDate": "2019-12-31T00:00:00Z",
"published": "true",
"pinned": "false",
"showInWidget": "true",
"showInStandalone": "true",
"category": "new",
"boostedAnnouncement": "snippet",
"translations": [
{
"title": "Title of the post.",
"content": "Content of the post.",
"contentHtml": "<p>Content of the post.</p>",
"language": "EN",
"category": "Category",
"linkUrl": "https://www.getbeamer.com/",
"linkText": "Click here!",
"images": [
"https://app.getbeamer.com/pictures?id=123"
]
}
],
"filter": "admins",
"filterUrl": "https://app.getbeamer.com/*",
"autoOpen": "false",
"editionDate": "2018-12-31T10:00:00Z",
"feedbackEnabled": "true",
"reactionsEnabled": "true"
}
Update an existing post
Updates the post with the existing ID.
JSON object containing the details of the post to update.
ID of the post to update.
Request Content-Types: application/json
Request Example
{
"title": [
"Title of your post"
],
"content": [
"Content of your post"
],
"category": "new",
"publish": true,
"archive": false,
"pinned": "false",
"showInWidget": "true",
"showInStandalone": "true",
"boostedAnnouncement": "snippet",
"linkUrl": [
"https://www.getbeamer.com/"
],
"linkText": [
"https://www.getbeamer.com/"
],
"linksInNewWindow": true,
"date": "2018-12-31T00:00:00",
"dueDate": "2019-12-31T00:00:00Z",
"language": [
"EN"
],
"filter": "admins",
"filterUserId": "1234",
"filterUrl": "https://www.getbeamer.com/*",
"enableFeedback": true,
"enableReactions": true,
"enableSocialShare": true,
"autoOpen": true,
"sendPushNotification": true,
"userEmail": "example@getbeamer.com"
}
Post updated.
Some parameter is missing or doesn't follow the API specification.
Either no API key was provided or the provided API key is invalid
Not allowed to access this resource.
Post not found.
This method is not allowed on this resource.
You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.
Something went wrong on our side.
Response Content-Types: application/json
Response Example (200 OK)
{
"id": "123",
"date": "2018-12-31T00:00:00Z",
"dueDate": "2019-12-31T00:00:00Z",
"published": "true",
"pinned": "false",
"showInWidget": "true",
"showInStandalone": "true",
"category": "new",
"boostedAnnouncement": "snippet",
"translations": [
{
"title": "Title of the post.",
"content": "Content of the post.",
"contentHtml": "<p>Content of the post.</p>",
"language": "EN",
"category": "Category",
"linkUrl": "https://www.getbeamer.com/",
"linkText": "Click here!",
"images": [
"https://app.getbeamer.com/pictures?id=123"
]
}
],
"filter": "admins",
"filterUrl": "https://app.getbeamer.com/*",
"autoOpen": "false",
"editionDate": "2018-12-31T10:00:00Z",
"feedbackEnabled": "true",
"reactionsEnabled": "true"
}
Deletes a post
Deletes the post with the given ID.
ID of the post to delete.
Post deleted.
Some parameter is missing or doesn't follow the API specification.
Either no API key was provided or the provided API key is invalid
Not allowed to access this resource.
Post not found.
This method is not allowed on this resource.
You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.
Something went wrong on our side.
Get unread posts
Use the GET method to query and retrieve unread posts from your account. Only posts that are visible in your feed are retrieved by this endpoint (draft, deleted, archived, expired and scheduled posts are not retrieved).
Retrieve posts with a matching segmentation filter. [Only available on the Pro plan (and up)]
Only retrieve posts that match this segmentation filter. [Only available on the Pro plan (and up)]
If URL segmentation is enabled, include posts with a matching segmentation URL. [Only available on the Pro plan (and up)]
Retrieve posts published after this date. The date must follow the ISO-8601 format.
Retrieve posts with translations in this language. The language must follow the ISO-639 two-letter code format. [Only available on the Startup plan (and up)]
Retrieve posts with this category.
First name of the user viewing these posts (for Analytics).
Last name of the user viewing these posts (for Analytics).
Email of the user viewing these posts (for Analytics).
ID of the user viewing these posts (for Analytics). If single-user posts are enabled, posts with a matching userId will be retrieved. [Only available on the Enterprise plan] If multi-device synchronization is enabled, the dateFrom parameter will be overridden by this user's last date of viewing your feed - if any. dateFrom can be omitted in this case. [Only available on the Pro plan (and up)]
Retrieve this many posts (at most). The max number of posts returned is 10.
Combined with the value of 'maxResults' (or its default value), paginate the retrieval of posts.
Posts retrieved.
Some parameter is missing or doesn't follow the API specification.
Either no API key was provided or the provided API key is invalid
Not allowed to access this resource.
This method is not allowed on this resource.
You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.
Something went wrong on our side.
Response Content-Types: application/json
Response Example (200 OK)
[
{
"id": "123",
"date": "2018-12-31T00:00:00Z",
"dueDate": "2019-12-31T00:00:00Z",
"published": "true",
"pinned": "false",
"showInWidget": "true",
"showInStandalone": "true",
"category": "new",
"boostedAnnouncement": "snippet",
"translations": [
{
"title": "Title of the post.",
"content": "Content of the post.",
"contentHtml": "<p>Content of the post.</p>",
"language": "EN",
"category": "Category",
"linkUrl": "https://www.getbeamer.com/",
"linkText": "Click here!",
"images": [
"https://app.getbeamer.com/pictures?id=123"
]
}
],
"filter": "admins",
"filterUrl": "https://app.getbeamer.com/*",
"autoOpen": "false",
"editionDate": "2018-12-31T10:00:00Z",
"feedbackEnabled": "true",
"reactionsEnabled": "true"
}
]
Count unread posts
Use the GET method to count unread posts from your account. Only posts that are visible in your feed are retrieved by this endpoint (draft, deleted, archived, expired and scheduled posts are not counted).
Count posts with a matching segmentation filter. [Only available on the Pro plan (and up)]
Only count posts that match this segmentation filter. [Only available on the Pro plan (and up)]
If URL segmentation is enabled, include posts with a matching segmentation URL. [Only available on the Pro plan (and up)]
Count posts published after this date. The date must follow the ISO-8601 format.
Count posts with translations in this language. The language must follow the ISO-639 two-letter code format.
Count posts with this category.
First name of the user viewing these posts (for Analytics).
Last name of the user viewing these posts (for Analytics).
Email of the user viewing these posts (for Analytics).
ID of the user viewing these posts (for Analytics). If single-user posts are enabled, posts with a matching userId will be counted. [Only available on the Enterprise plan] If multi-device synchronization is enabled, the dateFrom parameter will be overridden by this user's last date of viewing your feed - if any. dateFrom can be omitted in this case. [Only available on the Pro plan (and up)]
Posts count.
Some parameter is missing or doesn't follow the API specification.
Either no API key was provided or the provided API key is invalid
Not allowed to access this resource.
This method is not allowed on this resource.
You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.
Something went wrong on our side.
Response Content-Types: application/json
Response Example (200 OK)
{
"count": 99,
"url": "https://app.getbeamer.com/news?app_id=mZXqptmd65",
"popupUrl": "https://app.getbeamer.com/popup?app_id=mZXqptmd65"
}
Feature requests
Operations on your feature requests [Beta]
Get existing feature requests
Use the GET method to query and retrieve existing feature requests from your account.
Retrieve feature requests with a matching segmentation filter. [Only available on the Pro plan (and up)]
Retrieve feature requests created after this date. The date must follow the ISO-8601 format.
Retrieve feature requests created before this date. The date must follow the ISO-8601 format.
Retrieve feature requests with translations in this language. The language must follow the ISO-639 two-letter code format.
Retrieve feature requests with this category.
Retrieve feature requests with this status.
Retrieve only visible (or not visible) feature requests. If unspecified, both types of feature requests will be retrieved.
Retrieve feature requests with title or content that contain this text.
Retrieve this many feature requests (at most). The max number of posts returned is 10.
Combined with the value of 'maxResults' (or its default value), paginate the retrieval of feature requests.
Feature requests retrieved.
Some parameter is missing or doesn't follow the API specification.
Either no API key was provided or the provided API key is invalid
Not allowed to access this resource.
This method is not allowed on this resource.
You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.
Something went wrong on our side.
Response Content-Types: application/json
Response Example (200 OK)
[
{
"id": "123",
"date": "2018-12-31T00:00:00Z",
"visible": "true",
"category": "bug",
"status": "under_review",
"translations": [
{
"title": "Title of the feature request.",
"content": "Content of the feature request.",
"contentHtml": "<p>Content of the feature request.</p>",
"language": "EN",
"permalink": "https://app.getbeamer.com/beamer/requests/en/example-feature-request",
"images": [
"https://app.getbeamer.com/pictures?id=123"
]
}
],
"votesCount": 10,
"commentsCount": "10",
"notes": "Internal note",
"filters": "Feature request",
"internalUserEmail": "janedoe@getbeamer.com",
"internalUserFirstname": "Jane",
"internalUserLastname": "Doe",
"userId": "1010",
"userEmail": "johndoe@getbeamer.com",
"userFirstname": "John",
"userLastname": "Doe",
"userCustomAttributes": {
"Organization": "Example",
"age": 33
}
}
]
Create a new feature request
Use the POST method to create a new feature request on your account.
Send a JSON object in the body of the request containing the details of the feature request to create.
All the main content fields of the feature request (such as title and content) are arrays of strings, in order to allow the creation of several translations simultaneously.
If you are creating a feature request with several translations, keep the same order when completing all of the translation-specific fields ( title, content and language).
The first translation will be created from the first language, the first title and the first content.
Likewise, the second translation will be created from the second title, the second content, and so on.
Multiple translations are only available on the Startup plan (and up).
Request Content-Types: application/json
Request Example
{
"title": [
"Title of your feature request"
],
"content": [
"Content of your feature request"
],
"visible": true,
"category": "bug",
"status": "under_review",
"notes": "Internal note",
"filters": "Feature request",
"votesCount": 10,
"date": "2018-12-31T00:00:00",
"internalUserEmail": "janedoe@getbeamer.com",
"userId": "1010",
"userEmail": "johndoe@getbeamer.com",
"userFirstname": "John",
"userLastname": "Doe"
}
Feature request created.
The request returns a JSON object containing the details of the feature request.
Some parameter is missing or doesn't follow the API specification.
Either no API key was provided or the provided API key is invalid
Not allowed to access this resource.
This method is not allowed on this resource.
You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.
Something went wrong on our side.
Response Content-Types: application/json
Response Example (201 Created)
{
"id": "123",
"date": "2018-12-31T00:00:00Z",
"visible": "true",
"category": "bug",
"status": "under_review",
"translations": [
{
"title": "Title of the feature request.",
"content": "Content of the feature request.",
"contentHtml": "<p>Content of the feature request.</p>",
"language": "EN",
"permalink": "https://app.getbeamer.com/beamer/requests/en/example-feature-request",
"images": [
"https://app.getbeamer.com/pictures?id=123"
]
}
],
"votesCount": 10,
"commentsCount": "10",
"notes": "Internal note",
"filters": "Feature request",
"internalUserEmail": "janedoe@getbeamer.com",
"internalUserFirstname": "Jane",
"internalUserLastname": "Doe",
"userId": "1010",
"userEmail": "johndoe@getbeamer.com",
"userFirstname": "John",
"userLastname": "Doe",
"userCustomAttributes": {
"Organization": "Example",
"age": 33
}
}
Users
Operations on your users [Only available on the Enterprise plan]
Get users from your Analytics
Use the GET method to query and retrieve users from your account's Analytics.
ID of the user (as defined in the embedded script's user_id parameter).
Beamer generated ID for the user.
Email of the user.
Sort users by this attribute (in ascending order). This parameter can contain any of the user attributes returned by this endpoint, including custom attributes.
Adding a hyphen ('-') before the attribute will sort the results in descending order. For example, sort=lastSeen will first retrieve users with the oldest 'last seen' date, while sort=-lastSeen will retrieve users that were 'last seen' most recently.
By default, users are sorted by firstSeen (oldest first).
Retrieve this many users (at most). The default number of users returned is 10, and the maximum is 100.
Combined with the value of 'maxResults' (or its default value), paginate the retrieval of users.
Users retrieved.
Some parameter is missing or doesn't follow the API specification.
Either no API key was provided or the provided API key is invalid
Not allowed to access this resource.
This method is not allowed on this resource.
You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.
Something went wrong on our side.
Response Content-Types: application/json
Response Example (200 OK)
[
{
"beamerId": "12345-67890",
"userId": "1234",
"userEmail": "example@getbeamer.com",
"userFirstName": "Example",
"userLastName": "Beamer",
"language": "EN",
"filter": "example-filter",
"firstSeen": "2018-12-31T10:00:00Z",
"lastSeen": "2019-01-01T10:00:00Z",
"ip": "127.0.0.1",
"browser": "Chrome",
"os": "Mac OS",
"city": "Barcelona",
"country": "Spain",
"latitude": "0.0",
"longitude": "0.0"
}
]
Create a new user
Use the POST method to create a new user on your account's Analytics.
Send a JSON object in the body of the request containing the details of the user to create.
Request Content-Types: application/json
Request Example
{
"userId": "1234",
"userEmail": "example@getbeamer.com",
"userFirstName": "Example",
"userLastName": "Beamer",
"filter": "role-admin;paid-user",
"language": "EN",
"ip": "127.0.0.1",
"browser": "Chrome",
"os": "Mac OS",
"city": "Barcelona",
"country": "Spain",
"latitude": "0.0",
"longitude": "0.0"
}
User created.
The request returns a JSON object containing the details of the user.
Some parameter is missing or doesn't follow the API specification.
Either no API key was provided or the provided API key is invalid
Not allowed to access this resource.
This method is not allowed on this resource.
You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.
Something went wrong on our side.
Response Content-Types: application/json
Response Example (201 Created)
{
"beamerId": "12345-67890",
"userId": "1234",
"userEmail": "example@getbeamer.com",
"userFirstName": "Example",
"userLastName": "Beamer",
"language": "EN",
"filter": "example-filter",
"firstSeen": "2018-12-31T10:00:00Z",
"lastSeen": "2019-01-01T10:00:00Z",
"ip": "127.0.0.1",
"browser": "Chrome",
"os": "Mac OS",
"city": "Barcelona",
"country": "Spain",
"latitude": "0.0",
"longitude": "0.0"
}
Update matching users
Updates existing users.
JSON object containing the details to update for users that match the query.
ID of the user to update.
Beamer generated ID of the user to update.
Email of the user to update.
Request Content-Types: application/json
Request Example
{
"userId": "1234",
"userEmail": "example@getbeamer.com",
"userFirstName": "Example",
"userLastName": "Beamer",
"filter": "role-admin;paid-user",
"language": "EN",
"ip": "127.0.0.1",
"browser": "Chrome",
"os": "Mac OS",
"city": "Barcelona",
"country": "Spain",
"latitude": "0.0",
"longitude": "0.0"
}
Users updated.
Some parameter is missing or doesn't follow the API specification.
Either no API key was provided or the provided API key is invalid
Not allowed to access this resource.
This method is not allowed on this resource.
You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.
Something went wrong on our side.
Response Content-Types: application/json
Response Example (200 OK)
[
{
"beamerId": "12345-67890",
"userId": "1234",
"userEmail": "example@getbeamer.com",
"userFirstName": "Example",
"userLastName": "Beamer",
"language": "EN",
"filter": "example-filter",
"firstSeen": "2018-12-31T10:00:00Z",
"lastSeen": "2019-01-01T10:00:00Z",
"ip": "127.0.0.1",
"browser": "Chrome",
"os": "Mac OS",
"city": "Barcelona",
"country": "Spain",
"latitude": "0.0",
"longitude": "0.0"
}
]
Deletes users
Deletes users that match the given identifiers. At least one of userId, beamerId or userEmail are required.
WARNING: This operation deletes your user's information permanently from Beamer's records.
ID of the user to delete (as defined in the embedded script's user_id parameter). Multiple IDs can be passed in, separated by semicolons (;).
Beamer generated ID of the user to delete. Multiple IDs can be passed in, separated by semicolons (;).
Email of the user to delete. Multiple emails can be passed in, separated by semicolons (;).
Users deleted.
Some parameter is missing or doesn't follow the API specification.
Either no API key was provided or the provided API key is invalid
Not allowed to access this resource.
This method is not allowed on this resource.
You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.
Something went wrong on our side.
Response Content-Types: application/json
Response Example (200 OK)
{
"deleted": 1
}
NPS
Operations on your NPS responses
Get NPS responses
Use the GET method to query and retrieve NPS responses from your account.
Retrieve NPS responses sent after this date. The date must follow the ISO-8601 format.
Retrieve NPS responses sent before this date. The date must follow the ISO-8601 format.
Retrieve NPS responses with a score of this value or greater.
Retrieve NPS responses with a score of this value or less.
Retrieve NPS responses with feedback that contains this text. The search value can also match the name of the user.
Retrieve this many posts (at most). The default number of responses returned is 10, and the maximum is 100.
Combined with the value of 'maxResults' (or its default value), paginate the retrieval of NPS response.
NPS responses retrieved.
Some parameter is missing or doesn't follow the API specification.
Either no API key was provided or the provided API key is invalid
Not allowed to access this resource.
This method is not allowed on this resource.
You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.
Something went wrong on our side.
Response Content-Types: application/json
Response Example (200 OK)
[
{
"date": "2018-12-31T00:00:00Z",
"score": 10,
"feedback": "Love this app!",
"userId": "1234",
"userEmail": "example@getbeamer.com",
"userFirstName": "Jane",
"userLastName": "Doe",
"refUrl": "https://app.getbeamer.com/home",
"url": "https://app.getbeamer.com/nps#feedback?userId=1234"
}
]
Count NPS responses
Use the GET method to count NPS responses from your account.
Retrieve NPS responses sent after this date. The date must follow the ISO-8601 format.
Retrieve NPS responses sent before this date. The date must follow the ISO-8601 format.
Retrieve NPS responses with a score of this value or greater.
Retrieve NPS responses with a score of this value or less.
Retrieve NPS responses with feedback that contains this text. The search value can also match the name of the user.
NPS responses count.
Some parameter is missing or doesn't follow the API specification.
Either no API key was provided or the provided API key is invalid
Not allowed to access this resource.
This method is not allowed on this resource.
You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.
Something went wrong on our side.
Response Content-Types: application/json
Response Example (200 OK)
{
"count": 99
}
Check if a user should see the NPS prompt
Use the GET method to check if a certain user meets the conditions to see the NPS prompt.
ID of the user (as defined in the embedded script's user_id parameter).
Beamer generated ID for the user.
Email of the user.
First name of the user.
Last name of the user.
Segmentation filters applied to this user.
Current URL (where the user is at now).
Creation/signup date for this user. The date must follow the ISO-8601 format.
Language of the user.
Whether this user is coming from a mobile device. If unspecified, it will be considered false.
Only applicable if using the userId parameter. If true, Beamer will consider different userIds strictly as different users - even if the userIds are associated to the same browser or device. If unspecified, it will be considered false.
Whether the NPS prompt should be shown for this user.
Some parameter is missing or doesn't follow the API specification.
Either no API key was provided or the provided API key is invalid
Not allowed to access this resource.
This method is not allowed on this resource.
You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.
Something went wrong on our side.
Response Content-Types: application/json
Response Example (200 OK)
{
"shouldShow": true
}
Privacy
Deletes user data
Deletes all data related to the specified user, including all feedback (comments, reactions, NPS) and analytics (views, clicks, etc.). At least one of userId, beamerId or userEmail are required.
WARNING: This operation deletes your user's information permanently from Beamer's records. Use only when necessary.
ID of the user to delete (as defined in the embedded script's user_id parameter).
Beamer generated ID of the user to delete. Multiple IDs can be passed in, separated by semicolons (;).
Email of the user to delete. Multiple emails can be passed in, separated by semicolons (;).
Users deleted.
Some parameter is missing or doesn't follow the API specification.
Either no API key was provided or the provided API key is invalid
Not allowed to access this resource.
This method is not allowed on this resource.
You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.
Something went wrong on our side.
Response Content-Types: application/json
Response Example (200 OK)
{
"deleted": 1
}
Schema Definitions
Category: string
Category of the post. Multiple categories can be passed in, separated by semicolons (;). Basic categories include 'new', 'improvement', 'fix', 'comingsoon', 'announcement' and 'other'; other categories may not be available on the Free plan.
NPS: object
- date: string
Creation date of this response in ISO-8601 format.
- score: integer
Score for this response.
- feedback: string
Feedback text for this response.
- userId: string
ID of the user that sent this response.
- userEmail: string
Email of the user that sent this response.
- userFirstName: string
First name of the user that sent this response.
- userLastName: string
Last name of the user that sent this response.
- refUrl: string
URL from where the user sent this response.
- url: string
URL for this response in your NPS dashboard.
Example
{
"date": "2018-12-31T00:00:00Z",
"score": 10,
"feedback": "Love this app!",
"userId": "1234",
"userEmail": "example@getbeamer.com",
"userFirstName": "Jane",
"userLastName": "Doe",
"refUrl": "https://app.getbeamer.com/home",
"url": "https://app.getbeamer.com/nps#feedback?userId=1234"
}
Post: object
- id: integer (int64)
Unique identifier of this post.
- date: string
Publication date of this post in ISO-8601 format.
- dueDate: string
Expiration date of this post in ISO-8601 format.
- published: boolean
Whether this post is published or a draft.
- pinned: boolean
Whether this post is pinned to the top of the feed.
- showInWidget: boolean
Whether this post shows up in the embedded feed.
- showInStandalone: boolean
Whether this post shows up in the standalone feed.
- category: Category
- boostedAnnouncement: string
Type of boosted announcement to set for this post.
- translations: Translation
Translation - filter: string
Segmentation filter for this post.
- filterUrl: string
Segmentation URL for this post.
- autoOpen: boolean
Whether this post automatically opens Beamer's sidebar the first time the user gets it. [Deprecated]
- editionDate: string
Date of the last edition made on this post in ISO-8601 format.
- feedbackEnabled: boolean
Whether this user feedback is enabled for this post.
- reactionsEnabled: boolean
Whether this user reactions are enabled for this post.
Example
{
"id": "123",
"date": "2018-12-31T00:00:00Z",
"dueDate": "2019-12-31T00:00:00Z",
"published": "true",
"pinned": "false",
"showInWidget": "true",
"showInStandalone": "true",
"category": "new",
"boostedAnnouncement": "snippet",
"translations": [
{
"title": "Title of the post.",
"content": "Content of the post.",
"contentHtml": "<p>Content of the post.</p>",
"language": "EN",
"category": "Category",
"linkUrl": "https://www.getbeamer.com/",
"linkText": "Click here!",
"images": [
"https://app.getbeamer.com/pictures?id=123"
]
}
],
"filter": "admins",
"filterUrl": "https://app.getbeamer.com/*",
"autoOpen": "false",
"editionDate": "2018-12-31T10:00:00Z",
"feedbackEnabled": "true",
"reactionsEnabled": "true"
}
PostCreation: object
- title: string[]
Title of the post.
string - content: string[]
Content of the post.
string - category: Category
- publish: boolean
Whether to publish this post or save it as a draft.
- archive: boolean
Whether to archive this post or not.
- pinned: boolean
Whether this post should be pinned to the top of the feed. [Only available on the Startup plan (and up)]
- showInWidget: boolean
Whether this post should show up in the embedded feed.
- showInStandalone: boolean
Whether this post should show up in the standalone feed.
- boostedAnnouncement: string top-bar, popup, snippet, tooltip
Type of boosted announcement to set for this post. [Only available with the Boosted Announcements add-on]
- linkUrl: string[]
The URL where users will be redirected to if they click the header of the post or the link shown at the bottom of it.
string - linkText: string[]
The text shown in the link ("linkUrl") of this post.
string - linksInNewWindow: boolean
Whether to open links in a new window/tab (true) or in the same window/tab (false) for this post.
- date: string
Publication date for this post in ISO-8601 format. [Future dates / post scheduling are only available on the Startup plan (and up)]
- dueDate: string
Expiration date for this post in ISO-8601 format. [Only available on the Startup plan (and up)]
- language: string[]
Language of this translation (in ISO-639 two-letter code format). [Only available on the Startup plan (and up)]
string - filter: string
Segmentation filter (or filters) for this post. [Only available on the Pro plan (and up)]
- filterUserId: string
User ID to apply as a filter. This post will only be shown to users that have the same ' user_id' parameter in the embedded script. Multiple IDs can be passed in, separated by semicolons (;). [Only available on the Enterprise plan]
- filterUrl: string
URL where this post will be shown. If the embedded feed is opened in any URL other than this, the post will not be shown. An asterisk ( ) can be used as a wildcard. Multiple URLs can be passed in, separated by semicolons (;). *[Only available on the Pro plan (and up)]**
- enableFeedback: boolean
Whether to enable or disable user feedback for this post [Only available on the Pro plan (and up)]
- enableReactions: boolean
Whether to enable or disable user reactions for this post [Only available on the Pro plan (and up)]
- enableSocialShare: boolean
Enable this to show options for your users to share this post on social media.
- autoOpen: boolean
Enable this to automatically open Beamer's sidebar the first time the user gets this post [Only available on the Startup plan (and up)] [Deprecated]
- sendPushNotification: boolean
Enable this to send a web push notification for this post to all your subscribed users. [Only available on the Pro plan (and up)]
- userEmail: string
Email of the user in your account creating this post.
Example
{
"title": [
"Title of your post"
],
"content": [
"Content of your post"
],
"category": "new",
"publish": true,
"archive": false,
"pinned": "false",
"showInWidget": "true",
"showInStandalone": "true",
"boostedAnnouncement": "snippet",
"linkUrl": [
"https://www.getbeamer.com/"
],
"linkText": [
"https://www.getbeamer.com/"
],
"linksInNewWindow": true,
"date": "2018-12-31T00:00:00",
"dueDate": "2019-12-31T00:00:00Z",
"language": [
"EN"
],
"filter": "admins",
"filterUserId": "1234",
"filterUrl": "https://www.getbeamer.com/*",
"enableFeedback": true,
"enableReactions": true,
"enableSocialShare": true,
"autoOpen": true,
"sendPushNotification": true,
"userEmail": "example@getbeamer.com"
}
Translation: object
- title: string
Title of the post.
- content: string
Content of the post (plain text).
- contentHtml: string
Content of the post (original HTML format).
- language: string
Language of this post (in ISO-639 two-letter code format).
- category: string
Custom category of this post.
- linkUrl: string
The URL where users will be redirected to if they click the header of the post or the link shown at the bottom of it.
- linkText: string
The text shown in the link ("linkUrl") of this post.
- images: string[]
URLs of the images embedded in this post.
string
Example
{
"title": "Title of the post.",
"content": "Content of the post.",
"contentHtml": "<p>Content of the post.</p>",
"language": "EN",
"category": "Category",
"linkUrl": "https://www.getbeamer.com/",
"linkText": "Click here!",
"images": [
"https://app.getbeamer.com/pictures?id=123"
]
}
FeatureRequest: object
- id: integer (int64)
Unique identifier of this post.
- date: string
Publication date of this post in ISO-8601 format.
- visible: boolean
Whether this feature required is visible or not.
- category: string
Category for this feature request.
- status: string
Status for this feature request.
- translations: FeatureRequestTranslation
FeatureRequestTranslation - votesCount: integer
Number of votes for this feature request.
- commentsCount: integer
Number of comments for this feature request.
- notes: string
Notes for this feature request.
- filters: string
Segmentation filters for this feature request.
- internalUserEmail: string
Email of the user in your account who created this feature request (if created by a team member).
- internalUserFirstname: string
First name of the user in your account who created this feature request (if created by a team member).
- internalUserLastname: string
Last name of the user in your account who created this feature request (if created by a team member).
- userId: string
ID of the end user who created this feature request (if created by an end user).
- userEmail: string
Email of the end user who created this feature request (if created by an end user).
- userFirstname: string
First name of the end user who created this feature request (if created by an end user).
- userLastname: string
Last name of the end user who created this feature request (if created by an end user).
- userCustomAttributes: object
Custom attributes of the end user who created this feature request (if created by an end user).
Example
{
"id": "123",
"date": "2018-12-31T00:00:00Z",
"visible": "true",
"category": "bug",
"status": "under_review",
"translations": [
{
"title": "Title of the feature request.",
"content": "Content of the feature request.",
"contentHtml": "<p>Content of the feature request.</p>",
"language": "EN",
"permalink": "https://app.getbeamer.com/beamer/requests/en/example-feature-request",
"images": [
"https://app.getbeamer.com/pictures?id=123"
]
}
],
"votesCount": 10,
"commentsCount": "10",
"notes": "Internal note",
"filters": "Feature request",
"internalUserEmail": "janedoe@getbeamer.com",
"internalUserFirstname": "Jane",
"internalUserLastname": "Doe",
"userId": "1010",
"userEmail": "johndoe@getbeamer.com",
"userFirstname": "John",
"userLastname": "Doe",
"userCustomAttributes": {
"Organization": "Example",
"age": 33
}
}
FeatureRequestCreation: object
- title: string[]
Title of the feature request.
string - content: string[]
Content of the feature request.
string - visible: boolean
Whether this feature request should be visible in your feed.
- category: string
Category for the feature request.
- status: string
Status for the feature request.
- notes: string
Notes for the feature request.
- filters: string
Segmentation filters for the feature request.
- votesCount: integer
Number of votes to create for this feature request.
- date: string
Publication date for this post in ISO-8601 format. [Future dates / post scheduling are only available on the Startup plan (and up)]
- internalUserEmail: string
Email of the user in your account creating this feature request (if created by a team member). [Required if not sending userId, userEmail, userFirstname or _userLastname_].
- userId: string
ID of the end user creating this feature request (if created by an end user). [If not sending internalUserEmail, at least one of userId, userEmail, userFirstname or userLastname are required].
- userEmail: string
Email of the end user creating this feature request (if created by an end user). [If not sending internalUserEmail, at least one of userId, userEmail, userFirstname or userLastname are required].
- userFirstname: string
First name of the end user creating this feature request (if created by an end user). [If not sending internalUserEmail, at least one of userId, userEmail, userFirstname or userLastname are required].
- userLastname: string
Last name of the end user creating this feature request (if created by an end user). [If not sending internalUserEmail, at least one of userId, userEmail, userFirstname or userLastname are required].
Example
{
"title": [
"Title of your feature request"
],
"content": [
"Content of your feature request"
],
"visible": true,
"category": "bug",
"status": "under_review",
"notes": "Internal note",
"filters": "Feature request",
"votesCount": 10,
"date": "2018-12-31T00:00:00",
"internalUserEmail": "janedoe@getbeamer.com",
"userId": "1010",
"userEmail": "johndoe@getbeamer.com",
"userFirstname": "John",
"userLastname": "Doe"
}
FeatureRequestTranslation: object
- title: string
Title of the feature request.
- content: string
Content of the feature request (plain text).
- contentHtml: string
Content of the feature request (original HTML format).
- language: string
Language of this feature request (in ISO-639 two-letter code format).
- permalink: string
Permalink of this feature request.
- images: string[]
URLs of the images embedded in this post.
string
Example
{
"title": "Title of the feature request.",
"content": "Content of the feature request.",
"contentHtml": "<p>Content of the feature request.</p>",
"language": "EN",
"permalink": "https://app.getbeamer.com/beamer/requests/en/example-feature-request",
"images": [
"https://app.getbeamer.com/pictures?id=123"
]
}
User: object
- beamerId: string
Beamer generated ID for this user.
- userId: string
ID of the user (as defined in the embedded script's user_id parameter).
- userEmail: string
Email of the user.
- userFirstName: string
First name of the user.
- userLastName: string
Last name of the user.
- language: string
Last detected language for this user.
- filter: string
Segmentation filters applied to this user.
- firstSeen: string
First detected access of this user, in ISO-8601 format.
- lastSeen: string
Last detected access of this user, in ISO-8601 format.
- ip: string
Last detected IP from where this user accessed.
- browser: string
Last detected browser from where this user accessed.
- os: string
Last detected operating system from where this user accessed.
- city: string
Last detected city from where this user accessed.
- country: string
Last detected country from where this user accessed.
- latitude: string
Last detected latitude from where this user accessed.
- longitude: string
Last detected longitude from where this user accessed.
Example
{
"beamerId": "12345-67890",
"userId": "1234",
"userEmail": "example@getbeamer.com",
"userFirstName": "Example",
"userLastName": "Beamer",
"language": "EN",
"filter": "example-filter",
"firstSeen": "2018-12-31T10:00:00Z",
"lastSeen": "2019-01-01T10:00:00Z",
"ip": "127.0.0.1",
"browser": "Chrome",
"os": "Mac OS",
"city": "Barcelona",
"country": "Spain",
"latitude": "0.0",
"longitude": "0.0"
}
UserCreation: object
- userId: string
Unique identifier for this user.
- userEmail: string
Email for this user.
- userFirstName: string
First name for this user.
- userLastName: string
Last name for this user.
- filter: string
Segmentation filter (or filters) for this user.
- language: string
Language for this user. The language must follow the ISO-639 two-letter code format.
- ip: string
IP from where this user accessed.
- browser: string
Browser from where this user accessed.
- os: string
Operating system from where this user accessed.
- city: string
City from where this user accessed.
- country: string
Country from where this user accessed.
- latitude: string
Latitude from where this user accessed.
- longitude: string
Longitude from where this user accessed.
Example
{
"userId": "1234",
"userEmail": "example@getbeamer.com",
"userFirstName": "Example",
"userLastName": "Beamer",
"filter": "role-admin;paid-user",
"language": "EN",
"ip": "127.0.0.1",
"browser": "Chrome",
"os": "Mac OS",
"city": "Barcelona",
"country": "Spain",
"latitude": "0.0",
"longitude": "0.0"
}