Package: lenddo
Python Lenddo API ClientTable of ContentsIntroductionInstallationManual InstallationGeneral UsageExample: Requesting one of your application's Lenddo ScoreExceptions and Error HandlingSubmitting Applications to Lenddo: Using the API Client as a White Label SolutionThe PartnerToken API callThe CommitPartnerJob API callRequesting Results from LenddoScoresVerification ResultsIntroductionThelenddo_api_clientpython module provides the classLenddoAPIClient,
a generic interface to all the Lenddo HTTP APIs. The client makes authenticated HTTP requests
using the HMAC-SHA1 signing method.InstallationTo install our client usepip:$ pip install lenddoVersion1.1.0supports both python2.7.xand python3.x.
If any bug is encountered kindly report the issuehere.Manual InstallationThe python Lenddo API client library has no third-party dependencies. The only installation
step is to copy and drop the directorylenddo_api_client/into a directory in yourPYTHONPATH. The client has
been tested with python versions2.7.xand3.6.x.General UsageIn order to make API calls, first instantiate aLenddoAPIClientinitialized
with your API id, your API secret, the base URL of the API resource you intend to use. You
may then make HTTP requests using the client'sget,post,put,deleteandoptionsmethods, which are named after the respective HTTP methods. Arguments to
these methods take the form(resource-type, resource-id, parameter-dictionary):resource-typedescribes the resource being requested (for exampleApplicationScore,PartnerToken)resource-ididentifies the specific instance of the requested resourceparameter-dictionarycontains additional parameters supported by the call.
In the case of a GET request, these are converted to the request query string. In a POST
or PUT request, they are JSON-encoded and submitted as the request body.Optionally, you can useproxieswhen connecting to external services.Example: Requesting one of your application's Lenddo ScoreIn this example we make a GET request to theApplicationScoreAPI to obtain the score for a
application with idexample-application.ApplicationScoreis hosted atscoreservice.lenddo.com.Request a Lenddo score with the LenddoAPIClientfromlenddo_api_clientimportLenddoAPIClientclient=LenddoAPIClient('your-api-client-id','your-api-client-secret','https://scoreservice.lenddo.com')response=client.get('ApplicationScore','example-application')This results in a signed HTTP GET request tohttps://scoreservice.lenddo.com/ApplicationScore/example-application.Request a Lenddo score behind a HTTP proxySay your HTTP proxy is running at thehttp://192.168.1.100address in your internal network:fromlenddo_api_clientimportLenddoAPIClientHTTP_PROXIES={'http':'http://192.168.1.100','https':'http://192.168.1.100',}client=LenddoAPIClient('your-api-client-id','your-api-client-secret','https://scoreservice.lenddo.com',proxies=HTTP_PROXIES)response=client.get('ApplicationScore','example-application')TheHTTP_PROXIESdictionary is based on python's'proxies' dict.Exceptions and Error HandlingExceptions raised by the client are standard exceptions documented in standard library docs.
The sdk client provides a wrapper module for these exceptions inlenddo_api_client.errors.exceptiondescription2.x3.xHTTPErrorRaised when an API call returns a non-success status.linklinkURLErrorRaised on network error.linklinkThe following is the same request as in the previous example, this time with error handling included:importjsonfromlenddo_api_clientimportLenddoAPIClientfromlenddo_api_client.errorsimportHTTPError,URLErrorclient=LenddoAPIClient('your-api-client-id','your-api-client-secret','https://scoreservice.lenddo.com')try:response=client.get('ApplicationScore','example-application')exceptHTTPErrorase:print('API call failed with status%d'%e.code)# Error responses from the Lenddo APIs still return JSON bodies describing error details,# only now we have to decode the JSON ourselves.print(json.loads(e.read()))exceptURLErrorase:print('API call failed with reason%s'%e.reason)For the sake of brevity, we omit error handling in subsequent examples. In production code, calls should
be made taking into account at least the possibility ofHTTPError.Submitting Applications to Lenddo: Using the API Client as a White Label SolutionYou may submit data directly to Lenddo while keeping your own branding, thus utilizing Lenddo services
without having users leave your ecosystem. For each user application, this is accomplished in two
phases: first by making POST calls to thePartnerTokenresource, which saves OAuth tokens associated
to your user's application, and finally by committing the job using theCommitPartnerJobresource.
Both resources are hosted atnetworkservice.lenddo.com.Applications are identified by aapplication_idwhich must be supplied as parameter to both
calls. In addition, thepartner_script_idparameter specifies how Lenddo informs
you of the results. You may only commit one job perapplication_id/partner_script_idpair.The PartnerToken API callDuring the first phase of the job flow, make calls toPartnerTokento send social
network OAuth tokens to Lenddo. Each call toPartnerTokenreturns aprofile_idwhich you must save in order to send it along with all otherprofile_idsassociated
to this application when you finally commit the job. To add multiple tokens for the same
application, make multiplePartnerTokencalls, each time saving the returnedprofile_id.PartnerTokentakes the following arguments, all required unless stated otherwise:application_id- a string that identifies the application to associate with an OAuth token
It must match theapplication_idyou use in theCommitPartnerJobstep.provider- the token provider. Valid values are:Facebook,LinkedIn,Yahoo,WindowsLive, orGoogletoken data- a dictionary of OAuth token data with keyskeyandextra_data.Note: All tokens must beOAuth 2.0.key- the access token proper, a stringextra_data- optional dictionary of additional OAuth fields returned by the token provider.NoteIn order for Lenddo to generate the profile_id, it has to use the supplied OAuth token,
which may fail (for example, when the user has denied permission or the token has expired). When
this happens,PartnerTokenwill return with HTTP 400 and the body of the response will contain both the
error code and response body that Lenddo received when trying to use the token. The provider's HTTP response
is underprovider_status_codeand the provider's response body is underprovider_response. The format of
theprovider_responsevaries among OAuth providers; see the OAuth provider's documentation for details.Exampleimportjsonfromlenddo_api_clientimportLenddoAPIClientfromlenddo_api_client.errorsimportHTTPErrorclient=LenddoAPIClient('your-api-client-id','your-api-client-secret','https://networkservice.lenddo.com')try:response=client.post('PartnerToken',None,{'application_id':'example-application','provider':'Facebook','token_data':{'key':'example-access-token'}})exceptHTTPErrorase:print('API call failed with HTTP status%d'%e.code)print(json.loads(e.read()))profile_id=response['profile_id']# ... and store this profile_id - application_id associationErrorsTo inspect error details, catchHTTPError, call the exception object's 'read()' method, and decode the
JSON response.  In the table below, 'Error Name' refers to the string found in the response body's 'name' field.Error NameHTTP Status CodeDescriptionBAD_REQUEST400Request was malformed, or missing required data.INVALID_TOKEN400Token data was missing required fields or fields had invalid values.TOKEN_FAILURE400Failure upon attempt to use the token.provider_status_codecontains the provider's HTTP status code.provider_responsecontains the provider's error response body.INTERNAL_ERROR500An internal error occurred. If this persists please contact a Lenddo Representative.The CommitPartnerJob API CallOnce there are no more tokens to associate to a given application, use theCommitPartnerJobcall to have Lenddo compute a score for your user. To
obtain the results of the job, see [Requesting Results from Lenddo] (#requesting-results-from-lenddo).CommitPartnerJobtakes the following required arguments:partner script id- Please reference thedeveloper sectionof the partner dashboard. This will define how you're notified of scoring results.application id- an application id that, coupled with the partner script id, identifies this job. For any given
application, this is the same application_id used in thePartnerTokencall.
You can use this value to retrieve score results.profile ids- a list ofprofile_idsgathered from the results of thePartnerTokencall.In addition to these arguments, CommitPartnerJob accepts the following:verification_data- A dictionary representing a verification formpartner_data- A dictionary pf form data.Example# In the actual workflow, profile_ids would be the list of the ids obtained from PartnerToken# responses associated to this application.profile_ids=['123FB']# Assume the same client instance as used in the PartnerToken section.# This client connects to networkservice.lenddo.com.client.post('CommitPartnerJob',None,{'partner_script_id':'your-partner-script-id','application_id':'example-application','profile_ids':profile_ids})ErrorsTo inspect error details, catchHTTPError, call the exception object'sread()method, and decode the
JSON response.  In the table below, 'Error Name' refers to the string found in the response body's 'name' field.Error NameHTTP Status CodeDescriptionBAD_REQUEST400Request was malformed, or missing required data.INTERNAL_ERROR500An internal error occurred. If this persists please contact a Lenddo Representative.PARTNER_CLIENT_ALREADY_PROCESSED400The specified application_id has already been used.Requesting Results from LenddoYou may obtain score and verification results from Lenddo by making calls to theApplicationVerificationandApplicationScoreAPIs hosted atscoreservice.lenddo.com.ScoresTo obtain score results, make a GET request toApplicationScore:fromlenddo_api_clientimportLenddoAPIClientclient=LenddoAPIClient('your-api-client-id','your-api-client-secret','https://scoreservice.lenddo.com')response=client.get('ApplicationScore','example-application',{'partner_script_id':'your-partner-script-id'})score=response['score']flags=response['flags']Verification ResultsTo obtain verification results, make a GET request toApplicationVerification:fromlenddo_api_clientimportLenddoAPIClientclient=LenddoAPIClient('your-api-client-id','your-api-client-secret','https://scoreservice.lenddo.com')response=client.get('ApplicationVerification','example-application',{'partner_script_id':'your-partner-script-id'})results=response['verifications']flags=response['flags']name_results=results['name']Application Decision ResultsTo obtain application decision results, make a GET request toApplicationVerification:fromlenddo_api_clientimportLenddoAPIClientclient=LenddoAPIClient('your-api-client-id','your-api-client-secret','https://scoreservice.lenddo.com')response=client.get('ApplicationDecision','example-application',{'partner_script_id':'your-partner-script-id'})results=response['decision']flags=response['flags']FICO Score ResultsTo obtain FICO score results, make a GET request toFICOScore:fromlenddo_api_clientimportLenddoAPIClientclient=LenddoAPIClient('your-api-client-id','your-api-client-secret','https://scoreservice.lenddo.com')response=client.get('FICOScore','example-application',{'partner_script_id':'your-partner-script-id'})results=response['score']pd=response['pd']CommitPartnerJob partner_data format for FICO scoringThe partner_data format for a FICO score application has has three required fields:applicationdictionary, requiredbureauDatadictionarapplicantdictionaryapplicationData.applicationThe application object has the following fields.KeyTypeRequiredDescriptionapplicationIdstringYesdatestring in ISO 8601 formatYesproductTypestringYesone of "Mortgage", "Personal Loans", "Overdraft", "Cards", "Auto Loans", "Payday Loan", "SME", or "Others"channelstringYesone of "Partner/Store", "Internet", "Branch", "Small business hub", "Pre-approved", "Top-up", "Mobile App" or "ATM"productobjectYessee description belowapplicationData.application.productThe product object has the following fields.KeyTypeRequiredDescriptionloanAmountintegerYespaymentMethodstringYesone of "Auto debit" or "Payment through transaction account"indicatorForPresenceOfGuarantorbooleanYesloanPurposestringYesone of "Loan for personal expenses", "Working capital loan", "Holiday", "Loan for making interest payment", "Education", "Renovation", "Refinancing", or "Others"applicationData.bureauDataThe "bureauData" object has two fields, "enquiries" (array of objects) and "tradelines" (array of objects).applicationData.bureauData.enquiriesEach enquiry object in the enquiries array has the following fields.KeyTypeRequiredDescriptionamountintegerYesthe amount of the enquiryapplicationIdstringYesenquiryDatestring in DDMMYYYY formatYesentityTypestringYesmemberCdstringYesmemberRefstringYesprocessedDatestring in DDMMYYYY formatYesthe date when the enquiry was madeproductCdstringYesthe product applied forpurposeintegerYespurpose of the enquirycontrolNumintegerNoa system-generated enquiry control numberapplicationData.bureauData.tradelinesEach tradeline object in the tradelines array has the following fields.KeyTypeRequiredDescriptionaccountNumstringYesaccountStatusintegerYesaccountTypeintegerYesaccountTypeCdintegerYesamtOverduenumberNothe amount past due as of the date in the Date Reported fieldapplicationIdstringYescashLimitnumberNocloseDatestring in DDMMYYYY formatYesthe date the account was closedcollateralTypeintegerYescollateralValuenumberNocontrolNumintegerNoa system-generated enquiry control numbercreditLimitnumberNofor Credit Card (Account Type 10) and Fleet Card (Account Type 16, this field contains the highest amount of credit used in the history of the accountcurrBalancenumberNothe entire amount of credit or loan outstanding, including the current and overdue portion, if any, together with interest last applied, as of the date in the Date Reported fielddelqHisMMYYstringYescycle delinquency (up to 48 months)installmentAmtnumberNointerestRatenumberNolastPaymentnumberNolastPaymentDatestring in DDMMYYYY formatYesmemberCdstringYesmemberRefstringYesopenDatestring in DDMMYYYY formatYesdate of first disbursement of the accountownershipIndintegerYes1 = Individual, 2 = Authorised User (refers to supplementary credit card holder), 3 = Guarantor, 4 = JointpayHistEndDatestring in DDMMYYYYYesthe date of the end of the payment historypayHistStartDatestring in DDMMYYYY formatYesdate of the beginning of the payment historyprocessedDatestring in DDMMYYYY formatYesproductCdstringYesrepaymentTenureintegerYesterm of loanreportedDateintegerNoYessanctionAmtnumberNofor all other accounts, this field contains the amount of loan sanctionedsettlementAmtnumberNosettlement amountsuitFiledCurrStatusstringYessuit filed status of the current monthsuitFiledStatusMMYYstringYessuit filed status history (up to 48 months))termFrequencystringYespayment frequencywriteoffPrincipalAmtnumberNowriteoffSettledStatusstringYeswriteoffTotalAmtnumberNowrite-off amount - totalapplicantThe applicant object has the following fields.KeyTypeRequiredDescriptiondobstring in ISO 8601 formatYesmobileTelephoneProvidedbooleanNogenderstringNoone of "MALE" or "FEMALE"maritalStatusstringNoone of "Married", "Living together", "Single", "Widowed", "Divorced/Separated", or "Other"residenceRegionstringNoemailProvidedbooleanNoemploymentStatusstringNoone of "Salaried", "Own Business/ Self-Employed", "Retired/Pensioner", "Part-time Employed / Freelance / Contractual Employee / Laborer", "Housewife/Other", or "Student"yearsInCurrentJobintegerNohomeTelephoneProvidedbooleanNoeducationLevelstringNoone of "Undergraduate", "Graduate", "Post Graduate", or "Diploma and Specialized Courses"yearsOfServiceintegerNoresidentialStatusstringNoone of "Self Owned", "Company Provided", "With Parents", "Rented", "Paying Guest", "Leased", or "Other"workTelephoneProvidedbooleanNodependentsintegerNonumOfMonthsInCurrentAddressintegerNomonthlyIncomeintegerNoexistingCustomerobjectNoobject with fields "timeWithTheBank" (integer) and "noOfAccountsWithTheBank" (integer)ErrorsTo inspect error details, catchHTTPError, call the exception object'sread()method, and decode the
JSON response.  In the table below, 'Error Name' refers to the string found in the response body's 'name' field.Error NameHTTP Status CodeDescriptionBAD_REQUEST400Request was malformed, or missing required data.INTERNAL_ERROR500An internal error occurred. If this persists please contact a Lenddo Representative.NOT_FOUND404The requested application_id was not found.