Getting started

The Bloomfire platform has an ever-growing API for externally interacting with the content and information in your Bloomfire communities. This site provides information about the Bloomfire platform, documents the available API calls, and provides usage examples to allow developers like you to develop Bloomfire integrations.

The documentation is written for a developer that has some experience working with REST-based APIs.

The API is being expanded to support greater functionality. We hope you enjoy the upgrades and welcome your feedback. Bookmark this API documentation for up-to-date support.

Terminology

The following table provides a description of Bloomfire terminology used throughout the documentation.

Term Description
Organization A single Bloomfire community. If you have a master community and subcommunities, each one is treated as an organization.
User A Bloomfire user account is tied to an email address, which uniquely identifies that user across all related organizations. However, users may have different levels of access within each subcommunity and are assigned separate member IDs for each organization, which are the IDs returned by the API.
Role The set of user permissions for accessing Bloomfire. For more information, see user roles.
Contribution Any type of content created by members in Bloomfire with the intention of sharing it with the community. This includes posts, questions, series, answers, and comments.
Post A contribution type created by a member or a group of members (co-authors) containing either text or media to be shared with the community.
Series A contribution type created by a member containing an ordered list of posts.
Question A contribution type created by a member that contains a question to the community.
Answer A contribution type created by a member in response to a specific question. An answer contains either text or media data.
Comment A contribution type containing text that is created by a member in response to an existing post, question, answer, or comment.
Keyword A keyword or tag is a user-specified label that improves the organization and searching of content.
Category A keyword or tag is a user-specified label that improves the organization and searching of content. Categories can only be defined by an admin or owner.
Featured A piece of content (post, question, series) promoted to the Featured section of the homepage.

Throughout this documentation, we use an ellipse as shorthand for the domain where your Bloomfire resides. So https://COMPANY.bloomfire.com/api/v2/ becomes .../api/v2/.

Public vs. Private

By default, content within Bloomfire is accessible only to members of the community. To access this private data via the API, you must use a session token.

However, you can choose to make all content publicly searchable by changing the Public Access settings under Gear > Communities > Settings (Admins/Owners only). Individual pieces of content can then be set public or private.

While a piece of content may be set to public, certain fields may still be suppressed. Details regarding specific fields can be found in the documentation for those content types.

User roles

In order to simplify the administration of Bloomfire permissions, a set of functionality is rolled up under a user role. User roles are assigned to each member in an organization. A member can have the Learner role in one organization and the Author role in another.

The user role grid provides a list of API functionalities and the role that can execute each functionality. If public content is enabled for the organization, a non-member has read access to a subset of the content provided in an organization, but has no permissions to contribute content.

Bloomfire roles Learner Author Admin Owner
View content and member profiles Yes Yes Yes Yes
Search contributions and profiles Yes Yes Yes Yes
Update personal profile Yes Yes Yes Yes
Ask a question (if Q&A enabled) Yes Yes Yes Yes
Contribute a comment Yes Yes Yes Yes
Use Hi-Five Yes Yes Yes Yes
Answer a question (if Q&A enabled) Yes Yes Yes
Contribute a post Yes Yes Yes
Manage public content (if public enabled) Yes Yes Yes
Publish a post to multiple organizations Yes Yes Yes
Contribute a series Yes Yes
Manage featured content (if featured enabled) Yes Yes
Manage categories Yes Yes
Manage members Yes Yes
Edit or delete any contribution or user profile Yes Yes

Data types

The response for each API request is returned in JSON format. The data types used in the response are described in the chart below.

API v2 no longer supports XML as the response format.

Type Description
string Character string in UTF-8
integer 32-bit signed integer
boolean True or False
timestamp ISO datetime (e.g. YYYY-MM-DD-HH-MM-SS_TIMEZONE)

Data structures

The following table describes the Bloomfire data structures accessible through this API.

Content type API route
Organization .../api/v2/organizations[/id]
User .../api/v2/users[/id]
Login .../api/v2/logins[/id]
Post .../api/v2/posts[/id]
Series .../api/v2/series[/id]
Question .../api/v2/questions[/id]
Answer .../api/v2/answers[/id]
Comment .../api/v2/comments[/id]
Keyword .../api/v2/keywords[/id]
Category .../api/v2/categories[/id]
Featured .../api/v2/featured

Accessing data

Use the above RESTful style API routes to access Bloomfire data structures. Here are GET and POST examples for working with user objects:

GET https://COMPANY.bloomfire.com/api/v2/users

Similarly, you create a new user by passing the following request (plus a JSON-formatted form body with additional parameters):

POST https://COMPANY.bloomfire.com/api/v2/users

Single instances

When you request a data type, you receive all instances of this data type. To limit the response to a specific instance, you use the format .../api/v2/OBJECT_NOUN/OBJECT_ID, as in:

GET .../api/v2/users/105

This returns the record for user with id 105. The next section shows you how to drill down into related content. You can also see how to restrict which fields are returned further below.

Chaining object nouns

A helpful feature is the ability to drill into object relations by chaining several nouns. For example, say you query a question with id 917 and then want to view its answers. You can do so like this:

GET .../api/v2/questions/917/answers

Chaining is restricted to one level deep. If you see that an answer with id 55 has several comments, for example, you cannot chain from question to answer to comments. Instead, you must drop down to the answer and chain to its comments:

GET .../api/v2/answers/55/comments

Data fields

The fields or parameters associated with each data structure are defined in the documentation for those objects. However, here are general tips for working with fields in your requests.

Filtering fields

The API request returns the response as an object with appropriate parameters and values. The API allows you to restrict the fields returned by inserting a comma-separated list of fields into the request: &fields=FIELD_1,FIELD_2,FIELD_3.

For example, if you want to receive only session tokens and organization details for a particular user, use the following request:

GET .../api/v2/users/logins?
email=user@email.com&
password=passw0rd&
fields=session_token,organization

Return JSON: Only session token and organization data for all organizations matching user email address

The request returns a list of all session tokens and organizations for this particular user:

[
    {
        "session_token": "s4goqi8qiukfwhpfcua57vw3p6udf4teycr6zw65yxunka72kjwa3ijb",
        "organization": {
            "id": 8534
        }
    },
    {
        "session_token": "s4goqi8qiukfwhpfcua57vw3p6udf4teycr6zw65yxunka72kjwa3ijb",
        "organization": {
            "id": 7530
        }
    },
    {
        "session_token": "qm3qcf22q2vugkkume7bsm4u9zqysu3ej753q9xpd8shwe8hmneiwmd9",
        "organization": {
            "id": 9157
        }
    }
]

Viewing additional fields

Bloomfire content is highly inter-related – a user has posts, which have comments, which have authors, who have their own posts, etc. By default, only the id field is returned for related objects. If you want to see additional fields, though, simply specify them in the fields parameter as we did above.

Look back at the chaining example. Chaining is restricted to one level, but by looking at the documentation for comments, we can retrieve additional info about these comments:

GET .../api/v2/questions/917/answers?
fields=id,comments(id,comment)

Return JSON: Digging into the comments linked to this answer

{
    "id": 55,
    "comments": [
        {
            "id": 128,
            "comment": "Wow! that worked well!"
        },
        {
            "id": 129,
            "comment": "It did?"
        },
        {
            "id": 198,
            "comment": "Woo"
        }
    ]
}

We have requested the id field of the root object and any nested comments, as well as the comment (text) field of those comments. Notice that the root object id is 55 (the answer), not 917 (the question). By chaining from question to answer, we no longer have visibility into the question. However, by requesting nested fields, we can see information about both the root object and its nested relations.

Your first API call

Only API requests matching the supported authentication generate return responses. To quickly get started using the Bloomfire Platform API, follow these steps to make your first API call.

Step 1: Generate API key

The API key is one form of the authentication the Bloomfire Platform API supports to execute requests. A unique API key can be generated for each organization in the Settings page, which is accessible only to the Owner role. If you do not have access to this page, please ask the Owner of your organization to provide the API key.

Follow these steps to generate the API key for the organization:

  1. Log in to Bloomfire with the Owner role.
  2. Click the Gear icon.
    gear icon
  3. In the drop-down menu, go to Settings.
    settings
  4. On the Settings page, in the Miscellaneous section, turn on the Enable API access setting, and then refresh the page.
    Enable API access
  5. On the refreshed Settings page, in the Miscellaneous section, the API key appears.
    API key

To generate a new API key, click New Key, and then click Yes in the confirmation message.

Step 2: Get session token

The session token is another form of authentication within the Bloomfire Platform; it is uniquely tied to a user in the organization and enables access to non-public data. A session token is generated using the API key or the user email and password. Both methods are described below.

All requests should be made using an SSL protocol. All requests made with plain HTTP are changed to HTTP with SSL.

Option 1: Session token for current organization using API key

GET https://start.bloomfire.com/api/v2/login?
email=user@email.com&
api_key=1234abcd5678efg90123456hijkl7890mn12opq
Code Description
COMPANY Subdomain of the organization
email Email for the user’s Bloomfire login
api_key API key for the organization generated in previous step

Option 2: Session token for current organization using a user password

GET https://start.bloomfire.com/api/v2/login?
email=user@email.com&
password=passw0rd
Code Description
COMPANY Subdomain of the organization
email Email for the user’s Bloomfire login
password Password for the user’s Bloomfire login

Return JSON: Session token for current organization

A successful request returns the session token plus other details in JSON format:

[
    {
        "session_token": "23cb56657a02611b7f636f0d85056eacf0e3f753ee09eedae7d8eb7316e9198f",
        "organization": {
            "id": 639
        },
        "user": {
            "id": 753
        }
    }
]

If a user is a member of more than one organization, you can make a request to return the session tokens for all organizations. To do this, use logins, instead of login when submitting the request.

Option 1: Session tokens for all user organizations with the API key

GET https://start.bloomfire.com/api/v2/logins?
email=user@email.com&
api_key=1234abcd5678efg90123456hijkl7890mn12opq

Option 2: Session tokens for all user organizations with the user password

GET https://start.bloomfire.com/api/v2/logins?
email=user@email.com&
password=passw0rd

Return JSON: Session token for all organizations matching user email address

The request returns a list of all session tokens for each corresponding organization along with the user id:

[
    {
        "session_token": "23cb56657a02611b7f636f0d85056eacf0e3f753ee09eedae7d8eb7316e9198f",
        "organization": {
            "id": 639
        },
        "user": {
            "id": 8534
        }
    },
    {
        "session_token": "s4goqi8qiukfwhpfcua57vw3p6udf4teycr6zw65yxunka72kjwa3ijb",
        "organization": {
            "id": 258
        },
        "user": {
            "id": 7530
        }
    },
    {
        "session_token": "s4goqi8qiukfwhpfcua57vw3p6udf4teycr6zw65yxunka72kjwa3ijb",
        "organization": {
            "id": 473
        },
        "user": {
            "id": 9157
        }
    }
]

Step 3: Make API call

Practice making your first API call by returning all your profile information using your session token. The following request pulls all user information for the corresponding session token used.

GET https://COMPANY.bloomfire.com/api/v2/users/me?
session_token=w56kkf7bw3poic36ckmgb8vbrtjgf73gbd7a45fwjryvytay288yuhxv
Code Description
COMPANY Subdomain of the organization
session_token Unique authentication token corresponding to a user within an organization

Return JSON: Details of the user associated with the session token

If the request is successful, the response returns in the following format:

{
    "likes": [
        {
            "id": 263
        },
        {
            "id": 333
        }
    ],
    "followed": true,
    "followers_count": 1,
    "following_count": 1,
    "comments_count": 7,
    "views_count": 40,
    "email": "user@email.com",
    "id": 1111,
    "role": "admin",
    "active": true,
    "posts_count": 6,
    "series_count": 1,
    "questions_count": 5,
    "answers_count": 5,
    "first_name": "John",
    "last_name": "Smith",
    "bio": "The first member of this community",
    "title": "sir",
    "company": "The Great Company",
    "created_at": "2013-07-24T23:05:20-09:00",
    "updated_at": "2013-08-15T03:13:09-09:00"
}

If you have gotten this far, congratulations on making your first API call!

The rest of the examples used in the documentation follow a similar format.

Throughout the documentation, it is assumed that the session token is passed as a parameter with most requests.

Error codes

If you were unsuccessful, here are some of the error codes you might have encountered with suggestions on what could be wrong with your request.

Error code Error description Comment
404 Unable to find user This means the user does not exist within this organization.
401 Authentication failed – invalid api_key The API key being used is not valid.
401 Invalid request, missing api_key or password parameter You are missing the API key, this is required to run this request.

If you make a request with a role that does not have necessary permissions, the following error returns:

Error code Error description Comment
401 Insufficient permissions This user does not have permission to execute this action.

In cases when the feature is not available or not enabled for your community, the following error returns:

Error code Error description Comment
403 Feature unavailable for this organization This feature is not enabled for your community.

Now, check out the rest of the API possibilities and have fun!