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.

POST - Create a verification process with external IDs

post
Authorizations
Body

Verification check request DTO

externalReferenceIdstring | nullableOptional

External reference ID

clientEmailstring | nullableOptional
clientIdstring | nullableOptional
Responses
200
OK request
application/json
post
POST /api/v1/verifications HTTP/1.1
Host: 
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 2796

{
  "options": {
    "runAsync": true,
    "mock": true,
    "piiDataObscure": true
  },
  "externalReferenceId": "text",
  "checks": [
    {
      "checkTypeId": 1,
      "checkMethod": 1,
      "matchesRequired": 1,
      "maximumSources": 1,
      "externalCheckReferenceId": "text",
      "enableOngoingMonitoring": true,
      "filters": {
        "byDob": {
          "includeAllDob": true,
          "includeFullDob": true,
          "includeYearOnlyDob": true,
          "includeYearOnlyDobTolerance": 1,
          "excludeIfSourceDobUnknown": true
        },
        "byName": {
          "nameMatchType": 0,
          "nameMatchMethod": 0,
          "nameMatchMethodTolerance": 1
        },
        "byGender": {
          "excludeGenderMatch": true,
          "excludeIfSourceGenderUnknown": true
        },
        "byPepType": {
          "excludePepTypes": [
            "text"
          ],
          "excludePepByFamilyAssociation": true
        },
        "byAdverseMediaType": {
          "excludeAdverseMediaTypes": [
            "text"
          ]
        }
      }
    }
  ],
  "profile": {
    "titleId": 1,
    "cardTypes": [
      {
        "cardTypeId": 1,
        "cardNumber": "text"
      }
    ],
    "genderTypeId": 1,
    "firstName": "text",
    "middleName": "text",
    "lastName": "text",
    "maidenSecondLastName": "text",
    "dateOfBirth": "2025-07-09T07:10:27.255Z",
    "countryOfBirthCountryCode": "text",
    "placeOfBirthTownCity": "text",
    "nationalityCountryCode": "text",
    "maritalStatusId": 1,
    "mobileNumber": "text",
    "landlineNumber": "text",
    "email": "[email protected]",
    "bankDetails": {
      "accountNumber": "text",
      "sortCode": "text",
      "openedDate": "2025-07-09T07:10:27.255Z"
    },
    "currentAddress": {
      "unStructured": {
        "address1": "text",
        "address2": "text",
        "address3": "text",
        "address4": "text",
        "address5": "text",
        "townCity": "text",
        "stateCounty": "text",
        "postZipCode": "text",
        "countryCode": "text",
        "dateFrom": "2025-07-09T07:10:27.255Z",
        "dateTo": "2025-07-09T07:10:27.255Z"
      },
      "structured": {
        "flatApartmentSubBuilding": "text",
        "buildingNumber": "text",
        "buildingName": "text",
        "roadStreet": "text",
        "district": "text",
        "townCity": "text",
        "stateProvinceName": "text",
        "stateProvinceCode": "text",
        "postZipCode": "text",
        "countryCode": "text",
        "dateFrom": "2025-07-09T07:10:27.255Z",
        "dateTo": "2025-07-09T07:10:27.255Z"
      }
    },
    "previousAddresses": [
      {
        "unStructured": {
          "address1": "text",
          "address2": "text",
          "address3": "text",
          "address4": "text",
          "address5": "text",
          "townCity": "text",
          "stateCounty": "text",
          "postZipCode": "text",
          "countryCode": "text",
          "dateFrom": "2025-07-09T07:10:27.255Z",
          "dateTo": "2025-07-09T07:10:27.255Z"
        },
        "structured": {
          "flatApartmentSubBuilding": "text",
          "buildingNumber": "text",
          "buildingName": "text",
          "roadStreet": "text",
          "district": "text",
          "townCity": "text",
          "stateProvinceName": "text",
          "stateProvinceCode": "text",
          "postZipCode": "text",
          "countryCode": "text",
          "dateFrom": "2025-07-09T07:10:27.255Z",
          "dateTo": "2025-07-09T07:10:27.255Z"
        }
      }
    ]
  },
  "companyDetails": {
    "countryCode": "text",
    "state": "text",
    "companyName": "text",
    "companyNumber": "text",
    "companyAddress": "text",
    "branch": "text"
  },
  "officerDetails": {
    "countryCode": "text",
    "state": "text",
    "companyName": "text",
    "companyNumber": "text",
    "companyAddress": "text",
    "firstName": "text",
    "middleName": "text",
    "lastName": "text",
    "officerId": "text",
    "position": "text"
  },
  "clientEmail": "text",
  "clientId": "text"
}
{
  "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-07-09T07:10:27.255Z",
        "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"
  }
}

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.

GET - Get verification statuses and result for a verification process

get
Authorizations
Path parameters
correlationIdstring · uuidRequired
Responses
200
Ok request
application/json
get
GET /api/v1/verifications/{correlationId} 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-07-09T07:10:27.255Z",
          "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"
    }
  }
]

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.

GET - Get verification reference fields

get
Authorizations
Responses
200
Ok request
application/json
get
GET /api/v1/verifications/references HTTP/1.1
Host: 
Authorization: Bearer JWT
Accept: */*
[
  {
    "referenceName": "text",
    "referenceCategory": "text",
    "referenceCode": "text",
    "referenceId": 1
  }
]

Last updated