All pages
Powered by GitBook
2 of 4

API Reference

The Tiller Verifications API is divided into three main components: Authentication, Verifications, and Ongoing Monitoring.

Authentication

Before using the API, clients must authenticate their requests. The authentication service ensures that all interactions with the API are authorized and secure.

Authentication

Verificatons

The Verifications component is the heart of the API, enabling businesses to perform a variety of checks. These include Address Verification, Background Checks (PEP & Sanctions, Watchlist, and Adverse Media), and UK Bank Account Checks.

Verifications

Ongoing Monitoring

Ongoing Monitoring enhances Background Checks by providing continuous updates on an individual’s PEP, sanctions, or adverse media status. This ensures businesses are alerted to compliance risks as soon as they arise.

Ongoing Monitoring

How It Works

  1. Authenticate: Begin by authenticating your API client and obtaining a bearer token. This token is required for all subsequent API calls.

  2. Submit a Verification Request: Use the Verifications API to perform compliance checks on an individual. Configure checks and provide the necessary profile details.

  3. Enable Monitoring (Optional): For continuous monitoring of PEP & Sanctions or Adverse Media, include enableOngoingMonitoring: true in your verification request.

  4. Retrieve Results: Access results directly from the response (synchronous) or poll using the correlation ID (asynchronous).

  5. Manage Monitoring Subscriptions: Use the Ongoing Monitoring endpoints to subscribe to notifications, retrieve results, or unsubscribe when no longer needed.

This API overview serves as your starting point for integrating the Tiller Verifications API into your workflows. For detailed technical documentation and examples, explore the linked sections or contact our support team at support@tillertech.com.

Authentication

The Tiller Verifications API uses token-based authentication via the OAuth 2.0 protocol. To ensure secure communication and protect sensitive data, every request to the API requires a valid access token in the Authorization header.

Prerequisities

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. -

    • info@tillertech.com.

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

Obtain an Access Token

To authenticate your requests, you need to retrieve an access token by sending a POST request to the authentication /connect/token endpoint. The request should include the following form data:

Parameter
Required
Description

grant_type

Yes

Specifies the OAuth 2.0 grant type. Use client_credentials.

client_id

Yes

Your client unique identifier provided by Tiller.

client_secret

Yes

Your secret key provided by Tiller.

scope

Yes

Use VerificationsAPI as the scope.

Authentication token

post

Obtain an authentication token using client credentials.

Body
grant_typestringRequiredDefault: client_credentials
scopestringRequiredDefault: {{scope}}
client_idstringRequiredDefault: {{client_id}}
client_secretstringRequiredDefault: {{client_secret}}
Responses
200
Successful response
application/json
post
POST /connect/token HTTP/1.1
Host: verifications-auth.tiller-verify.com
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 119

"grant_type='client_credentials'&scope='{{scope}}'&client_id='{{client_id}}'&client_secret='{{client_secret}}'"
{
  "access_token": "text",
  "token_type": "text",
  "expires_in": 1
}

Example request

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'

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"
}

To use the access token with the Verifications service, include it in the Authorization header of your HTTP requests.

Best Practices for Using Access Tokens

  • Token Renewal: Monitor the token’s expiry and implement logic to request a new one before making further API calls.

  • Secure Transmission: Always use HTTPS to prevent interception of the access token during transmission.

  • Scope Management: Use minimal scopes necessary for each request to enhance security.

By including the access token in your requests, you gain secure and authenticated access to the Verifications service, protecting sensitive information.

Verifications

The Verifications API can a variety of checks for customer verification purposes. This section outlines the available check types, the required request structure, and the specific profile details needed for each type of check.

For more details on building a request please see Request Structure.

Making a Verifications Request

Endpoint:

POST /api/v1/verifications

Description: This endpoint is used to initiate a verification request. It processes and returns the results of the specified checks.

Key Features:

  • Supports synchronous (runAsync: false) and asynchronous (runAsync: true) processing.

  • When runAsync is false, the response includes the verification results.

  • When runAsync is true, a correlationId is returned, which must be used to fetch the results via the GET /api/v1/verifications/{correlationId} endpoint.

Usage: This endpoint allows users to perform one or more checks (e.g., Address Verification, Bankground Checks, Bank Account Check) in a single request. Ensure that the required information is provided for each check type. For more detail on building a request please see Request Structure.

Retrieving Check Results

Endpoint:

GET /api/v1/verifications/{correlationId}

Description: Used to retrieve the results of a previously submitted verification request. This endpoint is primarily used when runAsync: true was specified in the initial request. But can be used when runAsync: false as well.

Key Features:

  • Can be polled to check the status of the verification process.

  • Returns the detailed results of each check once available.

Parameters:

  • correlationId (path): The unique identifier returned when the initial verification request was submitted.

References

Endpoint: GET /api/v1/verifications/references

Description: This endpoint provides reference data required for verifications. It includes details such as valid check types, status codes, titles, genders, and country codes.

Key Features:

  • Useful for retrieving a list of valid codes and identifiers required when making a verification request.

  • Helps to ensure requests are formatted correctly with the proper values.

Ongoing Monitoring

Overview

The Ongoing Monitoring API allows you to manage and retrieve updates for continuous background checks. When ongoing monitoring is enabled during a verification request (enableOngoingMonitoring: true), the system monitors the individual on a daily basis to identify new PEP & Sanctions, Adverse Media, or Watchlist events. Alerts are sent to the subscribed return URL whenever there is a status change, and results can be retrieved using the relevant endpoints.

Retrieving monitoring results

Endpoint:

GET /api/v1/ongoingmonitoring/{correlationId}

Description:

Retrieves the verification statuses and results for a specific ongoing monitoring record using the correlationId provided during the initial verification request.

Path parameters:

  • correlationId (string, required): The unique ID associated with the monitoring request.

Query Parameters:

  • fromDate (date-time, optional): Filter results starting from this date.

  • toDate (date-time, optional): Filter results up to this date.

Subcribing to the Monitoring Service

Endpoint:

POST /api/v1/ongoingmonitoring/subscribe

Description:

Subscribes to the ongoing monitoring service by registering a return URL and API key. This URL will receive webhook notifications for updates in monitored results.

Unsubscribe from the Monitoring Service

Endpoint:

POST /api/v1/ongoingmonitoring/unsubscribe

Description:

Unsubscribes the provided return URL from ongoing monitoring. After unsubscribing, you will no longer receive updates for monitored profiles.

Unsubscribe the subscription

post
Authorizations
Responses
200
OK
application/json
post
POST /api/v1/ongoingmonitoring/unsubscribe HTTP/1.1
Host: 
Authorization: Bearer JWT
Accept: */*

{
  "correlationId": "123e4567-e89b-12d3-a456-426614174000",
  "externalReferenceId": "text",
  "checkStatuses": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "checkTypeId": 1,
      "externalCheckReferenceId": "text",
      "status": {
        "id": 1,
        "status": "text"
      },
      "resultCount": {
        "totalSourcesChecked": 1,
        "totalSourcesPassed": 1,
        "totalSourcesFailed": 1,
        "totalSourcesForReview": 1
      },
      "matchesRequired": 1,
      "sourceResults": {
        "id": 1,
        "date": "2025-05-16T21:06:42.489Z",
        "rule": "text",
        "ruleId": 1,
        "status": {
          "id": 1,
          "status": "text"
        },
        "result": {
          "id": 1,
          "result": "text"
        },
        "title": "text",
        "summaryTitle": "text",
        "summary": [
          {
            "id": 1,
            "key": "text",
            "value": "text"
          }
        ],
        "results": [
          {
            "id": 1,
            "title": "text",
            "description": "text",
            "result": "text",
            "recordedDate": "text",
            "detail": {
              "reasons": [
                {
                  "id": 1,
                  "key": "text",
                  "result": "text",
                  "reason": "text",
                  "code": "text",
                  "metaData": {
                    "sourceName": "text",
                    "sourceOriginName": "text",
                    "title": "text",
                    "date": "text",
                    "name": "text",
                    "dob": [
                      "text"
                    ],
                    "matchScore": 1,
                    "riskScore": 1,
                    "gender": "text",
                    "relations": [
                      {
                        "relationType": "text",
                        "entityName": "text"
                      }
                    ],
                    "positions": [
                      {
                        "position": "text",
                        "fromYear": "text",
                        "toYear": "text"
                      }
                    ],
                    "aliases": [
                      {
                        "type": "text",
                        "name": "text"
                      }
                    ],
                    "regNumber": "text",
                    "branch": "text",
                    "address": "text",
                    "currentStatus": "text",
                    "incorporationDate": "text",
                    "dissolutionDate": "text",
                    "type": "text",
                    "officers": [
                      {
                        "id": 1,
                        "name": "text",
                        "position": "text",
                        "startDate": "text",
                        "endDate": "text",
                        "status": "text",
                        "address": "text"
                      }
                    ],
                    "parentCompanyInfo": {
                      "companyName": "text",
                      "countryCode": "text",
                      "regNumber": "text"
                    },
                    "primaryCompanyInfo": {
                      "companyName": "text",
                      "countryCode": "text",
                      "regNumber": "text"
                    },
                    "filings": {
                      "lastFilingDate": "text",
                      "filingType": {
                        "filingTypeCode": "text",
                        "filingTypeDescription": "text"
                      }
                    },
                    "officerId": "text",
                    "position": "text",
                    "startDate": "text",
                    "endDate": "text",
                    "actedCompany": "text",
                    "actedRegNumber": "text",
                    "country": "text",
                    "state": "text"
                  }
                }
              ]
            }
          }
        ],
        "resultsExcludedByFilters": [
          {
            "id": 1,
            "title": "text",
            "description": "text",
            "recordedDate": "text",
            "detail": {
              "reasons": [
                {
                  "id": 1,
                  "key": "text",
                  "result": "text",
                  "reason": "text",
                  "code": "text",
                  "metaData": {
                    "sourceName": "text",
                    "sourceOriginName": "text",
                    "title": "text",
                    "date": "text",
                    "name": "text",
                    "dob": [
                      "text"
                    ],
                    "matchScore": 1,
                    "riskScore": 1,
                    "gender": "text",
                    "relations": [
                      {
                        "relationType": "text",
                        "entityName": "text"
                      }
                    ],
                    "positions": [
                      {
                        "position": "text",
                        "fromYear": "text",
                        "toYear": "text"
                      }
                    ],
                    "aliases": [
                      {
                        "type": "text",
                        "name": "text"
                      }
                    ],
                    "regNumber": "text",
                    "branch": "text",
                    "address": "text",
                    "currentStatus": "text",
                    "incorporationDate": "text",
                    "dissolutionDate": "text",
                    "type": "text",
                    "officers": [
                      {
                        "id": 1,
                        "name": "text",
                        "position": "text",
                        "startDate": "text",
                        "endDate": "text",
                        "status": "text",
                        "address": "text"
                      }
                    ],
                    "parentCompanyInfo": {
                      "companyName": "text",
                      "countryCode": "text",
                      "regNumber": "text"
                    },
                    "primaryCompanyInfo": {
                      "companyName": "text",
                      "countryCode": "text",
                      "regNumber": "text"
                    },
                    "filings": {
                      "lastFilingDate": "text",
                      "filingType": {
                        "filingTypeCode": "text",
                        "filingTypeDescription": "text"
                      }
                    },
                    "officerId": "text",
                    "position": "text",
                    "startDate": "text",
                    "endDate": "text",
                    "actedCompany": "text",
                    "actedRegNumber": "text",
                    "country": "text",
                    "state": "text"
                  },
                  "excludedReasons": [
                    "text"
                  ]
                }
              ]
            }
          }
        ]
      },
      "result": {
        "id": 1,
        "result": "text"
      }
    }
  ],
  "overallResult": {
    "id": 1,
    "result": "text"
  },
  "overallStatus": {
    "id": 1,
    "status": "text"
  }
}