API 2.0 Overview – BlueFolder Support

The BlueFolder API is an interface that you can use to programmatically interact with your BlueFolder account. The API is implemented using XML over HTTPS.

Prerequisites

Depending on your BlueFolder Plan the API may or may not be included in your account. Refer to www.bluefolder.com/pricing for more information. To use the API, you must first enable API access for your BlueFolder account. To enable your account for API access, go to Settings > API and click the "Enable my BlueFolder account for API access" checkbox.

Additionally, each user account that will interact with the API must also be enabled for API access. To enable a user account for API access, go to Settings > API, and then add the user you want to enable to the Authorized API Users list.

Authentication

All API requests must be made via SSL over HTTPS. Requests are authenticated to the API using Basic HTTP Authentication .

Each BlueFolder user account has a unique API token, which can be found in the "Authorized API Users" table located in "Settings > API". A user's API token is tied to their password - if the password changes, so will the API token. API Tokens should be guarded just as carefully as a password.

Basic HTTP authentication typically requires a "username:password" pair, but the BlueFolder API only requires a single token as the username so you'll only use the "username" field (just use "X" or any string you prefer as the password). To authenticate your API requests, concatenate your API token and a bogus password together with a colon (e.g. "my-api-token:X"), and then Base64 encode that string. Add the "Authorization" HTTP header to your API request, and sets the header's value to the Base64-encoded string you just created.

Requests must be submitted via HTTPS POST in the following format.

<request>
  request_details
</request>

Successful Requests

A successful request to the API will return the following XML:

<response status="ok">
  response_content
</response>

Failed Requests

A failed request to the API will return the following XML:

<response status="fail">
  <error code="error_code">
    error_message
  </error>
</response>

Data Types

The following data type standards apply when sending values via the API. These are listed by type for reference and apply to all our various API endpoint XML payloads described in this documentation.

Numeric - numbers with no formatting that may not contain a decimal point
Decimal - numbers with no formatting that may contain a decimal point
Boolean - should be passed as string values of "true" or "false" (case does not matter)
Date - should be passed as string value matching format YYYY.MM.DD
Time - should be passed as string value matching format HH:MM AM

API Limits

To prevent degradation to our services we implement an API limit. Our current request limit is 100 requests per minute. If you hit the limit you will receive a response with a 429 status code and a header "Retry-After" that contains the number of seconds until the limit is reset.

A request that exceeds the limits of the API will return headers similar the headers below:

HTTP/1.1 429 Too Many Requests
Content-Type: text/xml; charset=utf-8
Date: Thu, 28 Jul 2022 20:44:28 GMT
Access-Control-Expose-Headers: Request-Context
Cache-Control: private
Retry-After: 60
Request-Context: appId=cid-v1:89d06338-6aaa-4d3c-9c8b-9bd751c6afec

A request that exceeds the limits of the API will return the following XML:

<response status='fail'>
  <error code='429'>
    <![CDATA[Too many requests.
    You have sent too many requests in a given amount of time ("rate limiting").
    You have exceeded your limit for the minute. Try again after 2022-07-28T20:44:28.9180000Z UTC.]]>
  </error>
</response>