Bondora API Introduction


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/b6d307e9-ef04-4109-b5ab-1d93b3676e7e
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: 2018-02-24T05:47:42.7826938Z
    Local Date: 2018-02-24T07:47:42.7826938+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 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=c9d056fdbf624a858c78f426222b2e43
    &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=T5yQHdiPE56bDxu2Dwii6CSd5dTQVNa5ePvsxWsw8VbYHS1w&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=c9d056fdbf624a858c78f426222b2e43 \
    -F client_secret=SO3En2Q47f30LRiXbJGn6AQ8UnxQkQCqmKvM1RWSW7x5fevY \
    -F code=T5yQHdiPE56bDxu2Dwii6CSd5dTQVNa5ePvsxWsw8VbYHS1w \
    -F redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
Response JSON:
    {
      "access_token": "ikPgfx6Yfpt08T6HWOlvf0m2k4QwJXHUXcq1APlmVkYdsmSj",
      "scope": "BidsRead BidsEdit Investments SmBuy SmSell",
      "token_type": "bearer",
      "expires_in": 3600,
      "refresh_token": Io4ns9b8Lj96eZCryUb0VBJpdG0AhaEk6Isus20QDaCiv0Y9
    }
    


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=c9d056fdbf624a858c78f426222b2e43 \
    -F client_secret=SO3En2Q47f30LRiXbJGn6AQ8UnxQkQCqmKvM1RWSW7x5fevY \
    -F refresh_token=Io4ns9b8Lj96eZCryUb0VBJpdG0AhaEk6Isus20QDaCiv0Y9 \
    -F redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
Response JSON:
    {
      "access_token": "ikPgfx6Yfpt08T6HWOlvf0m2k4QwJXHUXcq1APlmVkYdsmSj",
      "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 ikPgfx6Yfpt08T6HWOlvf0m2k4QwJXHUXcq1APlmVkYdsmSj
    Where ikPgfx6Yfpt08T6HWOlvf0m2k4QwJXHUXcq1APlmVkYdsmSj 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 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"
            }
        ]
    }
    

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 "https://api.bondora.com/api/v1/auctions" \
    -H "Authorization: Bearer ikPgfx6Yfpt08T6HWOlvf0m2k4QwJXHUXcq1APlmVkYdsmSj"