NAV Navbar
javascript jquery shell
  • 🦁 Valiant API
  • Authentication
  • Leads
  • Errors
  • 🦁 Valiant API

    Introduction

    Welcome to the Valiant API!

    The Valiant API is a RESTful API with predictable, resource-oriented URLs, and uses semantic HTTP response codes to indicate API errors. Our API supports cross-origin resource sharing (CORS), allowing you to securely consume our API from any client-side web application. JSON is returned by all resource related API responses and all API requests must be made over HTTPS. The API follows the json:api specification for all requests and responses.

    Sandbox

    As a part of on-boarding we will provide both a set of Sandbox and Production API credentials. All endpoint paths for both APIs are the same however the root domain differs as detailed below.

    To test the API Sandbox we recommend using Postman. We couldn't live without it! 📮

    Authentication

    🔐

    Security is paramount at Valiant so all calls made to our API are authenticated. Once you have been given access to the API, you will receive a Valiant API uuid, key and secret which are the credentials that allow access to the API. These parameters are used to generate a set of HTTP headers that are used to authenticate requests.

    The content type of all calls made to the API are also verified. The Content-Type header in every request must be set to application/vnd.api+json.

    Headers

    We authenticate and verify all API requests via three HTTP headers that are required to be set in all API requests.

    Header Description
    X-AUTH-ID Your API client id that is a uuid provided once your API account has been established.
    X-AUTH-SIGNED-KEY A base64 string generated by HMAC-SHA256 signing your API key with your API secret.
    Content-Type All requests must be set to application/vnd.api+json.

    Generating your signed key

    To generate your signed key for the X-AUTH-SIGNED-KEY header you must generate a base64 string of HMAC-SHA256 signing your API key with your API secret.

    A great resource that provides examples of generating base64 hashes using HMAC-SHA256 in a variety of different languages can be found here.

    Unauthorized & unverified requests

    Testing Authentication

    Example request

    xhr = new XMLHttpRequest();
    
    xhr.open("GET", "https://mercury-summer.valiant.finance/api/v1/authenticate");
    xhr.setRequestHeader("X-AUTH-ID",         "<API_ID>")
    xhr.setRequestHeader("X-AUTH-SIGNED-KEY", "<API_SIGNED_KEY>");
    xhr.setRequestHeader("Content-Type",      "application/vnd.api+json");
    
    xhr.onreadystatechange = function () {
      if (xhr.readyState == 4) {
        console.log(xhr.status);
        console.log(xhr.responseText);
      }
    }
    
    xhr.send();
    
    curl -iX GET \
      https://mercury-summer.valiant.finance/api/v1/authenticate \
      -H "X-AUTH-ID:         <API_ID>" \
      -H "X-AUTH-SIGNED-KEY: <API_SIGNED_KEY>" \
      -H "Content-Type:      application/vnd.api+json"
    

    ⚠️ Be sure to replace <API_ID> and <API_SIGNED_KEY> with your API credentials!

    We have created an API endpoint which an empty request can be sent to in order to check if authentication headers have been set correctly.

    Item Details
    Endpoint /api/v1/authenticate
    Supported methods GET
    Description Test if authentication headers are correctly set. If the authentication & content type headers are set correctly, the endpoint will return a 200 OK status with an empty body. If authentication headers aren't set correctly the endpoint will return a 401 Unauthorized header with an empty body.

    Leads

    🏅

    Our Lead API allows third parties to directly submit Leads to Valiant via the API.

    Create a Lead

    Item Details
    Endpoint /api/v1/leads
    Supported methods POST
    Description Submits a Lead with the given details to Valiant.

    Parameters

    Example request

    var params = {
      "first_name":     "Isaac",
      "last_name":      "Newton",
      "phone":          "0400000000",
      "email":          "[email protected]",
      "months_trading": "12"
    }
    
    xhr = new XMLHttpRequest();
    
    xhr.open("POST", "https://mercury-summer.valiant.finance/api/v1/leads");
    xhr.setRequestHeader("X-AUTH-ID",         "<API_ID>")
    xhr.setRequestHeader("X-AUTH-SIGNED-KEY", "<API_SIGNED_KEY>");
    xhr.setRequestHeader("Content-Type",      "application/vnd.api+json");
    
    xhr.onreadystatechange = function () {
      if (xhr.readyState == 4) {
        console.log(xhr.status);
        console.log(xhr.responseText);
      }
    }
    
    xhr.send(JSON.stringify(params));
    
    var params = {
      "first_name":     "Isaac",
      "last_name":      "Newton",
      "phone":          "0400000000",
      "email":          "[email protected]",
      "months_trading": "12"
    }
    
    $.ajax({
      url: "https://mercury-summer.valiant.finance/api/v1/leads",
      type: "POST",
      contentType: "application/vnd.api+json",
      headers: {
        "X-AUTH-ID":         "<API_ID>",
        "X-AUTH-SIGNED-KEY": "<API_SIGNED_KEY>",
        "Content-Type":      "application/vnd.api+json"
      },
      data: JSON.stringify(params),
    
      beforeSend: function(data) {
        console.log("beforeSend");
      },
    
      success: function(data) {
        console.log("success");
        console.log(data);
      },
    
      error: function(data) {
        console.log("error");
      },
    
      complete: function(data) {
        console.log("complete!");
      }
    });
    
    curl -iX POST \
      https://mercury-summer.valiant.finance/api/v1/leads \
      -H "X-AUTH-ID:         <API_ID>" \
      -H "X-AUTH-SIGNED-KEY: <API_SIGNED_KEY>" \
      -H "Content-Type:      application/vnd.api+json" \
      -d '{
            "first_name":     "Isaac",
            "last_name":      "Newton",
            "email":          "[email protected]",
            "phone":          "0400000000",
            "months_trading": "12"
          }'
    

    Below lists a detail of accepted parameters that can be posted to the endpoint as a part of a valid JSON payload. A number of attributes are required.

    Attribute Type Required Description
    first_name string Must be less than 255 characters long
    last_name string Must be less than 255 characters long
    phone string Must be an Australian phone number and can begin with all valid local area codes, 1800 or 1300.
    email string Must conform to a valid email address.
    requested_amount integer The amount of the loan being requested. Must be a value greater than 0 if provided.
    months_trading integer The months the Lead's business has been trading. Must be a value greater than 0 if provided.

    Response

    Example successful response

    {
      "data": {
        "id": "6bbba93f-48c4-413b-88cf-de6436ccb20c",
        "type": "leads",
        "attributes": {
          "created_at": "2017-08-17T00:00:00.001Z"
        }
      }
    }
    

    If a request is successful, a json:api compliant JSON response will be delivered with all resource related information in a data key.

    Data Description
    id A unique identifier in uuid format generated for the resource by Valiant.
    type Pluralized name of the resource called on.
    attributes A map with values of resource attributes.

    Attributes

    The values of attributes included in the attributes hash are:

    Attribute Description
    created_at The UTC datetime the resource was created.

    Errors

    ⚠️

    The Valiant API uses conventional HTTP response codes to indicate the the HTTP status an API request.

    HTTP Status Codes

    Code Meaning
    200 OK Everything worked as expected.
    201 Created The resource was created successfully.
    400 Bad Request The request was unacceptable, often due to missing a required parameter.
    401 Unauthorized No valid authentication headers found.
    402 Request Failed The parameters were valid but the request failed.
    404 Not Found The requested resource doesn't exist.
    500 Server Error Something went wrong on Valiant's end.