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 support@tillertech.com 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 support@tillertech.com.
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.
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:
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)
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.
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)
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);
- 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.
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)
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));
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.
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 support@tillertech.com
For "grant_type" we only support either "client_credentials" or "password". This will usually be "password".
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.
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.
