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 Starter. If you need an extension, please contact us on our Support chat.

API Endpoint
https://api.getbeamer.com/v0
Contact: info@getbeamer.com
Schemes: https
Version: 0.1.0

Authentication

Beamer-Api-Key

type
apiKey
in
header
name
Beamer-Api-Key

Feed

Operations on your feed

Get the URL for your feed

GET /url

Use /url to retrieve the URL for your feed.

language: string
in query

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 Starter plan (and up)]

filterByUrl: boolean
in query

Whether to apply URL filtering to the feed. [Only available on the Pro plan (and up)]

filter: string
in query

Retrieve posts with a matching segmentation filter. [Only available on the Pro plan (and up)]

forceFilter: string
in query

Only retrieve posts that match this segmentation filter. [Only available on the Pro plan (and up)]

userFirstName: string
in query

First name of the user viewing the feed (for Analytics).

userLastName: string
in query

Last name of the user viewing the feed (for Analytics).

userEmail: string
in query

Email of the user viewing the feed (for Analytics).

userId: string
in query

ID of the user viewing the feed (for Analytics).

theme: string
in query

Theme class to use for appearance customization via CSS. [Only available on the Pro plan (and up)]

200 OK

Request authenticated. The request returns a JSON object containing the URL for your standalone feed.

type
object
401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

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

POST /ping

Use /ping to check you are correctly authenticating your requests with your API key.

200 OK

Request authenticated. The request returns a JSON object containing the name of your product on Beamer.

type
object
401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

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

GET /posts

Use the GET method to query and retrieve existing posts from your account.

filter: string
in query

Retrieve posts with a matching segmentation filter. [Only available on the Pro plan (and up)]

forceFilter: string
in query

Only retrieve posts that match this segmentation filter. [Only available on the Pro plan (and up)]

filterUrl: string
in query

If URL segmentation is enabled, include posts with a matching segmentation URL. [Only available on the Pro plan (and up)]

dateFrom: string
in query

Retrieve posts published after this date. The date must follow the ISO-8601 format.

dateTo: string current date/time
in query

Retrieve posts published before this date. The date must follow the ISO-8601 format.

language: string
in query

Retrieve posts with translations in this language. The language must follow the ISO-639 two-letter code format.

category: string
in query

Retrieve posts with this category.

published: boolean
in query

Retrieve only published (or draft) posts. If unspecified, both types of posts will be retrieved.

archived: boolean
in query

Retrieve only archived (or not archived) posts. If unspecified, both types of posts will be retrieved.

expired: boolean
in query

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 Starter plan (and up)]

filterByUserId: boolean false
in query

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 Scale plan]

userFirstName: string
in query

First name of the user viewing these posts (for Analytics).

userLastName: string
in query

Last name of the user viewing these posts (for Analytics).

userEmail: string
in query

Email of the user viewing these posts (for Analytics).

userId: string
in query

ID of the user viewing these posts (for Analytics).

traceableLinks: boolean false
in query

Whether links in the post should be converted to a traceable format (both the CTA and links within the content). If true, the opened URL will be tracked and record a 'click' entry in your Analytics.

ignoreRequestDetails: boolean false
in query

Whether request-specific details should be ignored (this includes IP, browser/OS and geolocation details). Useful when sending requests from your backend, where the request's details aren't representative of the end user.

saveViews: boolean true
in query

Whether to save views for the posts retrieved (for Analytics). If unspecified, views are saved.

maxResults: integer
in query

Retrieve this many posts (at most). The max number of posts returned is 10.

page: integer
in query

Combined with the value of 'maxResults' (or its default value), paginate the retrieval of posts.

ignoreFilters: boolean
in query

If true, all posts will be retrieved, ignoring any segmentation they may have. This parameter should only be used for requests sent from the backend. [In order to user this parameter, the API key should have the 'Read posts (ignore filters)' permission enabled.]

200 OK

Posts retrieved.

type
400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

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",
    "views": "310",
    "uniqueViews": "250",
    "clicks": "120",
    "feedbacks": "55",
    "positiveReactions": "12",
    "neutralReactions": "5",
    "negativeReactions": "10"
  }
]

Create a new post

POST /posts

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 Starter 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",
  "fixedBoostedAnnouncement": true
}
201 Created

Post created.

The request returns a JSON object containing the details of the post.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

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",
  "views": "310",
  "uniqueViews": "250",
  "clicks": "120",
  "feedbacks": "55",
  "positiveReactions": "12",
  "neutralReactions": "5",
  "negativeReactions": "10"
}

Count existing posts

GET /posts/count

Use the GET method to count existing posts from your account.

filter: string
in query

Count posts with a matching segmentation filter. [Only available on the Pro plan (and up)]

forceFilter: string
in query

Only count posts that match this segmentation filter. [Only available on the Pro plan (and up)]

filterUrl: string
in query

If URL segmentation is enabled, include posts with a matching segmentation URL. [Only available on the Pro plan (and up)]

dateFrom: string
in query

Count posts published after this date. The date must follow the ISO-8601 format.

dateTo: string current date/time
in query

Count posts published before this date. The date must follow the ISO-8601 format.

language: string
in query

Count posts with translations in this language. The language must follow the ISO-639 two-letter code format. [Only available on the Starter plan (and up)]

category: string
in query

Count posts with this category.

published: boolean
in query

Count only published (or draft) posts. If unspecified, both types of posts will be counted.

archived: boolean
in query

Count only archived (or not archived) posts. If unspecified, both types of posts will be counted.

expired: boolean
in query

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.

filterByUserId: boolean false
in query

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 Scale plan]

userId: string
in query

For using with the filterByUserId parameter only.

ignoreFilters: boolean
in query

If true, all posts will be counted, ignoring any segmentation they may have. This parameter should only be used for requests sent from the backend. [In order to user this parameter, the API key should have the 'Read posts (ignore filters)' permission enabled.]

200 OK

Posts count.

type
object
400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (200 OK)
{
  "count": 99
}

Get post by ID

GET /posts/{postId}

Returns a post.

postId: integer (int64)
in path

ID of the post to retrieve.

userFirstName: string
in query

First name of the user viewing these posts (for Analytics).

userLastName: string
in query

Last name of the user viewing these posts (for Analytics).

userEmail: string
in query

Email of the user viewing these posts (for Analytics).

userId: string
in query

ID of the user viewing these posts (for Analytics).

language: string
in query

ID of the user viewing these posts (for Analytics).

traceableLinks: boolean false
in query

Whether links in the post should be converted to a traceable format (both the CTA and links within the content). If true, the opened URL will be tracked and record a 'click' entry in your Analytics.

ignoreRequestDetails: boolean false
in query

Whether request-specific details should be ignored (this includes IP, browser/OS and geolocation details). Useful when sending requests from your backend, where the request's details aren't representative of the end user.

200 OK

Post retrieved.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

404 Not Found

Post not found.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

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",
  "views": "310",
  "uniqueViews": "250",
  "clicks": "120",
  "feedbacks": "55",
  "positiveReactions": "12",
  "neutralReactions": "5",
  "negativeReactions": "10"
}

Update an existing post

PUT /posts/{postId}

Updates the post with the existing ID.

JSON object containing the details of the post to update.

postId: integer (int64)
in path

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",
  "fixedBoostedAnnouncement": true
}
200 OK

Post updated.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

404 Not Found

Post not found.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

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",
  "views": "310",
  "uniqueViews": "250",
  "clicks": "120",
  "feedbacks": "55",
  "positiveReactions": "12",
  "neutralReactions": "5",
  "negativeReactions": "10"
}

Deletes a post

DELETE /posts/{postId}

Deletes the post with the given ID.

postId: integer (int64)
in path

ID of the post to delete.

204 No Content

Post deleted.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

404 Not Found

Post not found.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Get existing comments in a post

GET /posts/{postId}/comments

Use the GET method to query and retrieve existing comments from a post.

postId: integer (int64)
in path

ID of the post to retrieve comments from.

dateFrom: string
in query

Retrieve comments published after this date. The date must follow the ISO-8601 format.

dateTo: string current date/time
in query

Retrieve comments published before this date. The date must follow the ISO-8601 format.

language: string
in query

Retrieve comments with translations in this language. The language must follow the ISO-639 two-letter code format.

search: string
in query

Retrieve comments with content that contain this text.

maxResults: integer
in query

Retrieve this many comments (at most). The max number of comments returned is 10.

page: integer
in query

Combined with the value of 'maxResults' (or its default value), paginate the retrieval of comments.

200 OK

Comments retrieved.

type
400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "id": "1234",
    "date": "2018-12-31T00:00:00Z",
    "text": "This is a comment.",
    "postTitle": "Title of the post.",
    "userId": "1234",
    "userEmail": "example@getbeamer.com",
    "userFirstName": "Jane",
    "userLastName": "Doe",
    "url": "https://app.getbeamer.com/inbox#comment?id=1234",
    "userCustomAttributes": {
      "organization": "Example",
      "age": 33
    }
  }
]

Create a new comment

POST /posts/{postId}/comments

Use the POST method to create a new comment on a post.

Send a JSON object in the body of the request containing the details of the comment to create.

postId: integer (int64)
in path

ID of the post to create a comment for.

Request Content-Types: application/json
Request Example
{
  "text": "Content of your comment",
  "userId": "1010",
  "userEmail": "johndoe@getbeamer.com",
  "userFirstname": "John",
  "userLastname": "Doe"
}
201 Created

Comment created.

The request returns a JSON object containing the details of the comment.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (201 Created)
{
  "id": "1234",
  "date": "2018-12-31T00:00:00Z",
  "text": "This is a comment.",
  "postTitle": "Title of the post.",
  "userId": "1234",
  "userEmail": "example@getbeamer.com",
  "userFirstName": "Jane",
  "userLastName": "Doe",
  "url": "https://app.getbeamer.com/inbox#comment?id=1234",
  "userCustomAttributes": {
    "organization": "Example",
    "age": 33
  }
}

Count existing comments in a post

GET /posts/{postId}/comments/count

Use the GET method to count existing comments from a post.

postId: integer (int64)
in path

ID of the post to retrieve comments from.

dateFrom: string
in query

Retrieve comments published after this date. The date must follow the ISO-8601 format.

dateTo: string current date/time
in query

Retrieve comments published before this date. The date must follow the ISO-8601 format.

language: string
in query

Retrieve comments with translations in this language. The language must follow the ISO-639 two-letter code format.

search: string
in query

Retrieve comments with content that contain this text.

200 OK

Comments retrieved.

type
object
400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

404 Not Found

Post not found.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (200 OK)
{
  "count": 99
}

Get comment by ID

GET /posts/{postId}/comments/{commentId}

Returns a comment.

postId: integer (int64)
in path

ID of the post to retrieve comments from.

commentId: integer (int64)
in path

ID of the comment to retrieve.

200 OK

Comment retrieved.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

404 Not Found

Comment not found.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "1234",
  "date": "2018-12-31T00:00:00Z",
  "text": "This is a comment.",
  "postTitle": "Title of the post.",
  "userId": "1234",
  "userEmail": "example@getbeamer.com",
  "userFirstName": "Jane",
  "userLastName": "Doe",
  "url": "https://app.getbeamer.com/inbox#comment?id=1234",
  "userCustomAttributes": {
    "organization": "Example",
    "age": 33
  }
}

Deletes a comment

DELETE /posts/{postId}/comments/{commentId}

Deletes the comment with the given ID.

postId: integer (int64)
in path

ID of the post to delete a comment from.

commentId: integer (int64)
in path

ID of the comment to delete.

204 No Content

Comment deleted.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

404 Not Found

Comment not found.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Get existing reactions in a post

GET /posts/{postId}/reactions

Use the GET method to query and retrieve existing reactions from a post.

postId: integer (int64)
in path

ID of the post to retrieve reactions from.

dateFrom: string
in query

Retrieve reactions published after this date. The date must follow the ISO-8601 format.

dateTo: string current date/time
in query

Retrieve reactions published before this date. The date must follow the ISO-8601 format.

reaction: string
in query

Retrieve reactions with this reaction type (positive, neutral or negative).

maxResults: integer
in query

Retrieve this many reactions (at most). The max number of reactions returned is 10.

page: integer
in query

Combined with the value of 'maxResults' (or its default value), paginate the retrieval of reactions.

200 OK

Reactions retrieved.

type
400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "id": "1234",
    "date": "2018-12-31T00:00:00Z",
    "reaction": "positive",
    "postTitle": "Title of the post.",
    "userId": "1234",
    "userEmail": "example@getbeamer.com",
    "userFirstName": "Jane",
    "userLastName": "Doe",
    "url": "https://app.getbeamer.com/inbox#reaction?id=1234",
    "userCustomAttributes": {
      "organization": "Example",
      "age": 33
    }
  }
]

Create a new reaction

POST /posts/{postId}/reactions

Use the POST method to create a new reaction on a post.

Send a JSON object in the body of the request containing the details of the reaction to create.

postId: integer (int64)
in path

ID of the post to create a reaction for.

Request Content-Types: application/json
Request Example
{
  "reaction": "positive",
  "userId": "1010",
  "userEmail": "johndoe@getbeamer.com",
  "userFirstname": "John",
  "userLastname": "Doe"
}
201 Created

Reaction created.

The request returns a JSON object containing the details of the reaction.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (201 Created)
{
  "id": "1234",
  "date": "2018-12-31T00:00:00Z",
  "reaction": "positive",
  "postTitle": "Title of the post.",
  "userId": "1234",
  "userEmail": "example@getbeamer.com",
  "userFirstName": "Jane",
  "userLastName": "Doe",
  "url": "https://app.getbeamer.com/inbox#reaction?id=1234",
  "userCustomAttributes": {
    "organization": "Example",
    "age": 33
  }
}

Count existing reactions in a post

GET /posts/{postId}/reactions/count

Use the GET method to count existing reactions from a post.

postId: integer (int64)
in path

ID of the post to retrieve reactions from.

dateFrom: string
in query

Retrieve reactions published after this date. The date must follow the ISO-8601 format.

dateTo: string current date/time
in query

Retrieve reactions published before this date. The date must follow the ISO-8601 format.

reaction: string
in query

Retrieve reactions with this reaction type (positive, neutral or negative).

200 OK

Reactions retrieved.

type
object
400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

404 Not Found

Reactions not found.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (200 OK)
{
  "count": 99
}

Get reaction by ID

GET /posts/{postId}/reactions/{reactionId}

Returns a reaction.

postId: integer (int64)
in path

ID of the post to retrieve reactions from.

reactionId: integer (int64)
in path

ID of the reaction to retrieve.

200 OK

Reaction retrieved.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

404 Not Found

Reaction not found.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "1234",
  "date": "2018-12-31T00:00:00Z",
  "reaction": "positive",
  "postTitle": "Title of the post.",
  "userId": "1234",
  "userEmail": "example@getbeamer.com",
  "userFirstName": "Jane",
  "userLastName": "Doe",
  "url": "https://app.getbeamer.com/inbox#reaction?id=1234",
  "userCustomAttributes": {
    "organization": "Example",
    "age": 33
  }
}

Deletes a reaction

DELETE /posts/{postId}/reactions/{reactionId}

Deletes the reaction with the given ID.

postId: integer (int64)
in path

ID of the post to delete a reaction from.

reactionId: integer (int64)
in path

ID of the reaction to delete.

204 No Content

Reaction deleted.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

404 Not Found

Reaction not found.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Get unread posts

GET /unread

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).

filter: string
in query

Retrieve posts with a matching segmentation filter. [Only available on the Pro plan (and up)]

forceFilter: string
in query

Only retrieve posts that match this segmentation filter. [Only available on the Pro plan (and up)]

filterUrl: string
in query

If URL segmentation is enabled, include posts with a matching segmentation URL. [Only available on the Pro plan (and up)]

dateFrom: string
in query

Retrieve posts published after this date. The date must follow the ISO-8601 format.

language: string
in query

Retrieve posts with translations in this language. The language must follow the ISO-639 two-letter code format. [Only available on the Starter plan (and up)]

category: string
in query

Retrieve posts with this category.

userFirstName: string
in query

First name of the user viewing these posts (for Analytics).

userLastName: string
in query

Last name of the user viewing these posts (for Analytics).

userEmail: string
in query

Email of the user viewing these posts (for Analytics).

userId: string
in query

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 Scale 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)]

traceableLinks: boolean false
in query

Whether links in the post should be converted to a traceable format (both the CTA and links within the content). If true, the opened URL will be tracked and record a 'click' entry in your Analytics.

ignoreRequestDetails: boolean false
in query

Whether request-specific details should be ignored (this includes IP, browser/OS and geolocation details). Useful when sending requests from your backend, where the request's details aren't representative of the end user.

saveViews: boolean true
in query

Whether to save views for the posts retrieved (for Analytics). If unspecified, views are saved.

markAsRead: boolean true
in query

Whether to mark the posts retrieved as 'read' for the specified user. By default, posts are marked as read and not retrieved again in subsequent calls.

maxResults: integer
in query

Retrieve this many posts (at most). The max number of posts returned is 10.

page: integer
in query

Combined with the value of 'maxResults' (or its default value), paginate the retrieval of posts.

ignoreFilters: boolean
in query

If true, all posts will be retrieved, ignoring any segmentation they may have. This parameter should only be used for requests sent from the backend. [In order to user this parameter, the API key should have the 'Read posts (ignore filters)' permission enabled.]

200 OK

Posts retrieved.

type
400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

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",
    "views": "310",
    "uniqueViews": "250",
    "clicks": "120",
    "feedbacks": "55",
    "positiveReactions": "12",
    "neutralReactions": "5",
    "negativeReactions": "10"
  }
]

Count unread posts

GET /unread/count

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).

filter: string
in query

Count posts with a matching segmentation filter. [Only available on the Pro plan (and up)]

forceFilter: string
in query

Only count posts that match this segmentation filter. [Only available on the Pro plan (and up)]

filterUrl: string
in query

If URL segmentation is enabled, include posts with a matching segmentation URL. [Only available on the Pro plan (and up)]

dateFrom: string
in query

Count posts published after this date. The date must follow the ISO-8601 format.

language: string
in query

Count posts with translations in this language. The language must follow the ISO-639 two-letter code format.

category: string
in query

Count posts with this category.

userFirstName: string
in query

First name of the user viewing these posts (for Analytics).

userLastName: string
in query

Last name of the user viewing these posts (for Analytics).

userEmail: string
in query

Email of the user viewing these posts (for Analytics).

userId: string
in query

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 Scale 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)]

theme: string
in query

Theme class to use for appearance customization via CSS. [Only available on the Pro plan (and up)]

ignoreFilters: boolean
in query

If true, all posts will be counted, ignoring any segmentation they may have. This parameter should only be used for requests sent from the backend. [In order to user this parameter, the API key should have the 'Read posts (ignore filters)' permission enabled.]

200 OK

Posts count.

type
object
400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

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

GET /requests

Use the GET method to query and retrieve existing feature requests from your account.

filters: string
in query

Retrieve feature requests with a matching segmentation filter. [Only available on the Pro plan (and up)]

dateFrom: string
in query

Retrieve feature requests created after this date. The date must follow the ISO-8601 format.

dateTo: string current date/time
in query

Retrieve feature requests created before this date. The date must follow the ISO-8601 format.

language: string
in query

Retrieve feature requests with translations in this language. The language must follow the ISO-639 two-letter code format.

category: string
in query

Retrieve feature requests with this category.

status: string
in query

Retrieve feature requests with this status.

visible: boolean
in query

Retrieve only visible (or not visible) feature requests. If unspecified, both types of feature requests will be retrieved.

search: string
in query

Retrieve feature requests with title or content that contain this text.

maxResults: integer
in query

Retrieve this many feature requests (at most). The max number of posts returned is 10.

page: integer
in query

Combined with the value of 'maxResults' (or its default value), paginate the retrieval of feature requests.

Feature requests retrieved.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

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

POST /requests

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 Starter 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",
  "language": [
    "EN"
  ],
  "internalUserEmail": "janedoe@getbeamer.com",
  "userId": "1010",
  "userEmail": "johndoe@getbeamer.com",
  "userFirstname": "John",
  "userLastname": "Doe"
}
201 Created

Feature request created.

The request returns a JSON object containing the details of the feature request.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

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
  }
}

Count existing feature requests

GET /requests/count

Use the GET method to count existing feature requests from your account.

filters: string
in query

Count feature requests with a matching segmentation filter. [Only available on the Pro plan (and up)]

dateFrom: string
in query

Count feature requests created after this date. The date must follow the ISO-8601 format.

dateTo: string current date/time
in query

Count feature requests created before this date. The date must follow the ISO-8601 format.

language: string
in query

Count feature requests with translations in this language. The language must follow the ISO-639 two-letter code format.

category: string
in query

Count feature requests with this category.

status: string
in query

Count feature requests with this status.

visible: boolean
in query

Count only visible (or not visible) feature requests. If unspecified, both types of feature requests will be retrieved.

search: string
in query

Count feature requests with title or content that contain this text.

200 OK

Feature requests count.

type
object
400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (200 OK)
{
  "count": 99
}

Get feature request by ID

GET /requests/{featureRequestId}

Returns a feature request.

featureRequestId: integer (int64)
in path

ID of the feature request to retrieve.

Feature request retrieved.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

404 Not Found

Feature request not found.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

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
  }
}

Update an existing feature request

PUT /requests/{featureRequestId}

Updates the feature request with the existing ID.

JSON object containing the details of the feature request to update.

featureRequestId: integer (int64)
in path

ID of the feature request to update.

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",
  "language": [
    "EN"
  ],
  "internalUserEmail": "janedoe@getbeamer.com",
  "userId": "1010",
  "userEmail": "johndoe@getbeamer.com",
  "userFirstname": "John",
  "userLastname": "Doe"
}

Feature request updated.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

404 Not Found

Feature request not found.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

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
  }
}

Deletes a feature request

DELETE /requests/{featureRequestId}

Deletes the feature request with the given ID.

featureRequestId: integer (int64)
in path

ID of the feature request to delete.

204 No Content

Feature request deleted.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

404 Not Found

Feature fequest not found.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Get existing comments in a feature request

GET /requests/{featureRequestId}/comments

Use the GET method to query and retrieve existing comments from a feature request.

featureRequestId: integer (int64)
in path

ID of the feature request to retrieve comments from.

dateFrom: string
in query

Retrieve comments published after this date. The date must follow the ISO-8601 format.

dateTo: string current date/time
in query

Retrieve comments published before this date. The date must follow the ISO-8601 format.

visible: boolean
in query

Retrieve only visible (or not visible) comments. If unspecified, both types of comments will be retrieved.

language: string
in query

Retrieve comments with translations in this language. The language must follow the ISO-639 two-letter code format.

search: string
in query

Retrieve comments with content that contain this text.

maxResults: integer
in query

Retrieve this many comments (at most). The max number of comments returned is 10.

page: integer
in query

Combined with the value of 'maxResults' (or its default value), paginate the retrieval of comments.

Comments retrieved.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "id": "1234",
    "date": "2018-12-31T00:00:00Z",
    "visible": "true",
    "actionComment": "true",
    "text": "This is a comment.",
    "featureRequestTitle": "Title of the feature request.",
    "parentComment": "Parent comment.",
    "internalUserEmail": "janedoe@getbeamer.com",
    "internalUserFirstname": "Jane",
    "internalUserLastname": "Doe",
    "userId": "1234",
    "userEmail": "example@getbeamer.com",
    "userFirstName": "Jane",
    "userLastName": "Doe",
    "userCustomAttributes": {
      "organization": "Example",
      "age": 33
    },
    "url": "https://app.getbeamer.com/inbox#featureRequestComment?id=1234"
  }
]

Create a new comment

POST /requests/{featureRequestId}/comments

Use the POST method to create a new comment on a post.

Send a JSON object in the body of the request containing the details of the comment to create.

featureRequestId: integer (int64)
in path

ID of the feature request to create a comment for.

Request Content-Types: application/json
Request Example
{
  "text": "Content of your comment",
  "userId": "1010",
  "userEmail": "johndoe@getbeamer.com",
  "userFirstname": "John",
  "userLastname": "Doe",
  "visible": "true"
}
201 Created

Comment created.

The request returns a JSON object containing the details of the comment.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (201 Created)
{
  "id": "1234",
  "date": "2018-12-31T00:00:00Z",
  "visible": "true",
  "actionComment": "true",
  "text": "This is a comment.",
  "featureRequestTitle": "Title of the feature request.",
  "parentComment": "Parent comment.",
  "internalUserEmail": "janedoe@getbeamer.com",
  "internalUserFirstname": "Jane",
  "internalUserLastname": "Doe",
  "userId": "1234",
  "userEmail": "example@getbeamer.com",
  "userFirstName": "Jane",
  "userLastName": "Doe",
  "userCustomAttributes": {
    "organization": "Example",
    "age": 33
  },
  "url": "https://app.getbeamer.com/inbox#featureRequestComment?id=1234"
}

Count existing comments in a feature request

GET /requests/{featureRequestId}/comments/count

Use the GET method to count existing comments from a feature request.

featureRequestId: integer (int64)
in path

ID of the feature request to count comments from.

dateFrom: string
in query

Count comments published after this date. The date must follow the ISO-8601 format.

dateTo: string current date/time
in query

Count comments published before this date. The date must follow the ISO-8601 format.

visible: boolean
in query

Count only visible (or not visible) comments. If unspecified, both types of comments will be retrieved.

language: string
in query

Count comments with translations in this language. The language must follow the ISO-639 two-letter code format.

search: string
in query

Count comments with content that contain this text.

200 OK

Comments count.

type
object
400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (200 OK)
{
  "count": 99
}

Get comment by ID

GET /requests/{featureRequestId}/comments/{commentId}

Returns a comment.

featureRequestId: integer (int64)
in path

ID of the feature request to retrieve comments from.

commentId: integer (int64)
in path

ID of the comment to retrieve.

Comment retrieved.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

404 Not Found

Comment not found.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "1234",
  "date": "2018-12-31T00:00:00Z",
  "visible": "true",
  "actionComment": "true",
  "text": "This is a comment.",
  "featureRequestTitle": "Title of the feature request.",
  "parentComment": "Parent comment.",
  "internalUserEmail": "janedoe@getbeamer.com",
  "internalUserFirstname": "Jane",
  "internalUserLastname": "Doe",
  "userId": "1234",
  "userEmail": "example@getbeamer.com",
  "userFirstName": "Jane",
  "userLastName": "Doe",
  "userCustomAttributes": {
    "organization": "Example",
    "age": 33
  },
  "url": "https://app.getbeamer.com/inbox#featureRequestComment?id=1234"
}

Deletes a comment

DELETE /requests/{featureRequestId}/comments/{commentId}

Deletes the comment with the given ID.

featureRequestId: integer (int64)
in path

ID of the feature request to delete a comment from.

commentId: integer (int64)
in path

ID of the comment to delete.

204 No Content

Comment deleted.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

404 Not Found

Comment not found.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Get existing votes in a feature request

GET /requests/{featureRequestId}/votes

Use the GET method to query and retrieve existing votes from a feature request.

featureRequestId: integer (int64)
in path

ID of the feature request to retrieve votes from.

dateFrom: string
in query

Retrieve votes created after this date. The date must follow the ISO-8601 format.

dateTo: string current date/time
in query

Retrieve votes created before this date. The date must follow the ISO-8601 format.

maxResults: integer
in query

Retrieve this many votes (at most). The max number of votes returned is 10.

page: integer
in query

Combined with the value of 'maxResults' (or its default value), paginate the retrieval of votes.

Votes retrieved.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "id": "1234",
    "date": "2018-12-31T00:00:00Z",
    "featureRequestTitle": "Title of the feature request.",
    "userId": "1234",
    "userEmail": "example@getbeamer.com",
    "userFirstName": "Jane",
    "userLastName": "Doe",
    "userCustomAttributes": {
      "organization": "Example",
      "age": 33
    },
    "url": "https://app.getbeamer.com/inbox#featureRequestVote?id=1234"
  }
]

Create a new vote

POST /requests/{featureRequestId}/votes

Use the POST method to create a new vote on a feature request.

Send a JSON object in the body of the request containing the details of the vote to create.

featureRequestId: integer (int64)
in path

ID of the feature request to create a comment for.

Request Content-Types: application/json
Request Example
{
  "userId": "1010",
  "userEmail": "johndoe@getbeamer.com",
  "userFirstname": "John",
  "userLastname": "Doe"
}
201 Created

Vote created.

The request returns a JSON object containing the details of the vote.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (201 Created)
{
  "id": "1234",
  "date": "2018-12-31T00:00:00Z",
  "featureRequestTitle": "Title of the feature request.",
  "userId": "1234",
  "userEmail": "example@getbeamer.com",
  "userFirstName": "Jane",
  "userLastName": "Doe",
  "userCustomAttributes": {
    "organization": "Example",
    "age": 33
  },
  "url": "https://app.getbeamer.com/inbox#featureRequestVote?id=1234"
}

Count existing votes in a feature request

GET /requests/{featureRequestId}/votes/count

Use the GET method to count existing votes from a feature request.

featureRequestId: integer (int64)
in path

ID of the feature request to count votes from.

200 OK

Votes count.

type
object
400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (200 OK)
{
  "count": 99
}

Get vote by ID

GET /requests/{featureRequestId}/votes/{voteId}

Returns a vote.

featureRequestId: integer (int64)
in path

ID of the feature request to retrieve votes from.

voteId: integer (int64)
in path

ID of the vote to retrieve.

Vote retrieved.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

404 Not Found

Vote not found.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "1234",
  "date": "2018-12-31T00:00:00Z",
  "featureRequestTitle": "Title of the feature request.",
  "userId": "1234",
  "userEmail": "example@getbeamer.com",
  "userFirstName": "Jane",
  "userLastName": "Doe",
  "userCustomAttributes": {
    "organization": "Example",
    "age": 33
  },
  "url": "https://app.getbeamer.com/inbox#featureRequestVote?id=1234"
}

Deletes a vote

DELETE /requests/{featureRequestId}/votes/{voteId}

Deletes the vote with the given ID.

featureRequestId: integer (int64)
in path

ID of the feature request to retrieve votes from.

voteId: integer (int64)
in path

ID of the vote to retrieve.

204 No Content

Vote deleted.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

404 Not Found

Vote not found.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Users

Operations on your users [Only available on the Scale plan]

Get users from your Analytics

GET /users

Use the GET method to query and retrieve users from your account's Analytics.

userId: string
in query

ID of the user (as defined in the embedded script's user_id parameter).

beamerId: string
in query

Beamer generated ID for the user.

userEmail: string
in query

Email of the user.

sort: string
in query

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).

maxResults: integer
in query

Retrieve this many users (at most). The default number of users returned is 10, and the maximum is 100.

page: integer
in query

Combined with the value of 'maxResults' (or its default value), paginate the retrieval of users.

200 OK

Users retrieved.

type
400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

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

POST /users

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"
}
201 Created

User created.

The request returns a JSON object containing the details of the user.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

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

PUT /users

Updates existing users.

JSON object containing the details to update for users that match the query.

userId: string
in query

ID of the user to update.

beamerId: string
in query

Beamer generated ID of the user to update.

userEmail: string
in query

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"
}
200 OK

Users updated.

type
400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

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

DELETE /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.

userId: string
in query

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 (;).

beamerId: string
in query

Beamer generated ID of the user to delete. Multiple IDs can be passed in, separated by semicolons (;).

userEmail: string
in query

Email of the user to delete. Multiple emails can be passed in, separated by semicolons (;).

200 OK

Users deleted.

type
object
400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (200 OK)
{
  "deleted": 1
}

NPS

Operations on your NPS responses

NPS

Get NPS responses

GET /nps

Use the GET method to query and retrieve NPS responses from your account.

dateFrom: string
in query

Retrieve NPS responses sent after this date. The date must follow the ISO-8601 format.

dateTo: string current date/time
in query

Retrieve NPS responses sent before this date. The date must follow the ISO-8601 format.

scoreFrom: integer
in query

Retrieve NPS responses with a score of this value or greater.

scoreTo: integer
in query

Retrieve NPS responses with a score of this value or less.

search: string
in query

Retrieve NPS responses with feedback that contains this text. The search value can also match the name of the user.

maxResults: integer
in query

Retrieve this many posts (at most). The default number of responses returned is 10, and the maximum is 100.

page: integer
in query

Combined with the value of 'maxResults' (or its default value), paginate the retrieval of NPS response.

200 OK
NPS

NPS responses retrieved.

type
NPS
400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "id": "64e508e8961ebc4a71688027",
    "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"
  }
]
NPS

Count NPS responses

GET /nps/count

Use the GET method to count NPS responses from your account.

dateFrom: string
in query

Retrieve NPS responses sent after this date. The date must follow the ISO-8601 format.

dateTo: string current date/time
in query

Retrieve NPS responses sent before this date. The date must follow the ISO-8601 format.

scoreFrom: integer
in query

Retrieve NPS responses with a score of this value or greater.

scoreTo: integer
in query

Retrieve NPS responses with a score of this value or less.

search: string
in query

Retrieve NPS responses with feedback that contains this text. The search value can also match the name of the user.

200 OK

NPS responses count.

type
object
400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (200 OK)
{
  "count": 99
}
NPS

Check if a user should see the NPS prompt

GET /nps/check

Use the GET method to check if a certain user meets the conditions to see the NPS prompt.

userId: string
in query

ID of the user (as defined in the embedded script's user_id parameter).

beamerId: string
in query

Beamer generated ID for the user.

userEmail: string
in query

Email of the user.

userFirstName: string
in query

First name of the user.

userLastName: string
in query

Last name of the user.

filter: string
in query

Segmentation filters applied to this user.

url: string
in query

Current URL (where the user is at now).

createdAt: string
in query

Creation/signup date for this user. The date must follow the ISO-8601 format.

language: string
in query

Language of the user.

mobile: boolean
in query

Whether this user is coming from a mobile device. If unspecified, it will be considered false.

multi: boolean
in query

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.

200 OK

NPS check results.

type
object
400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json
Response Example (200 OK)
{
  "shouldShow": true,
  "url": "https://app.getbeamer.com/nps..."
}
NPS

Send NPS email survey

POST /nps/email

Use the POST method send an NPS email survey.

Send a JSON object in the body of the request containing the details of the user.

Request Example
{
  "userEmail": "jdoe@getbeamer.com"
}
200 OK

NPS email notification sent.

204 No Content

NPS email notification was already sent.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json

Team

Operations on your team [Beta]

Invite a new member into your Beamer team

POST /team

Use the POST method to invite a new team member into your Beamer account.

Send a JSON object in the body of the request containing the email and role of the team member to invite.

Request Example
{
  "email": "jdoe@getbeamer.com",
  "role": "writer"
}
201 Created

Team member created.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json

Update the role of a member in your Beamer team

PUT /team

Use the PUT method to update the role of a team member in your Beamer account.

Send a JSON object in the body of the request containing the email and role of the team member to update.

Request Example
{
  "email": "jdoe@getbeamer.com",
  "role": "writer"
}
200 OK

Team member updated.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json

Remove a member from your Beamer team

DELETE /team

Use the DELETE method to remove a team member from your Beamer account.

Send a JSON object in the body of the request containing the email of the team member to delete.

Request Example
{
  "email": "jdoe@getbeamer.com"
}
204 No Content

Team member deleted.

400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

Something went wrong on our side.

Response Content-Types: application/json

Privacy

Deletes user data

DELETE /privacy

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.

userId: string
in query

ID of the user to delete (as defined in the embedded script's user_id parameter).

beamerId: string
in query

Beamer generated ID of the user to delete. Multiple IDs can be passed in, separated by semicolons (;).

userEmail: string
in query

Email of the user to delete. Multiple emails can be passed in, separated by semicolons (;).

200 OK

Users deleted.

type
object
400 Bad Request

Some parameter is missing or doesn't follow the API specification.

401 Unauthorized

Either no API key was provided or the provided API key is invalid

403 Forbidden

Not allowed to access this resource.

405 Method Not Allowed

This method is not allowed on this resource.

429 Too Many Requests

You have reached your account's monthly requests limit. If you think this is wrong, please reach out on our Support chat.

500 Internal Server Error

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

id: string

Unique identifier of this response.

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
{
  "id": "64e508e8961ebc4a71688027",
  "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"
}

NpsEmailSurvey: object

userEmail: string

Email address of the user to send an NPS survey to.

Example
{
  "userEmail": "jdoe@getbeamer.com"
}

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.

views: integer (int64)

Number of views for this post.

uniqueViews: integer (int64)

Number of unique views for this post.

clicks: integer (int64)

Number of clicks for this post.

feedbacks: integer (int64)

Number of feedbacks for this post.

positiveReactions: integer (int64)

Number of positive reactions for this post.

neutralReactions: integer (int64)

Number of neutral reactions for this post.

negativeReactions: integer (int64)

Number of negative reactions for of 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",
  "views": "310",
  "uniqueViews": "250",
  "clicks": "120",
  "feedbacks": "55",
  "positiveReactions": "12",
  "neutralReactions": "5",
  "negativeReactions": "10"
}

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 Starter 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 Starter plan (and up)]

dueDate: string

Expiration date for this post in ISO-8601 format. [Only available on the Starter plan (and up)]

language: string[]

Language of this translation (in ISO-639 two-letter code format). [Only available on the Starter 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 Scale 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 Starter 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.

fixedBoostedAnnouncement: boolean

Enable this for the post to be shown as a fixed top-bar announcement.

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",
  "fixedBoostedAnnouncement": true
}

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"
  ]
}

Comment: object

id: integer (int64)

Unique identifier of this comment.

date: string

Publication date of this comment in ISO-8601 format.

text: string

Content for this comment.

postTitle: string

Title of the post this comment was created on.

userId: string

ID of the user that sent this comment.

userEmail: string

Email of the user that sent this comment.

userFirstName: string

First name of the user that sent this comment.

userLastName: string

Last name of the user that sent this comment.

url: string

URL for this comment in your dashboard.

userCustomAttributes: object

Custom attributes of the user who created this comment.

Example
{
  "id": "1234",
  "date": "2018-12-31T00:00:00Z",
  "text": "This is a comment.",
  "postTitle": "Title of the post.",
  "userId": "1234",
  "userEmail": "example@getbeamer.com",
  "userFirstName": "Jane",
  "userLastName": "Doe",
  "url": "https://app.getbeamer.com/inbox#comment?id=1234",
  "userCustomAttributes": {
    "organization": "Example",
    "age": 33
  }
}

CommentCreation: object

text: string

Content of the comment.

userId: string

ID of the end user who created this comment.

userEmail: string

Email of the end user who created this comment.

userFirstname: string

First name of the end user who created this comment.

userLastname: string

Last name of the end user who created this comment.

Example
{
  "text": "Content of your comment",
  "userId": "1010",
  "userEmail": "johndoe@getbeamer.com",
  "userFirstname": "John",
  "userLastname": "Doe"
}

Reaction: object

id: integer (int64)

Unique identifier of this reaction.

date: string

Publication date of this reaction in ISO-8601 format.

reaction: string

Reaction type (positive, negative or neutral).

postTitle: string

Title of the post this reaction was created on.

userId: string

ID of the user that sent this reaction.

userEmail: string

Email of the user that sent this reaction.

userFirstName: string

First name of the user that sent this reaction.

userLastName: string

Last name of the user that sent this reaction.

url: string

URL for this reaction in your dashboard.

userCustomAttributes: object

Custom attributes of the user who created this reaction.

Example
{
  "id": "1234",
  "date": "2018-12-31T00:00:00Z",
  "reaction": "positive",
  "postTitle": "Title of the post.",
  "userId": "1234",
  "userEmail": "example@getbeamer.com",
  "userFirstName": "Jane",
  "userLastName": "Doe",
  "url": "https://app.getbeamer.com/inbox#reaction?id=1234",
  "userCustomAttributes": {
    "organization": "Example",
    "age": 33
  }
}

ReactionCreation: object

reaction: string

Reaction type (positive, negative or neutral).

userId: string

ID of the end user who created this reaction.

userEmail: string

Email of the end user who created this reaction.

userFirstname: string

First name of the end user who created this reaction.

userLastname: string

Last name of the end user who created this reaction.

Example
{
  "reaction": "positive",
  "userId": "1010",
  "userEmail": "johndoe@getbeamer.com",
  "userFirstname": "John",
  "userLastname": "Doe"
}

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 Starter plan (and up)]

language: string[]

Language of this translation (in ISO-639 two-letter code format). [Only available on the Starter plan (and up)]

string
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",
  "language": [
    "EN"
  ],
  "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"
  ]
}

FeatureRequestComment: object

id: integer (int64)

Unique identifier of this comment.

date: string

Publication date of this comment in ISO-8601 format.

visible: boolean

Whether this comment is visible or not.

actionComment: boolean

Whether this comment was created automatically created after an action (such as updating the feature request's status).

text: string

Content for this comment.

featureRequestTitle: string

Title of the feature request this comment was created on (in case it's a direct comment on the feature request).

parentComment: string

Content of the parent comment this comment was created on (in case it's a reply to another comment).

internalUserEmail: string

Email of the user in your account who created this comment (if created by a team member).

internalUserFirstname: string

First name of the user in your account who created this comment (if created by a team member).

internalUserLastname: string

Last name of the user in your account who created this comment (if created by a team member).

userId: string

ID of the user that sent this comment.

userEmail: string

Email of the user that sent this comment.

userFirstName: string

First name of the user that sent this comment.

userLastName: string

Last name of the user that sent this comment.

userCustomAttributes: object

Custom attributes of the user who created this comment.

url: string

URL for this comment in your dashboard.

Example
{
  "id": "1234",
  "date": "2018-12-31T00:00:00Z",
  "visible": "true",
  "actionComment": "true",
  "text": "This is a comment.",
  "featureRequestTitle": "Title of the feature request.",
  "parentComment": "Parent comment.",
  "internalUserEmail": "janedoe@getbeamer.com",
  "internalUserFirstname": "Jane",
  "internalUserLastname": "Doe",
  "userId": "1234",
  "userEmail": "example@getbeamer.com",
  "userFirstName": "Jane",
  "userLastName": "Doe",
  "userCustomAttributes": {
    "organization": "Example",
    "age": 33
  },
  "url": "https://app.getbeamer.com/inbox#featureRequestComment?id=1234"
}

FeatureRequestCommentCreation: object

text: string

Content of the comment.

userId: string

ID of the end user who created this comment.

userEmail: string

Email of the end user who created this comment.

userFirstname: string

First name of the end user who created this comment.

userLastname: string

Last name of the end user who created this comment.

visible: boolean

Whether this comment should be visible or not.

Example
{
  "text": "Content of your comment",
  "userId": "1010",
  "userEmail": "johndoe@getbeamer.com",
  "userFirstname": "John",
  "userLastname": "Doe",
  "visible": "true"
}

FeatureRequestVote: object

id: integer (int64)

Unique identifier of this vote.

date: string

Creation date of this vote in ISO-8601 format.

featureRequestTitle: string

Title of the feature request this vote was created on.

userId: string

ID of the user that created this vote.

userEmail: string

Email of the user that created this vote.

userFirstName: string

First name of the user that created this vote.

userLastName: string

Last name of the user that created this vote.

userCustomAttributes: object

Custom attributes of the user who created this vote.

url: string

URL for this vote in your dashboard.

Example
{
  "id": "1234",
  "date": "2018-12-31T00:00:00Z",
  "featureRequestTitle": "Title of the feature request.",
  "userId": "1234",
  "userEmail": "example@getbeamer.com",
  "userFirstName": "Jane",
  "userLastName": "Doe",
  "userCustomAttributes": {
    "organization": "Example",
    "age": 33
  },
  "url": "https://app.getbeamer.com/inbox#featureRequestVote?id=1234"
}

FeatureRequestVoteCreation: object

userId: string

ID of the end user who created this vote.

userEmail: string

Email of the end user who created this vote.

userFirstname: string

First name of the end user who created this vote.

userLastname: string

Last name of the end user who created this vote.

Example
{
  "userId": "1010",
  "userEmail": "johndoe@getbeamer.com",
  "userFirstname": "John",
  "userLastname": "Doe"
}

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"
}

TeamMember: object

email: string

Email address of the team member.

role: string admin, manager, writer, designer, reader, billing

Role for the team member.

Example
{
  "email": "jdoe@getbeamer.com",
  "role": "writer"
}

TeamMemberDeletion: object

email: string

Email address of the team member.

Example
{
  "email": "jdoe@getbeamer.com"
}