Bondora API

Bondora API Introduction

Contents

Environments

Production

API Production environment is located at https://api.bondora.com. 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}.bondora.com/api/{version}/{resource}{additional-parameters}.

Some example Uris for requesting data from API

    Getting list of auctions
    https://api.bondora.com/api/v1/auctions


    Getting auction with specific ID 
    https://api.bondora.com/api/v1/auction/6832dee6-92a3-4d9b-af03-5c53fed0c41d


    Getting list of bids
    https://api.bondora.com/api/v1/bids?bidStatus=1

Versioning

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 https://api.bondora.com/api/v1/resource.

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: 2024-12-09T17:41:11.8993295Z
    Local Date: 2024-12-09T19:41:11.8993295+02:00

Authorization

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 (https://www.bondora.com/oauth/authorize).

OAuth Authorization endpoint

Fist step of the OAuth authorization flow is to redirect the user to the OAuth Authorization (https://www.bondora.com/oauth/authorize) endpoint with following parameters

Scopes - Permissions that you can request from user
Authorization Code Request (GET to OAuth Authorization endpoint)
curl -X GET "https://www.bondora.com/oauth/authorize
    ?response_type=code
    &client_id=ddb0fe442ba74dd19feba9c87faaa02b
    &state=xyz
    &scope=BidsEdit%20BidsRead%20Investments%20SmBuy%20SmSell
    &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb"
Response Redirect Url:
    https://client.example.com/cb?code=ytPbmCg9VREMxkDjS0mnjaGHBXpHaK1A0rXiglwvySkeorKS&state=xyz

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 https://api.bondora.com/oauth/access_token \
    -F grant_type=authorization_code \
    -F client_id=ddb0fe442ba74dd19feba9c87faaa02b \
    -F client_secret=Qe0WkMmXdFE9CINKp5XlK2C9Uumk34msl2LybsXbHbUtz9Dt \
    -F code=ytPbmCg9VREMxkDjS0mnjaGHBXpHaK1A0rXiglwvySkeorKS \
    -F redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
Response JSON:
    {
      "access_token": "UdLrkfwNvqas68a2JvqHG24ChgQykSJp5D2jPGQA0en0zvFu",
      "scope": "BidsRead BidsEdit Investments SmBuy SmSell",
      "token_type": "bearer",
      "expires_in": 3600,
      "refresh_token": QS8uIYapF4q0yJ0aie1KkI8X4vxelO4vXbxd1bhw2ppP8bOV
    }

Access Token for Refresh Token Request (POST to OAuth Token endpoint)
curl -X POST https://api.bondora.com/oauth/access_token \
    -F grant_type=refresh_token \
    -F client_id=ddb0fe442ba74dd19feba9c87faaa02b \
    -F client_secret=Qe0WkMmXdFE9CINKp5XlK2C9Uumk34msl2LybsXbHbUtz9Dt \
    -F refresh_token=QS8uIYapF4q0yJ0aie1KkI8X4vxelO4vXbxd1bhw2ppP8bOV \
    -F redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
Response JSON:
    {
      "access_token": "UdLrkfwNvqas68a2JvqHG24ChgQykSJp5D2jPGQA0en0zvFu",
      "token_type": "bearer",
      "expires_in": 3600
    }

Authentication

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 UdLrkfwNvqas68a2JvqHG24ChgQykSJp5D2jPGQA0en0zvFu
    Where UdLrkfwNvqas68a2JvqHG24ChgQykSJp5D2jPGQA0en0zvFu is the access token generated by the OAuth 2.0 Token endpoint (/oauth/access_token).

Compression

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 different for all endpoints:

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

Webhooks

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

Error tolerance

The POST request that is made to the registered URL is limited by how many error responses can occur. Currently it is limited to 25 errors. This also includes time-out errors. Currently the webhook caller has a time-out of 30 seconds. Make sure your webhook handler is capable of handling the incoming data during this time. If possible, try to process the data asyncronously.

If there are more than 25 errors, the webhook is marked as blocked. In the UI, if you click on the "send test" button and the response is successful, the webhook should be unblocked.

The error count is reset each day. Blocking is not cleared automatically.

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

We have some sample code available on our Github account.

Bondora.Api.Client.Sample.DotNet

Bondora API Sample client written in C# for .NET. Github link.

webhooksample-python

This is a simple Python 3 Flask app that can receive Bondora API's webhook calls.

Also contains a working sample of the HTTP authentication checking. Github link.

REST samples

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

Auctions list example (with access token in header)

curl -X GET "https://api.bondora.com/api/v1/auctions" \
    -H "Authorization: Bearer UdLrkfwNvqas68a2JvqHG24ChgQykSJp5D2jPGQA0en0zvFu"