Quick Start Guide

Getting straight to it with this quick start guide.

This section will guide you through the initial steps to integrate and use our services. Whether you are new to APIs or an experienced developer, we've designed this process to be straightforward.

Step 1: Register for API Access

Before you can start using the API, you'll need to register and obtain your unique API credentials. These credentials are essential for authenticating and sending your API requests.

1) Sign Up: Visit our sign up page and create an account for your company. This will not be instant as we need to set up your company before we can give you access to our services.

2) API Permission: Once your account is set up, please contact us at [e-mail] to request API permission on your user credentials.

Step 2: Install Required Tools

To make API requests, you'll need a tool that can send HTTP requests. You can use tools like Postman , cURL, or write your code in a language that supports HTTP requests, such as Python, JavaScript, etc.

We can provide you with a Postman collection if required. Please contact [e-mail].

Step 3: Authenticate Your API Request

All API requests to Verify by Tiller require authentication. An access token can be retrieved through the Authentication method. Please see below some examples code.

URL: "https://api.tiller-verify.com/api/v1/ext/authentications/token"

Code example:

Python

import requests

def get_auth_token(username, password):
    url = "https://api.tiller-verify.com/api/v1/ext/authentications/token"
    payload = {
        "username": username,
        "password": password,
        "grant_type": "password"
    }
    headers = {
        "Content-Type": "application/x-www-form-urlencoded"
    }
    response = requests.post(url, data=payload, headers=headers)
    if response.status_code == 200:
        return response.json().get("access_token")
    else:
        print(f"Error: {response.status_code}, Message: {response.text}")
        return None

# Replace with your username and password
token = get_auth_token("your_username", "your_password")

JavaScript

const axios = require('axios');

async function getAuthToken(username, password) {
    const url = "https://api.tiller-verify.com/api/v1/ext/authentications/token";
    const payload = {
        username: username,
        password: password,
        grant_type: "password"
    };
    try {
        const response = await axios.post(url, payload, {
            headers: {
                'Content-Type': 'application/json',
                'Accept': 'application/json'
            }
        });
        return response.data.access_token;
    } catch (error) {
        console.error(`Error: ${error.response.status}, Message: ${error.response.data}`);
        return null;
    }
}

// Replace with your username and password
getAuthToken('your_username', 'your_password').then(token => {
    console.log(token);
});

cURL

curl -X POST https://api.tiller-verify.com/api/v1/ext/authentications/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "username=your_username&password=your_password&grant_type=password"

❗For "grant_type" we only support either "client_credentials" or "password". This will usually be "password".

Authentication will provide a bearer token to include in the header of your subsequent API requests. Please ensure this token is passed into the Authorization header on subsequent requests.

Step 4: Making Your First API Calls

Once you're authenticated, you can start making API calls. Here are some initial requests to get you started (subscribe, references and application).

- Post Subscription:

The subscribe endpoint provides a URL to send the customer verification results to your system via a Webhook.

Example code:

Python

import requests

def subscribe_to_webhook(token, callback_url):
    url = "https://api.tiller-verify.com/api/v1/ext/webhooks/subscribe"
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    }
    payload = {
        "callback_url": callback_url
    }
    response = requests.post(url, headers=headers, json=payload)
    if response.status_code == 200:
        return response.json()
    else:
        print(f"Error: {response.status_code}, Message: {response.text}")
        return None

# Example usage
token = "your_auth_token"  # Replace with your actual token
callback_url = "https://your.callback.url" # Replace with your URL
subscription = subscribe_to_webhook(token, callback_url)
print(subscription)

JavaScript

const axios = require('axios');

async function subscribeToWebhook(token, callbackUrl) {
    const url = "https://api.tiller-verify.com/api/v1/ext/webhooks/subscribe";
    const headers = {
        Authorization: `Bearer ${token}`,
        'Content-Type': 'application/json'
    };
    const payload = {
        callback_url: callbackUrl
    };

    try {
        const response = await axios.post(url, payload, { headers: headers });
        return response.data;
    } catch (error) {
        console.error(`Error: ${error.response.status}, Message: ${error.response.statusText}`);
        return null;
    }
}

// Example usage
const token = 'your_auth_token'; // Replace with your actual token
const callbackUrl = 'https://your.callback.url'; // Replace with your url

subscribeToWebhook(token, callbackUrl)
    .then(subscription => console.log(subscription))
    .catch(error => console.error(error));

cURL

curl -X POST "https://api.tiller-verify.com/api/v1/ext/webhooks/subscribe" \
     -H "Authorization: Bearer your_auth_token" \
     -H "Content-Type: application/json" \
     -d '{"callback_url": "https://your.callback.url"}'

You can specify a dynamic URL, such as an application ID. For example:

https://api.tiller-verify.com/api/v1/ext/webhooks/subscribe/{application_reference}

This allows for greater flexibility and specificity in handling webhook notifications.

- Get References:

This endpoint provide the ID references to commonly needed items such as your mandate type IDs and status IDs.

Python

import requests

def get_references(token):
    url = "https://api.tiller-verify.com/api/v1/ext/references"
    headers = {"Authorization": f"Bearer {token}"}
    response = requests.get(url, headers=headers)
    if response.status_code == 200:
        return response.json()
    else:
        print(f"Error: {response.status_code}, Message: {response.text}")
        return None

# Example usage
token = "your_auth_token"  # Replace with your actual token
references = get_references(token)
print(references)

JavaScript

const axios = require('axios');

async function getReferences(token) {
    const url = "https://api.tiller-verify.com/api/v1/ext/references";
    const headers = {
        Authorization: `Bearer ${token}`
    };

    try {
        const response = await axios.get(url, { headers });
        return response.data;
    } catch (error) {
        console.error(`Error: ${error.response.status}, Message: ${error.response.statusText}`);
        return null;
    }
}

// Example usage
const token = "your_auth_token"; // Replace with your actual token
getReferences(token).then(references => {
    console.log(references);
});

cURL

curl -X GET "https://api.tiller-verify.com/api/v1/ext/references" \
     -H "Authorization: Bearer your_auth_token"

It is useful to organise the references into categories.

Python

import json
from collections import defaultdict

def organise_by_category(data):
    categories = defaultdict(list)
    for item in data:
        category = item['category']
        categories[category].append(item)
    
    # Optionally, sort each category by name or reference_id
    for category in categories:
        categories[category].sort(key=lambda x: (x['reference_id'] is None, x['reference_id']))

    return categories

# JSON payload
data = get_references(token)

# Organise data
organised_data = organise_by_category(data)

# To print the organized data
for category, items in organised_data.items():
    print(f"Category: {category}")
    for item in items:
        print(f"  {item}")
    print("\n")

# Optionally, convert it back to JSON
json_output = json.dumps(organized_data, indent=4)
print(json_output)

JavaScript

const data = references

function organiseByCategory(data) {
    const categories = {};

    data.forEach(item => {
        const category = item.category;
        if (!categories[category]) {
            categories[category] = [];
        }
        categories[category].push(item);
    });

    // Optionally, sort each category by name or reference_id
    for (const category in categories) {
        categories[category].sort((a, b) => {
            // Sorting by reference_id with null values last
            return (a.reference_id === null) - (b.reference_id === null) || 
                   (a.reference_id || 0) - (b.reference_id || 0);
        });
    }

    return categories;
}

const organisedData = organiseByCategory(data);

// To print the organized data
for (const category in organisedData) {
    console.log(`Category: ${category}`);
    organisedData[category].forEach(item => console.log(`  ${JSON.stringify(item)}`));
    console.log('\n');
}

// Optionally, convert it back to JSON
const jsonOutput = JSON.stringify(organisedData, null, 4);
console.log(jsonOutput);

❗It is important that you retrieve your mandate type ID(s) to be able to start creating applications. These mandate types will determine the checks made against the individual. You should have at least one mandate type available upon set-up.

- Create Application

You can create an application for one or more individuals. This will send each individual an email inviting them to download the Verify by Tiller app and complete their checks. For more information please see the Applications section.

Python

import requests

def create_application(token, application_data):
    url = "https://api.tiller-verify.com/api/v1/ext/applications"
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    }
    response = requests.post(url, headers=headers, json=application_data)
    if response.status_code == 200:
        return response.json()
    else:
        print(f"Error: {response.status_code}, Message: {response.text}")
        return None

# Example usage
token = "your_auth_token"  # Replace with your actual token
application_data = {
        "name": "YOUR_APPLICATION_NAME", # A meaningful application name for the customer
        "reference": "MANDATE_REFERENCE", # A unique mandate referece
        "mandate_type": 1, # Update from references list
        "individuals": [
            {
                "email": "CUSTOMER_EMAIL",
                "title": "Mr",
                "first_name": "FIRST_NAME",
                "middle_name": "", #Optional
                "last_name": "LAST_NAME",
                "date_of_birth": "1980-12-31", #Optional
                "gender": "male",
                "reference": "REFERENCE001" # Your unique reference
            } 
            # Additional individuals can be added to this list.
        ]
    }
new_application = create_application(token, application_data)
print(new_application)

JavaScript

const axios = require('axios');

async function createApplication(token, applicationData) {
    const url = "https://api.tiller-verify.com/api/v1/ext/applications";
    const headers = {
        Authorization: `Bearer ${token}`,
        'Content-Type': 'application/json'
    };

    try {
        const response = await axios.post(url, applicationData, { headers });
        return response.data;
    } catch (error) {
        console.error(`Error: ${error.response.status}, Message: ${error.response.data}`);
        return null;
    }
}

// Example usage
const token = "your_auth_token"; // Replace with your actual token
const applicationData = {
    name: "YOUR_APPLICATION_NAME", // A meaningful application name for the customer
    reference: "MANDATE_REFERENCE", // A unique mandate reference
    mandate_type: 1, // Update from references list
    individuals: [
        {
            email: "CUSTOMER_EMAIL",
            title: "Mr",
            first_name: "FIRST_NAME",
            middle_name: "", // Optional
            last_name: "LAST_NAME",
            date_of_birth: "1980-12-31", // Optional
            gender: "male",
            reference: "REFERENCE001" // Your unique reference
        }
        // Additional individuals can be added to this list.
    ]
};

createApplication(token, applicationData)
    .then(newApplication => console.log(newApplication))
    .catch(error => console.error(error));

cURL

curl -X POST "https://api.tiller-verify.com/api/v1/ext/applications" \
     -H "Authorization: Bearer your_auth_token" \
     -H "Content-Type: application/json" \
     -d '{
            "name": "YOUR_APPLICATION_NAME",
            "reference": "MANDATE_REFERENCE",
            "mandate_type": 1,
            "individuals": [
                {
                    "email": "CUSTOMER_EMAIL",
                    "title": "Mr",
                    "first_name": "FIRST_NAME",
                    "middle_name": "",
                    "last_name": "LAST_NAME",
                    "date_of_birth": "1980-12-31",
                    "gender": "male",
                    "reference": "REFERENCE001"
                }
                // Additional individuals can be added here.
            ]
         }'

Once an individual has completed their checks on the Verify by Tiller mobile app, the results will be sent to the URL provided through the subscription endpoint. You can also retrieve the information directly using the Applications endpoint.

Further information about all the endpoint can be found in the API Reference section.

Step 5: Your Results

Each time an individual completes their checks within the Verify by Tiller app, you will receive a response to the URL you have posted to the subscription endpoint. Each webhook will contain the mandate/application details and all the details about the individuals.

❗When all individuals have completed their checks, the mandate (application) will move from an 'in progress' 🔵 status to either a 'in review' 🟡 or 'complete' 🟢 status.

General structure:

• ID and Reference: Unique identifiers for the application or the mandate.

• Mandate Type: Describes the type of application and what checks are included.

• Status: Overall status of the application, which is 'in progress' >> 'in review'/'complete'.

Individual details:

• Name, Date of Birth, Email, Gender: Basic personal information.

• Terms Accepted: Indicates whether the terms and conditions were accepted.

• Completed Actions: Lists completed steps in the mobile app to complete their check, like accepting terms and conditions, adding personal details, etc.

• Checks: Each check completed (e.g. address_verification_check) will have a set of result data, including:

  • Title - The type of check made

  • Status - Indicates the result of the check type, such as "pending", "review", or "accepted".

  • Check field results - Any underlying verifications made to determine the overall check status.

  • Images - Any associated images that are related to the check. This can include the ID document image for the Identity and Liveliness Checks.

Handling Errors

Each API request will return a response. A successful request will typically return a 200 OK status code along with any requested data. Errors or issues with your request will return different status codes (e.g., 400 Bad Request, 401 Unauthorized) and an error message explaining what went wrong.

Error handling for all API methods must adhere to the RFC7807 standard, ensuring standardized and informative error responses for clients. Please see https://www.rfc-editor.org/rfc/rfc7807. Please see more information within the Error Handling section.

Need Help?

If you encounter any issues or have questions, our support team is here to help. Please contact us at [e-mail]