Bondora API Introduction



API Production environment is located at Production is a LIVE environment!
To get access to the production API, you must first complete bank account identification by making a deposit to Bondoras account.

Uri format

API Uri is formatted as following https://api{-environment}{version}/{resource}{additional-parameters}.

Some example Uris for requesting data from API

    Getting list of auctions
Getting auction with specific ID
Getting list of bids


Bondora API uses versioning to ensure backward compability when breaking changes are introduced to the API. Current API version is v1. We will support max 3 versions of API at the time. When new API version is introduced, previous 2 versions will still work for users. Version is added to the API Uri as following

Request Methods

Currently GET and POST are used as request methods for getting data and posting data to the API. Please consult the API Reference Documentation for selecting correct method for specific API resource. Status code 405 (Method Not Allowed) is returned when using wrong method for the resource.

Status Codes

HTTP Status Codes are used to indicate if the request was successfully processed or it failed with specific error. The response status codes depend on the resource and can vary. Please consult the API Reference Documentation to get the list of response codes for specific resource.

Commonly used status codes:

Accept and Content Types

API supports different request and response data types. The types are specifified by standard HTTP Content Negotiation. To specify the POSTed content format, use the Content-Type header with appropriate value. For response data format, use the Accept header with specific format. When no Accept or Content-Type headers are specified, the JSON format will be used as default.

The API accepts and returns data in following types:

Some resources support additional types:

Response format

All responses are returned with unified data format, including Success, Payload and Errors properties, where Payload is optional when error situation occured.

Successful response example:

        "Payload": {
            "ExampleProperty": "Example data"
        "Success": true,
        "Errors": null

Errors in response data

When error situation is raised (for ex. in case of wrong resource (Uri) format, wrong data format, server processing and etc.) then the error(s) are returned in response data within the Errors property, which is collection of Error objects.

Error response example:

        "Success": false,
        "Errors": [
                "Code": 0,
                "Message": "Error message",
                "Details": "Error description"

Date and Time format

All Date and Time values are formated as ISO 8601.

    UTC Date: 2018-12-13T19:00:23.0474048Z
    Local Date: 2018-12-13T21:00:23.0474048+02:00


Bondora API uses OAuth 2.0 protocol for authentication and authorization.

Before you can begin with the OAuth process, you must first register a new client application at applications page. When registering the app, you must enter the name, description and website address. In addition, you must register a authorizaton callback URI that will be used for redirecting users to from the OAuth Authorization endpoint (

OAuth Authorization endpoint

Fist step of the OAuth authorization flow is to redirect the user to the OAuth Authorization ( endpoint with following parameters

Scopes - Permissions that you can request from user
Authorization Code Request (GET to OAuth Authorization endpoint)
curl -X GET "
Response Redirect Url:

OAuth Token endpoint

For getting the Access Token, you must make a POST request to OAuth Token endpoint with following parameters

Access Token for Authorization Code Request (POST to OAuth Token endpoint)
curl -X POST \
    -F grant_type=authorization_code \
    -F client_id=54b25a55605c4c0c83d17f139477d19c \
    -F client_secret=eNIX9ZHBuun8yJihapgGVn4mt7jYurTyphW4VdbD7OMXryNf \
    -F code=hJxrDYFkPtwyPEBEuKCwUlHPiVWMPC3LXx30TpYOhNq63p1I \
    -F redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
Response JSON:
      "access_token": "lSjGmny1BC3nh7ghRxoQ3wHYemWQUvOmDxdw5HGJSIMg342d",
      "scope": "BidsRead BidsEdit Investments SmBuy SmSell",
      "token_type": "bearer",
      "expires_in": 3600,
      "refresh_token": WLYvWrazg9qVRwe0o3ksjZNUGFXiaNhCtybIGSIU140NWvq8

Access Token for Refresh Token Request (POST to OAuth Token endpoint)
curl -X POST \
    -F grant_type=refresh_token \
    -F client_id=54b25a55605c4c0c83d17f139477d19c \
    -F client_secret=eNIX9ZHBuun8yJihapgGVn4mt7jYurTyphW4VdbD7OMXryNf \
    -F refresh_token=WLYvWrazg9qVRwe0o3ksjZNUGFXiaNhCtybIGSIU140NWvq8 \
    -F redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
Response JSON:
      "access_token": "lSjGmny1BC3nh7ghRxoQ3wHYemWQUvOmDxdw5HGJSIMg342d",
      "token_type": "bearer",
      "expires_in": 3600


After the application has obtained the access token, it must send the token to a API in the HTTP Authorization header as a value Bearer <access_token>. Access tokens are valid only for the set of operations and resources described in the scope of the token request.

    Authorization: Bearer lSjGmny1BC3nh7ghRxoQ3wHYemWQUvOmDxdw5HGJSIMg342d
    Where lSjGmny1BC3nh7ghRxoQ3wHYemWQUvOmDxdw5HGJSIMg342d is the access token generated by the OAuth 2.0 Token endpoint (/oauth/access_token).


Bondora API supports HTTP compression to reduce the response size and so providing faster transfer of the data. To enable response data compression, add Accept-Encoding header with gzip, deflate value(s).

    Accept-Encoding: gzip, deflate

Rate limiting (Throttling)

Request rate limiting aka Throttling is used by API to limit number of requests per second for user. Currently the limit is 1 request per second for unique user. For /oauth/access_token resource, additional throttling of 10 requests per minute is used, so that the authentication would not be misused. If the rate is exceeded, response code 429 (Too Many Requests) is returned. Error is also returned as content. Additionally the Retry-After header is set with the time when the limit ends and user can make another request to the API resource.

Response Header:

    Retry-After: 1

Response Content:

        "Success": false,
        "Errors": [
                "Code": 429,
                "Message": "API calls quota exceeded! maximum admitted 1 per Second.",
                "Details": "Retry after 1"


Use webhooks to be notified about events that happen in a API.

Bondora can send webhook events that notify your application any time a new event happens. This mechanism is useful for services that are not directly responsible for making an API request, but still need to know the response from that request.

Receiving a webhook notification

Creating a webhook endpoint on your server is no different from creating any page on your website. Webhook data is sent as JSON in the POST request body. If response code is not 200, request will be retried multiple times. In some cases, your webhook may receive duplicate events. Your webhook app should be tolerant of this and dedupe by event ID. The full event details are included and can be used directly, after parsing the JSON into an Event object.

Example webhook request:

      "EventId": "15848b4e-ff56-4de3-9b5f-a92e01171453", 
      "EventType": "auction.published"
      "Payload": {
        "LoanId": "9cefa176-e917-4f1a-9629-a92f011265b3",
        "AuctionId": "3035068d-ac57-4e7c-a734-a92f00e0f5b2",
        "LoanNumber": 865878,
        "UserName": "BOK297331",
        "Liabilities": [],
        "Debts": [],
        "BorrowerHistory": {...}
To manage webhooks continue here

Sample code

You can get sample .NET / C# project for Bondora API from Github.

Below you can find some simple samples, how to use the API.

Auctions list example (with access token in header)

curl -X GET "" \
    -H "Authorization: Bearer lSjGmny1BC3nh7ghRxoQ3wHYemWQUvOmDxdw5HGJSIMg342d"