Applications

This page contains information about managing applications/mandates.

Overview

The Applications API is designed to facilitate the management of Verify by Tiller applications and the individuals associated. It offers the following functionality:

• Create an application.

• Retrieve application details.

• Delete the application (and all associated individuals and check data).

• Archive the application (to help with record keeping).

❗The words 'application' and 'mandate' are used interchangeably.

Create application

The Application POST endpoint (/ext/applications) is designed for creating new verification applications. This endpoint initiates the verification process by creating an application and sending email invites to the individuals.

It requires application details, mandate type id (see References section), and information about the individuals. The endpoint ensures that each application is uniquely identified and processed, facilitating a structured and efficient verification workflow.

post

Creates a new application with one or more individuals specified details. The 'suppress_email_notification' field allows users to suppress all email notifications from Tiller. Set it to true to suppress, or false to allow notifications.

Authorizations

Bearer

AuthorizationstringRequired

Header parameters

Content-TypestringRequiredDefault: application/json

AcceptstringRequiredDefault: application/json

Body

application/json

namestringOptional

The name of the application.

Example: YOUR_APPLICATION_NAME

referencestringOptional

The unique reference for the mandate.

Example: MANDATE_REFERENCE

mandate_typeintegerOptional

The ID of the mandate type.

Example: 1

suppress_email_notificationbooleanOptional

If set to true, it will suppress all email communications from Tiller.

Example: false

Responses

200Success

application/json

idintegerRead-onlyOptional

namestring · min: 1 · max: 150Required

referencestring · max: 150 · nullableRequired

archivedbooleanOptional

post

/ext/applications

HTTPcURLJavaScriptPython

POST /api/v1/ext/applications HTTP/1.1
Host: api.tiller-verify.com
Authorization: YOUR_API_KEY
Accept: application/json
Content-Type: application/json
Content-Length: 312

{
  "name": "YOUR_APPLICATION_NAME",
  "reference": "MANDATE_REFERENCE",
  "mandate_type": 1,
  "suppress_email_notification": false,
  "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"
    }
  ]
}

200Success

{
  "id": 1,
  "name": "text",
  "reference": "text",
  "status": {
    "id": 1,
    "status": "text"
  },
  "mandate_type": {
    "id": 1,
    "name": "text",
    "code": "text",
    "description": "text"
  },
  "archived": true,
  "available_actions": [
    {
      "id": 1,
      "name": "text",
      "title": "text"
    }
  ]
}

Example request data:

application_data = {
        "name": "YOUR_APPLICATION_NAME", # A meaningful application name for your business
        "reference": "MANDATE_REFERENCE", # A unique mandate reference
        "mandate_type": 1, # Update ID from references list for your mandate type
        "individuals": [
            {
                "email": "CUSTOMER_EMAIL",
                "title": "Mr", # See references for full list
                "first_name": "FIRST_NAME",
                "middle_name": "", #Optional
                "last_name": "LAST_NAME",
                "date_of_birth": "1980-12-31", #Optional
                "gender": "male",
                "reference": "REFERENCE001" # A unique reference from your system
            } 
            # Additional individuals can be added to this list.
        ]
    }

Retrieve application

The Retrieve Application Endpoint (/ext/applications/{id}) allows you to fetch detailed information about a specific Verify by Tiller application using its unique identifier. This endpoint is useful in actively in monitoring the progress and status of an application, providing comprehensive insights into the progress of the mobile actions, individual checks, status updates, and other relevant data.

get

Retrieves details of a specific application identified by its ID.

Authorizations

Bearer

AuthorizationstringRequired

Path parameters

idstringRequired

Header parameters

Content-TypestringRequiredDefault: application/json

AcceptstringRequiredDefault: application/json

Responses

200Success

application/json

idintegerRead-onlyOptional

namestring · min: 1 · max: 150Required

referencestring · max: 150Required

archivedbooleanRead-onlyOptional

get

/ext/applications/{id}

HTTPcURLJavaScriptPython

GET /api/v1/ext/applications/{id} HTTP/1.1
Host: api.tiller-verify.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: application/json

200Success

{
  "id": 1,
  "name": "text",
  "reference": "text",
  "status": {
    "id": 1,
    "status": "text"
  },
  "mandate_type": {
    "id": 1,
    "name": "text",
    "code": "text",
    "description": "text"
  },
  "individuals": [
    {
      "id": 1,
      "email": "[email protected]",
      "title": "text",
      "first_name": "text",
      "middle_name": "text",
      "last_name": "text",
      "date_of_birth": "2026-04-01",
      "gender": "male",
      "reference": "text",
      "status": {
        "id": 1,
        "status": "text"
      },
      "terms_accepted": true,
      "address": {
        "id": 1,
        "individual": 1,
        "flat_appartment_subbuilding": "text",
        "building_number": "text",
        "building_name": "text",
        "road_street": "text",
        "district": "text",
        "town_city": "text",
        "state_province_name": "text",
        "state_province_code": "text",
        "country_code": "text",
        "post_zip_code": "text",
        "date_from": "2026-04-01",
        "date_to": "2026-04-01"
      },
      "completed_actions": [
        {
          "id": 1,
          "name": "text",
          "title": "text"
        }
      ],
      "checks_in_review": 1,
      "checks_in_pending": 1,
      "checks_passed": 1,
      "checks": [
        {
          "id": 1,
          "status": {
            "id": 1,
            "status": "text"
          },
          "name": "text",
          "title": "text",
          "individual_checkfield_result": [
            {
              "id": 1,
              "individual": 1,
              "check_field": 1,
              "result": "text",
              "status": 1
            }
          ],
          "instance": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        }
      ]
    }
  ],
  "archived": true,
  "available_actions": [
    {
      "id": 1,
      "name": "text",
      "title": "text"
    }
  ]
}

Complete application

The Complete Application endpoint (/ext/applications/{app_id}/complete) transitions an application from the "in review" status to "completed." This endpoint is used when the verification process for an application has been fully reviewed, or when it is determined that no further action is needed. Once an application is marked as completed it signifies that the verification process has reached its conclusion.

Reject application

The Reject Application endpoint (/ext/applications/{app_id}/reject) is used to reject an application that is currently "in review." This endpoint plays a crucial role when it is determined that the application does not meet the required standards or the associated checks have failed. By rejecting an application, the system ensures that no further processing occurs and that the application is marked as invalid. This also allows tracking of rejected applications for auditing or reporting purposes.

Delete application

The Delete Application Endpoint (/ext/applications/{id}), accessible via an HTTP DELETE request, enables clients to permanently remove an application using its unique identifier.

This will delete the application and all individual data associated with that application. It ensures clients can efficiently manage their application records, removing those no longer needed or relevant. All applications are automatically deleted after eight weeks as per our privacy policy.

delete

Deletes the application associated with the provided ID.

Authorizations

Bearer

AuthorizationstringRequired

Path parameters

idstringRequired

Responses

204Success

delete

/ext/applications/{id}

HTTPcURLJavaScriptPython

DELETE /api/v1/ext/applications/{id} HTTP/1.1
Host: api.tiller-verify.com
Authorization: YOUR_API_KEY
Accept: */*

204Success

No content

Archive application

The Archive Application Endpoint (/ext/applications/{id}/archive), which is accessed through an HTTP PATCH request, provides a facility to archive an existing application by its unique identifier.

Archiving an application is a prudent way to manage no longer current records but might be needed for future reference. This functionality helps keep the active application pool manageable and relevant while ensuring that historical data is preserved. Archiving differs from deletion in that it preserves the data rather than removing it, allowing for retrieval and review as usual through the retrieve application endpoint.

patch

Archives the specified application, changing its status but retaining its data.

Authorizations

Bearer

AuthorizationstringRequired

Path parameters

idstringRequired

Header parameters

Content-TypestringRequiredDefault: application/json

AcceptstringRequiredDefault: application/json

Body

application/json

objectOptional

Responses

200Success

application/json

idintegerRead-onlyOptional

namestring · min: 1 · max: 150Required

referencestring · max: 150Required

archivedbooleanRead-onlyOptional

patch

/ext/applications/{id}/archive

HTTPcURLJavaScriptPython

PATCH /api/v1/ext/applications/{id}/archive HTTP/1.1
Host: api.tiller-verify.com
Authorization: YOUR_API_KEY
Accept: application/json
Content-Type: application/json
Content-Length: 2

{}

200Success

{
  "id": 1,
  "name": "text",
  "reference": "text",
  "status": {
    "id": 1,
    "status": "text"
  },
  "mandate_type": {
    "id": 1,
    "name": "text",
    "code": "text",
    "description": "text"
  },
  "individuals": [
    {
      "id": 1,
      "email": "[email protected]",
      "title": "text",
      "first_name": "text",
      "middle_name": "text",
      "last_name": "text",
      "date_of_birth": "2026-04-01",
      "gender": "male",
      "reference": "text",
      "status": {
        "id": 1,
        "status": "text"
      },
      "terms_accepted": true,
      "address": {
        "id": 1,
        "individual": 1,
        "flat_appartment_subbuilding": "text",
        "building_number": "text",
        "building_name": "text",
        "road_street": "text",
        "district": "text",
        "town_city": "text",
        "state_province_name": "text",
        "state_province_code": "text",
        "country_code": "text",
        "post_zip_code": "text",
        "date_from": "2026-04-01",
        "date_to": "2026-04-01"
      },
      "completed_actions": [
        {
          "id": 1,
          "name": "text",
          "title": "text"
        }
      ],
      "checks_in_review": 1,
      "checks_in_pending": 1,
      "checks_passed": 1,
      "checks": [
        {
          "id": 1,
          "status": {
            "id": 1,
            "status": "text"
          },
          "name": "text",
          "title": "text",
          "individual_checkfield_result": [
            {
              "id": 1,
              "individual": 1,
              "check_field": 1,
              "result": "text",
              "status": 1
            }
          ],
          "instance": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        }
      ]
    }
  ],
  "archived": true,
  "available_actions": [
    {
      "id": 1,
      "name": "text",
      "title": "text"
    }
  ]
}

An archived application will have the following attribute:

"archived": True

Accept check

The Accept Check endpoint (/check/{check_id}/accept) allows the manual acceptance of a verification check. This endpoint is used when a check needs to be marked as manually_accepted. This might occur in situations where the system requires human review before finalising the status of a check. Once a check is accepted, its status is updated, and the relevant data is persisted in the system. The process helps ensure that the system can account for exceptions where automated checks may not fully suffice.

The following body is required in the request:

payload = {
    "comment": "This is a comment for the approval of this check",
    "comment_for": "IndividualCheck",
    "reference": 123456
}

patch

Accepts a check, setting its status to 'manually_accepted'.

Authorizations

Bearer

AuthorizationstringRequired

Path parameters

check_idstringRequired

Header parameters

Content-TypestringRequiredDefault: application/json

Body

application/json

commentstringOptional

A comment explaining the reason for accepting the check

Example: This is a comment for the acceptance of this check

comment_forstringOptional

The context of the comment, e.g., 'IndividualCheck'

Example: IndividualCheck

referenceintegerOptional

The unique reference ID for the check

Example: 123456

Responses

200

The check has been successfully accepted.

application/json

messagestringOptionalExample: Check accepted

401

Unauthorized request.

404

The check was not found.

patch

/check/{check_id}/accept

HTTPcURLJavaScriptPython

PATCH /api/v1/check/{check_id}/accept HTTP/1.1
Host: api.tiller-verify.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 115

{
  "comment": "This is a comment for the acceptance of this check",
  "comment_for": "IndividualCheck",
  "reference": 123456
}

{
  "message": "Check accepted"
}

Reject check

The Reject Check endpoint (/check/{check_id}/reject) provides the ability to reject a verification check manually. When a check fails or does not meet the required criteria, it can be flagged as manually_rejected through this endpoint. This ensures that the system maintains an accurate log of rejected checks and can trigger any necessary follow-up actions or notifications. By rejecting a check, administrators can control the verification process and ensure that unsuitable individuals are not processed further.

The following body is required in the request:

payload = {
    "comment": "This is a comment for the rejection of this check",
    "comment_for": "IndividualCheck",
    "reference": 123456
}

patch

Rejects a check, setting its status to 'manually_rejected'.

Authorizations

Bearer

AuthorizationstringRequired

Path parameters

check_idstringRequired

Header parameters

Content-TypestringRequiredDefault: application/json

Body

application/json

commentstringOptional

A comment explaining the reason for rejecting the check

Example: This is a comment for the rejection of this check

comment_forstringOptional

The context of the comment, e.g., 'IndividualCheck'

Example: IndividualCheck

referenceintegerOptional

The unique reference ID for the check

Example: 123456

Responses

200

The check has been successfully rejected.

application/json

messagestringOptionalExample: Check rejected

401

Unauthorized request.

404

The check was not found.

patch

/check/{check_id}/reject

HTTPcURLJavaScriptPython

PATCH /api/v1/check/{check_id}/reject HTTP/1.1
Host: api.tiller-verify.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 114

{
  "comment": "This is a comment for the rejection of this check",
  "comment_for": "IndividualCheck",
  "reference": 123456
}

{
  "message": "Check rejected"
}