Quick Start Guide

This quick start guide will help you set up and execute your first verification request in just a few steps.

Good to know: While this guide is designed to get you up and running quickly, we recommend working closely with us to maximise the benefits of our services. Contact us at [e-mail] to connect with one of our experts.

Step 1: Get Your API Credentials

To use the Tiller Verifications API, you'll need some credentials. This is essential for authenticating your requests and ensuring secure access to the system. Here’s how to get started:

• Contact your Tiller account manager to request your API credentials. -

  • [e-mail].

• Safeguard your credentials; it is required for authorization. Treat it like a password—never share it or expose it publicly.

---

Step 2: Set Up Authentication

The Tiller Verifications API uses token-based authentication via the OAuth 2.0 protocol. You’ll need to obtain an access token to authenticate your requests. Here’s how to do it:

Authentication Endpoint

https://verifications-auth.tiller-verify.com/connect/token

Parameters Required

• grant_type: Always set to client_credentials.

• scope: Use VerificationsAPI as the scope.

• client_id: Your client ID, provided by Tiller.

• client_secret: Your client secret, provided by Tiller.

Example request:

curl

curl --location 'https://verify-auth.tiller-verify.com/connect/token' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=VerificationsAPI' \
--data-urlencode 'client_id=CLIENT_ID' \
--data-urlencode 'client_secret=CLIENT_SECRET'

Python Requests

import requests

url = "https://verifications-auth.tiller-verify.com/connect/token"

payload = {'grant_type':'client_credentials',
           'scope': 'VerificationsAPI',
           'client_id': CLIENT_ID,
           'client_secret': CLIENT_SECRET
          }

headers = {
  'Accept': 'application/json',
  'Content-Type': 'application/x-www-form-urlencoded'
}

response = requests.request("POST", AUTH_URL, headers=headers, data=payload)

print(response.text)

Example response:

{
    "access_token": "eyJhbGciOiJS...",
    "expires_in": 600,
    "token_type": "Bearer",
    "scope": "VerificationsAPI"
}

Include the retrieved access token in the Authorization header of all subsequent API requests:

Please see Authentication for more information.

---

Step 3: Make Your First Request

This step walks you through performing an Address Verification Check using the Tiller Verifications API. Below, we explain the required payload, headers, and the structure of the request.

Endpoint:

POST https://verifications-api.tiller-verify.com/api/v1/verifications

Headers Required

Header	Value
Authorization	Bearer YOUR_ACCESS_TOKEN (Replace YOUR_ACCESS_TOKEN with your valid token)
Content-Type	application/json

Payload structure

We need some basic information in the request to be able to perform the check. The request is broken down into the following elements:

• externalReferenceId - Your reference for this request.

• options - These parameters change the behaviour of the request. Keep to the default values in the example payload below.

  • runAsync - determines whether the verification request is processed synchronously (returns results immediately) or asynchronously (returns a correlation ID to retrieve results later).

  • mock - We return mock data for testing purposes if True

• checks - This controls which checks will be performed in this request and includes some parameters around how the check will be performed. Keep to the default values in the example payload below for address check.

• profile - The personal information about the individual you are making a request about.

Example payload:

{
    "externalReferenceId": "YOUR_REQUEST_REFERENCE",
    "options": {
        "runAsync": false,
        "mock": true
    },
    "checks": [
        {
            "checkTypeId": 1,
            "externalCheckReferenceId": "YOUR_CHECK_REFERENCE",
            "maximumSources": 3,
            "CheckMethod": 1,
            "matchesRequired": 1
        }
    ],
    "profile": {
        "titleId": 1,
        "genderTypeId": 1,
        "firstName": "John",
        "middleName": "Charles",        
        "lastName": "Smith",
        "dateOfBirth": "1980-06-12",
        "currentAddress": {
            "structured": {
                "flatApartmentSubBuilding": "10A",
                "BuildingNumber": "50",
                "BuildingName": "Example House",
                "RoadStreet": "Example Street",
                "townCity": "Exampleton",
                "District": "Exampleshire",
                "StateProvinceName": "Example",
                "StateProvinceCode": "EG",
                "postZipCode": "EX12AB",
                "countryCode": "GB",
                "dateFrom": "2020-01-03T00:00:00"
            }
        }
    }
}

Making your first request:

curl

curl -X POST "https://verifications-api.tiller-verify.com/api/v1/verifications" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
    "externalReferenceId": "YOUR_REQUEST_REFERENCE",
    "options": {
        "runAsync": false,
        "mock": true
    },
    "checks": [
        {
            "checkTypeId": 1,
            "externalCheckReferenceId": "YOUR_CHECK_REFERENCE",
            "maximumSources": 3,
            "CheckMethod": 1,
            "matchesRequired": 1
        }
    ],
    "profile": {
        "titleId": 1,
        "genderTypeId": 1,
        "firstName": "John",
        "middleName": "Charles",        
        "lastName": "Smith",
        "dateOfBirth": "1980-06-12",
        "currentAddress": {
            "structured": {
                "flatApartmentSubBuilding": "10A",
                "BuildingNumber": "50",
                "BuildingName": "Example House",
                "RoadStreet": "Example Street",
                "townCity": "Exampleton",
                "District": "Exampleshire",
                "StateProvinceName": "Example",
                "StateProvinceCode": "EG",
                "postZipCode": "EX12AB",
                "countryCode": "GB",
                "dateFrom": "2020-01-03T00:00:00"
            }
        }
    }
}'

Python Requests

import requests

# API endpoint
url = "https://verifications-api.tiller-verify.com/api/v1/verifications"

# Headers
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}

# Payload
payload = {
    "externalReferenceId": "YOUR_REQUEST_REFERENCE",
    "options": {
        "runAsync": False,
        "mock": True
    },
    "checks": [
        {
            "checkTypeId": 1,
            "externalCheckReferenceId": "YOUR_CHECK_REFERENCE",
            "maximumSources": 3,
            "CheckMethod": 1,
            "matchesRequired": 1
        }
    ],
    "profile": {
        "titleId": 1,
        "genderTypeId": 1,
        "firstName": "John",
        "middleName": "Charles",        
        "lastName": "Smith",
        "dateOfBirth": "1980-06-12",
        "currentAddress": {
            "structured": {
                "flatApartmentSubBuilding": "10A",
                "BuildingNumber": "50",
                "BuildingName": "Example House",
                "RoadStreet": "Example Street",
                "townCity": "Exampleton",
                "District": "Exampleshire",
                "StateProvinceName": "Example",
                "StateProvinceCode": "EG",
                "postZipCode": "EX12AB",
                "countryCode": "GB",
                "dateFrom": "2020-01-03T00:00:00"
            }
        }
    }
}

# Request
response = requests.post(url, headers=headers, json=payload)

# Response
print(response.json())