Application API Integration Guide

Base URL: https://vision.timvero.xyz/customer_api/swagger-ui/index.html#/

1. Overview

The timveroOS API allows you to integrate our online application process into your own platform, providing a seamless experience for your end borrowers. By following this guide, you will be able to:

• Authenticate with the API

• Create loan applications

• Upload required documents

• Obtain signature URLs for document signing

• Retrieve and select loan offers

2. Getting Started

Prerequisites:

• Access to valid API credentials (username and password).

• Familiarity with making HTTP requests.

• timveroOS SDK (optional, for customization).

Authentication

All API requests must be authenticated using your API credentials. Authentication is done via a login request that provides you with a token for subsequent API calls.

Example Credentials:

• Username: client9

• Password: 5091071

API Endpoints:

Login

Authenticate with the API to obtain an access token.

• Endpoint: /v1/login

• Method: POST

• Headers: Content-Type: application/json

Request:

{
    "username": "client9",
    "password": "5091071"
}

Response:

• 200 OK: Returns an access_token for authentication.

• Example:

{
    "access_token": "your_access_token_here",
    "token_type": "Bearer",
    "expires_in": 3600
}

Notes:

• Store the access_token securely.

• Include the token in the Authorization header for all subsequent requests.

Create an Application

Create a new loan application for a borrower.

• Endpoint: /v1/application

• Method: POST

• Headers:

• Content-Type: application/json

• Authorization: Bearer {access_token}

Request Parameters:

• total_income: Borrower’s total income. Format: ``USD:AMOUNT''

• monthly_outgoings: Borrower’s monthly outgoings. Format: ``USD:AMOUNT''

Advice:

• Best Practice: Use a total income at least 20 times greater than the monthly outgoings to avoid application decline due to basic underwriting logic.

Request Example:

{
    "total_income": "USD:20000",
    "monthly_outgoings": "USD:1000"
}

Response:

• 200 Created: Returns an applicationCode for the new application.

• Example:

{
    "applicationCode": "1234567890abcdef"
}

Notes:

• Save the applicationCode for future API calls related to this application.

Upload Required Documents

Upload the necessary documents for the application.

• Endpoint: /v1/application/{applicationCode}/required-documents

• Method: POST

• Headers:

• Content-Type: multipart/form-data

• Authorization: Bearer {access_token}

Required Documents:

• ID_scan: A scanned copy of the borrower’s ID.

• Proof_of_address: A document verifying the borrower’s address.

Request Example:

POST /v1/application/{applicationCode}/required-documents HTTP/1.1
Host: http://vision.timvero.xyz
Authorization: Bearer {access_token}
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="document_type"
ID_scan
`------WebKitFormBoundary7MA4YWxkTrZu0gW`
Content-Disposition: form-data; name="file"; filename="id_scan.pdf"
Content-Type: application/pdf
<file content>
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Response:

• 200 OK: Document uploaded successfully.

Notes:

• Repeat this step for each required document.

• Replace {applicationCode} with the actual code from step 2.

Obtain Signature URL

Retrieve the URL for the borrower to sign the application form via DocuSign.

• Endpoint: /v1/application/{applicationCode}/signature-url

• Method: GET

• Headers:

• Authorization: Bearer {access_token}

Request Example:

GET /v1/application/{applicationCode}/signature-url HTTP/1.1
Host: http://vision.timvero.xyz
Authorization: Bearer {access_token}

Response:

• 200 OK: Returns a signature_url.

• Example:

{
    "signature_url": "https://docusign.com/signature?envelopeId=abc123"
}

Notes:

• Embed the signature_url in your platform where the borrower can access and sign the document.

Retrieve Offers

Get all available loan offers for the borrower after underwriting.

• Endpoint: /v1/application/{applicationCode}/offers

• Method: GET

• Headers:

• Authorization: Bearer {access_token}

Processing Time:

• The underwriting process takes approximately 10 seconds.

Request Example:

GET /v1/application/{applicationCode}/offers HTTP/1.1
Host: http://vision.timvero.xyz
Authorization: Bearer {access_token}

Response:

• 200 OK: Returns a list of loan offers.

• Example:

{
    "offers": [
        {
            "offer_id": "offer123",
            "amount": "USD:10000",
            "interest_rate": "5%",
            "term": "24 months",
            "conditions": "Standard terms and conditions apply."
        },
        {
            "offer_id": "offer456",
            "amount": "USD:15000",
            "interest_rate": "4.5%",
            "term": "36 months",
            "conditions": "Standard terms and conditions apply."
        }
    ]
}

Choose Offer Conditions

Select specific terms and conditions for the chosen loan offer.

• Endpoint: /v1/application/{applicationCode}/save-condition/regular

• Method: POST

• Headers:

• Content-Type: application/json

• Authorization: Bearer {access_token}

Request Parameters:

• offer_id: The ID of the selected offer.

• tnc_id: The ID of the terms and conditions agreed upon.

Request Example:

{
    "offer_id": "offer123",
    "tnc_id": "tnc789"
}

Response:

• 200 OK: Conditions saved successfully.

Additional Steps

We also offer further steps, including a second underwriting process and signing of the final offer. These steps are similar in mechanics to the ones described above. If you require detailed guidance on these additional steps, please let us know, and we will update this documentation accordingly.

Notes and Best Practices

Authentication:

Always include the Authorization: Bearer {access_token} header in your API requests after logging in.

Data Formats:

Monetary values should be in the format ``USD:AMOUNT''.

Currency is important.

Error Handling:

Check for HTTP status codes and handle errors gracefully.

Security:

Keep your access_token and API credentials secure.

Use HTTPS for all API requests to ensure data security.

Underwriting Logic:

Providing a total income at least 20 times greater than monthly outgoings increases the likelihood of application approval.