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.
API Uri is formatted as following https://api{-environment}.bondora.com/api/{version}/{resource}{additional-parameters}
.
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
Bondora API uses versioning to ensure backward compability when breaking changes are introduced to the API. Current API version is v
.
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
.
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.
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.
200 (Success)
The request was successfully processed202 (Accepted)
The submitted data was successfully accepted, but it might take time to process the data400 (Bad Request)
Expected data or parameter is not provided, is in wrong format or request size is too big401 (Unauthorized)
The Authorization Token is not provided or the Token is not valid anymore403 (Forbidden)
User is not allowed to access or modify the resource404 (Not Found)
Data with specified parameters or the resource is not found405 (Method Not Allowed)
Request method (GET
, POST
, DELETE
, PUT
, etc.) is not allowed for the resource409 (Conflict)
There is conflict with the data provided415 (Unsupported Media Type)
Content-Type for request is not supported429 (Too Many Requests)
There are too many requests made in time frame. See Throttling section for more information.500 (Internal Server Error)
There was an unexpected error when processing the request
API supports different request and response data types. The types are specifified by standard HTTP Content Negotiation.
To specify the POST
ed 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.
application/x-www-form-urlencoded
- URL encoded format as request content-type is supported by some resources. See the API Reference Documentation for more information.text/csv
or text/plain
- Some of the API resources support CSV as output content-type format. See the API Reference Documentation for more information.
All responses are returned with unified data format, including Success
, Payload
and Errors
properties, where Payload
is optional when error situation occured.
{ "Payload": { "ExampleProperty": "Example data" }, "Success": true, "Errors": null }
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.
{ "Success": false, "Errors": [ { "Code": 0, "Message": "Error message", "Details": "Error description" } ] }
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
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).
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
client_id
- Client application identifierscope
- List of scopes (operations and resources) that app is requesting access to (separated by space)response_type
- Must always be code
redirect_uri
- Optional, if not specified the redirect uri from app registration is usedstate
- Optional, can be used by client app to maintain state between request and callbackInvestments
- Allow to view user's investment list and detailsBidsRead
- Allow to view user's auction bid(s)BidsEdit
- Allow to create or cancel aution bid(s)SmSell
- Allow to sell investments in Secondary MarketSmBuy
- Allow to buy investments from Secondary MarketReportCreate
- Allow to create new report(s)ReportRead
- Allow to view user's created report items and report detailscurl -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
For getting the Access Token, you must make a POST
request to OAuth Token endpoint with following parameters
grant_type
- Grant type for getting the access token
authorization_code
for exchanging the token for the code, set the valuerefresh_token
for getting access token for refresh tokenclient_id
- Identifies the client that is making the request. The value passed in this parameter must exactly match the value in the registred Applicationclient_secret
- The client secret that is created for the Applicationcode
- Code that was returned from the OAuth Authorize step. Used when requesting token for exchange of authorization coderefresh_token
- Refresh token that was returned in token response for exchange of code. Used when requesting token for exchange of authorization coderedirect_uri
- Optional, if set, must be the same as the provided in the OAuth Authorize step
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 }
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 }
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).
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
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.
Retry-After: 1
{ "Success": false, "Errors": [ { "Code": 429, "Message": "API calls quota exceeded! maximum admitted 1 per Second.", "Details": "Retry after 1" } ] }
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.
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.
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.
{ "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
We have some sample code available on our Github account.
Bondora API Sample client written in C# for .NET. Github link.
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.
Below you can find some simple samples, how to use the API using simple REST calls.
curl -X GET "https://api.bondora.com/api/v1/auctions" \ -H "Authorization: Bearer UdLrkfwNvqas68a2JvqHG24ChgQykSJp5D2jPGQA0en0zvFu"