Working with API

Sending requests

All requests are sent via HTTPS using GET or POST by API url (found in your account integration parameters). All parameters are passed as GET or POST parameters. Default method is GET.

Authentication and tokens

To authenticate with API, an access token should be passed with each query (found in integration parameters).

Access token expires by default after 2 weeks, so you will need to receive a new one when it does. To automate this, you can use auth.refreshTokens method to receive new access/refresh token pair.

Common parameters

Response

All API responses are json encoded. A response is an object with two fields, one of each is always 'success' or 'error', and the second one, if present, is 'warning'.

Success fields are described in method specification. Warning field contains two fields, 'warningMessage' and 'warningCode'.

Please note that, although warning is not an error, it is a sign that something could be wrong with the query, so you should always check for warningMessage and warningCode in reply, log it and take appropriate actions.

Example

Methods

Offers

offers.create

Create an offer for a new loan. Please note that organizationall offers you have received as a result of invoking this method should be either accepted or declined in 1 hour or less, or they will be declined automatically by system.
Offers.create returns updatedDatetime which you should always record as it was returned, since you will use it later during reconciliation.

Sandbox version of this method does not use production calculations and instead performs some random (but repeatable) calculation on your applicationFields. It means that decision and fee are meaningless and are always the same for the same loan. If you want to test both willParticipate values, just change any input value within allowed ranges (i.e. income) in applicationFields until result changes as you like.
The nature of this calculation also results in wildly differing results even when introducing most subtle changes. This is to be expected.

offers.accept

Accept previously received offer.
Offers.accept returns updatedDatetime which you should always record as it was returned, since you will use it later during reconciliation.

offers.decline

Decline previously received offer.
Offers.decline returns updatedDatetime which you should always record as it was returned, since you will use it later during reconciliation.

offers.cancel

Cancel previously accepted offer. Please note that offer cancellation should only be used in special cases, e.g. when user cancels an approved loan, so underlying accepted offer should be cancelled.
Offers.cancel returns updatedDatetime which you should always record as it was returned, since you will use it later during reconciliation.

Data sending

data.sendApplications

Send loans data. See schedule in Bulk loan data export section.

data.sendRepayments

Send repayments data. See schedule in Bulk loan data export section.

Collateral

collateral.getRelevantPortfolio

Returns latest (if it was successfully generated during current week) collateral markup i.e. updated set of loans that are pledged to investors in accordance to collateral agreements.

{
    "success":  {
        "ready":  true,
        "relevant": [
           {"loanId": "12345", "flici": "12345", "investorId": "24"},
           {"loanId": "22345", "flici": "22345", "investorId": "25"},
           {"loanId": "32345", "flici": "22345", "investorId": "25"},
           ...
        ]
    }
}
                

collateral.getRetainedPortfolio

Returns a part of latest collateral markup containing only loans that were present in previous markup and retained their pledge status.

{
    "success":  {
        "ready":  true,
        "retained": [
           {"loanId": "12345", "flici": "12345", "investorId": "24"},
           {"loanId": "22345", "flici": "22345", "investorId": "25"},
           {"loanId": "32345", "flici": "22345", "investorId": "25"},
           ...
        ]
    }
}
                

collateral.getLeftPortfolio

Returns only loans that were present in previous collateral markup update but left current markup, so that they are not pledged anymore.

{
    "success":  {
        "ready":  true,
        "left": [
           {"loanId": "12345", "flici": "12345", "investorId": "24"},
           {"loanId": "22345", "flici": "22345", "investorId": "25"},
           {"loanId": "32345", "flici": "22345", "investorId": "25"},
           ...
        ]
    }
}
                

collateral.getLastUpdateDate

Returns date of latest markup update in Y-m-d format. Useful for automated checks whether a new markup has been generated.

{
  "success": "2017-07-03"
}
                

Portfolio

portfolio.reconcileDirectCessionTransactions

Reconcile cession transaction on loans bought by Blackmoon investors, for all time. If any discrepancies detected, Blackmoon tech support should be contacted and discrepancies removed.

Please note that we need some time after receiving your data to process it, so the cession transactions might not be ready to reconcile just yet. If that is the case, the API will reply that it is not ready yet and you should retry this request 1 hour later, and again until you receive ready = true in reply.

portfolio.getReverseCessionTransactions

Get full list of loans Blackmoon investor sell back to originator, for all time.

Auth

auth.refreshTokens

Refresh both access and refresh tokens.

Misc

ping

Helper method which replies with a message 'pong', current server date and all parameters that you have sent. Useful to perform connectivity checks and debug tricky parameters.

Error and warning codes

Error codes

Warning codes

Integration using DB replica

API limitations

API integration has some natural limitations that affect daily batch data sending.

“Pushing” information instead of “pulling”

To perform information update, Originator must explicitly invoke Blackmoon API method, so Blackmoon cannot perform manual data checks without asking Originator to resend some of the data. This complicates integration process and requires additional resources to be provided for maintenance afterward.

Additional layer of entities and services meaning additional points of failure

API services, cronjobs, internal middlewares for temporary information storage have to be maintained and monitored both for being functional and for storing consistent amounts of data. Many times we faced the issues with incomplete batches generation, for example, daily loans batch arrives in a consistent state while repayments arrive only partially due to some middleware memory limit being reached.

Changes to DB information storage must be reconciled against API requests generation

To create API request Originator must “prepare” DB-stored information to be sent to Blackmoon. This means that all changes in information storage must be “reconciled” and checked against compatibility with such preparations. Often there are situations where subtle changes in DB are not being translated to API request generation mechanisms and that in turn causes API requests to change unpredictably. In such cases, this gets noticed on the analytical level after some time.

Shared responsibility in case of errors

If something is wrong with the data exchange, both sides spend resources for investigations, meaning 50% loss of effort in general. If the process is majorly owned by one party that leaves very high probability that only this party should investigate the issue.

DB interaction

The factors above led us to create a new form of integration - using a restricted DB replica that Blackmoon can access and pull data from. Such replica should:

• be accessible through secure VPN connection, without Internet-facing ports
• be restricted to a read-only user for Blackmoon
• contain only agreed set of tables and fields that in the case of API integration would be sent in data.send-methods
• be regularly updated/replicated from production DB of the Originator. Replication mechanisms of modern DBs are very robust and tend to “just work”, and require near-zero maintenance
• occupy a separate set of resources (VM/VPC/physical host) so in a case of high load it would not affect production DB performance
• contain general-purpose indexes in tables for quick querying

In general, this DB should contain two tables “loans” and “repayments” connected through loanId entity.

If such DB is accessible for Blackmoon, all interactions for data gathering are simplified and fall onto Blackmoon team. Blackmoon creates and maintains data grabbing services, handles mapping, monitors changes. That eliminates the need for implementation of data.send-API methods by Originator and consequently speeds up integration process.

Compliance documents