Privacy Bee offers enterprise-grade privacy controls via our secure, stateless, and RESTful API. Requests are made with predictable verbs and form-encoded request bodies, while responses are JSON-encoded with standard HTTP response codes.

The following documentation details the implementation of Privacy Bee’s API.

Quick Start Overview

The Base URL for all requests can be found on the API Keys page next to the OAuth clients table: https://api.privacybee.com/v3/companies/{id} (unless your contract or SLA instructs you to use an alternative).

Requests sent via HTTP will be automatically upgraded to HTTPS (SSL required). We recommend all requests include the Keep-Alive header for increased efficiency.

URL Endpoints and Header Variables: These are case insensitive, meaning that it doesn’t matter whether you use uppercase or lowercase letters; the server will interpret them as the same. For example, HTTP://API.PRIVACYBEE.COM/ENDPOINT is equivalent to http://api.privacybee.com/endpoint. It is also styled using dash-notation (also known as kebab-case), where words are separated by dashes, like user-profile or access-token.

Form Variables: In contrast, form variables are case sensitive, which means that the server distinguishes between uppercase and lowercase letters. If a variable is expected to be in lowercase, sending it in uppercase could result in an error. Additionally, these variables are styled in underscore notation (also known as snake_case), where words are separated by underscores, such as first_name or account_id.

Request Authentication

The Privacy Bee API is structured where a user authenticates via OAuth 2.0, obtains an access token, and uses that token for all requests. If the request is user-specific, it’ll operate under the authenticated individual’s account. If the request is for something broader, like a Business Setting, the authorized user will require the appropriate roles for access to those resources.

Please reference Privacy Bee’s API Authentication page for additional details.

Any request lacking proper authentication will be denied, resulting in an HTTP 401 Not Authorized status code.

Rate Limit

API clients have a default rate limit of 200 Requests Per Minute (RPM), and upon hitting the cap, requests will be denied until the next request period begins (the next minute). To help maintain visibility into your current rate limit utilization, all successful requests will include these HTTP Response Headers:

Upon exceeding the limit, all requests will fail with an HTTP/429 Too Many Requests status code and a “X-Rate-Limit-Retry-After” header field indicating the number of seconds until the next request period begins.

Compatibility

In order to extend the lifetime of the API, all routes will always maintain the return values that exist, but we reserve the right to add additional data to any route as we deem necessary. So it is possible that the returns will change and include more data, however we will never remove data from a return to maintain compatibility now and in the future.

Error State

If any request is authenticated properly, but does not have proper URL structure, invalid or missing parameters, is accessing restricted functionality, or any other general failure occurs, the request will return an HTTP/400 Bad Request status code.

If a request cannot be processed due to an ephemeral technical failure on Privacy Bee’s end, the request will return an HTTP/500 Internal Server Error status code. Please try this request again later, or contact support if it persists.

All requests, including errors, will count against your rate limit.

{
  "error": {
    "code": "400",
    "message": "Bad Request: The request cannot be fulfilled due to bad syntax."
  }
}

{
  "error": {
    "code": "401",
    "message": "Unauthorized: Access is denied due to invalid credentials."
  }
}

{
  "code": 429,
  "message": "Too Many Requests",
  "details": "You have exceeded the rate limit for requests. Please try again later."
}

{
  "error": {
    "code": "500",
    "message": "Internal Server Error: An unexpected condition was encountered."
  }
}

Pagination

Any request that returns a list of items, such as listing employees or listing exposures, includes support for pagination variables.

Parameters:

Return: If the result set supports pagination, these variables will be included in the meta response object:

{
    "data": [... ],
    "meta": {
       "total" => 575,
       "per_page" => 1,
       "current_page" => 100,
       "from": 1,
       "to": 100,
       "last_page": 5
    },
    "query_id": "c485ee09-d394-4434-802a-4c025aa6adda",
    "response_time": 42,
    "api_version": 3
}

Note: API documentation might not illustrate pagination across all examples, but if a result set array is returned, pagination is supported.

Have Questions or Need Help?

We’re obsessed with making you successful! Don’t hesitate to reach out anytime via any of our Partner API Support Channels.