alterest API

Introduction

API Reference

The Alterest API is organized around REST. Our API gives developers and external applications unparalleled access into the alternative lending market. Some of the things you can do are request data on originators, loans available for investment, upload portfolios and access our pricing and risk engines.

To keep it simple, we've designed our API to be predictable, resource-oriented URLs, and use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors (although we're developing our API libraries to help you convert responses to appropriate language-specific objects).

To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no "switch" for changing between modes, just use the appropriate key to perform a live or test call. Requests made with test mode credentials never count as actual transactions on loans.

Usage

Request an API key by emailing support@alterest.co and follow the documentation to start using the Alterest APIs. You can use the API Explorer within this documentation to try the APIs out.

Authentication

Authenticate your account when using the API by including your secret API key in the request. You can manage your API keys in the API section of the Alterest platform. Your API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

To use your API key, pass it to the Alterest module. The Node.js library then will automatically send this key in each request.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Errors

Alterest uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an error with Alterest's servers (these are rare). Not all errors map cleanly onto HTTP response codes, however. When a request is valid but does not complete successfully (e.g., a bid on a loan is declined), we return a 402 error code.

HTTP status code summary

Code Error Summary
200 OK Everything worked as expected.
400 Bad Request The request was unacceptable, often due to missing a required parameter.
401 Unauthorized No valid API key provided.
402 Request Failed The parameters were valid but the request failed.
404 Not Found The requested resource doesn't exist.
409 Conflict The request conflicts with another request (perhaps due to using the same idempotent key).
429 Too Many Requests Too many requests hit the API too quickly.
500, 502, 503, 504 Server Errors Something went wrong on Alterest's end. (These are rare.)

Handling errors

Our API libraries raise exceptions for many reasons, such as a failed charge, invalid parameters, authentication errors, and network unavailability. We recommend writing code that gracefully handles all possible API exceptions.

Objects

The following is a description of the main type of objects returned by the Alterest API.

Originator object

{
  "id": "org_980Vjlj78v123klmvbC6hfak",
  "timestamp": 1462123988815,
  "object": "originator",
  "name": "Demo Originator",
  "type_of_loans": ["consumer", "business"],
  "funding_mechanism": ["balance sheet", "marketplace"],
  "historical_loan_origination": {
    value: 10000000,
    currency: "gbp",
    timestamp: 1462123988815
  },
  "indicative_loan_durations": [
    {
      unit: "month",
      values: [3, 6, 9]
    },
    {
      unit: "year",
      values: [1, 2, 3]  
    }
  ],
  "flexible_loan_duration": true,
  "operative_countries": ["United Kingdom", "Spain"],
  "description": "Flexible, online working capital and project finance solution.",
  "founded": 2010,
  "contact": {
    "phones": ["+442078456746","+344124566345"],
    "emails": ["contact@demooriginator.com"],
    "addresses": ["4-5 Bonhill Street, London EC2 3BX"]
  },
  "headquarters": "United Kingdom",
  "employess": "50-100"
}

Loan object

{
  "id": "lon_980Vjlj78v123klmvbC6hfak",
  "object": "loan",
  "originator_id": "org_980Vjlj78v123klmvbC6hfak",
  "issue": 1451606400000,
  "maturity": 1514764800000,
  "principal": {
    "currency": "gbp",
    "value": 100000
  },
  "bidding": {
    "alive": true,
    "unbid_principal": ,
    "bidding_process": ,
    "running_rates": {
      "high": 0.085,
      "low": 0.075,
      "frequency": "per annum"
      },
    "alterest_suggested_rate":{
      "rate": 0.08,
      "frequency": "per annum"
    },
    "alterest_view": "neutral",
    "timestamp": 1462123988815
  },
  "interest_payment_frequency": {
    "value": 3,
    "unit": "months"
  },
  "sector": "business",
  "collaterlized": true,
  "collateral_id": "col_980Vjlj78v123klmvbC6hfak"
}

Order object

{
  "id": "ord_980Vjlj78v123klmvbC6hfak",
  "object": "order",
  "user_id": "usr_980Vjlj78v123klmvbC6hfak",
  "timestamps": {
    "first_submit": 1462123988815,
    "updated": null
  },
  "portfolio_id": "pfo_980Vjlj78v123klmvbC6hfak",
  "bid_ids": [
    "bid_980Vjlj78v123klmvbC6hfa1",
    "bid_ljsadf98q349987jkhdf8782",
    "bid_987345jksdhkjfg783465s73",
    "bid_08sdfjk3457hjsdf78yhjkf4",
    "bid_345nksdugiusfgn489sds345",
    "bid_098435jlksdf934idsf9lk4d6",
    "bid_908asdfkjh347sdfkhj7834f7"
  ]
}

Bid object

{
  "id": "bid_980Vjlj78v123klmvbC6hfak",
  "object": "bid",
  "loan_id": "lon_980Vjlj78v123klmvbC6hfak",
  "user_id": "usr_980Vjlj78v123klmvbC6hfak",
  "timestamps": {
    "first_submit": 1462123988815,
    "updated": null,
  },
  "bid_amount": {
    "value": 10000,
    "currency": "gbp"
  },
  "bid_rate": {
    "value": 0.08,
    "frequency": "per annum"
  }
}

Portfolio object

{
  "id": "pfo_980Vjlj78v123klmvbC6hfak",
  "object": "portfolio",
  "loans": [
    {
      "id": "lon_980Vjlj78v123klmvbC6hfak",
      "principal_held": 100000,
      "currency": "gbp",
      "bought_timestamp": 1462123000000,
      "purchase_status": "complete",
      "pv_future_cashflows": {
        "value": 95000,
        "currency": "gbp",
        "timestamp": 1462123988815
      },
      "past_cashflows": [
        {
          "values": 2000,
          "currency": "gbp",
          "timestamp: 1462123450000
        },
        {
          "values": 2000,
          "currency": "gbp",
          "timestamp: 1462123900000
        }
      ]
    },
    {
      "id": "lon_8934hkjasd8f4hid8hiuhd84",
      "principal_held": 20000,
      "currency": "gbp",
      "bought_timestamp": null,
      "purchase_status": "filling",
      "present_value": null
    }
  ]
}

Account object

{
  "id": "acc_980Vjlj78v123klmvbC6hfak",
  "object": "account",
  "kyc_aml_complete": true,
  "first_name": "John Pierpont",
  "last_name": "Morgan",
  "company_name": "Demo Investor",
  "address": "5 Bonhill Street, London EC2A 4BX"
}

Collateral object

{
  "id": "col_980Vjlj78v123klmvbC6hfak",
  "object": "collateral",
  "asset_type": "property",
  "details": {
    "address": "1 Hyde Park, London SW1X 7LJ
",
    "valuation": {
      "value": 1000000,
      "currency": "gbp",
      "timestamp": 1462123988815
    }
  }
}

Support

We're a young company and we're trying hard to keep this documentation comprehensive and easy to follow. But we recognize that this is a work in progress. At any time you have a question, please send an email to support@alterest.co or use the in-product chat support.

Versioning

When we make backwards-incompatible changes to the API, we release new, dated versions. The current version is 2016-03-07. Read our API upgrades guide to see our API changelog (both coming soon) and to learn more about backwards compatibility.

All requests will use your account API settings, unless you override the API version. The changelog lists every available version. Note that events generated by API requests will always be structured according to your account API version. To set the API version on a specific request, send a Alterest-Version header.

You can visit your API section of the Alterest platform to upgrade your API version. As a precaution, use API versioning to test a new API version before committing to an upgrade.