API Reference

Key Concepts

The KYB API leverages several core concepts for building versatile processes that work with business data. These include GPaths, Inputs, Results, and Configurations:

GPaths

Inputs, results and configurations describe how data is supplied, processed and stored. Throughout this chain, we reference pieces of data by using "GPaths" (similar to JPath and JSONPath) to query individual pieces of data.

GPaths take the format $.some.possibly.nested.string

Inputs

Inputs are the foundational data provided to the API for merchant verification purposes. This data can include critical details such as company information, addresses, URLs, and identification documents. Once a merchant is created, inputs are submitted through the /merchants/{merchantId}/inputs endpoint in one of 2 JSON formats. These inputs trigger a series of processing and verification workflows that operate according to predefined KYB configurations, serving as the starting point for the entire verification process.

Formats

Nested JSON

Submit data in a nested JSON format. This is designed to allow for close matching to your data structures.

{
  "company": {
    "name": "Gratify Payments Inc",
    "address": "Suite 2412 205-50 Lonsdale Ave North Vancouver, BC V7M 2E6 Canada",
    "url": "https://www.gratifypay.com/",
    "phone": "+1 (778) 784-4188",
    "email": "[email protected]"
  },
  "linkedinUrl": "https://ca.linkedin.com/company/gratify-pay",
  "director": {
    "name": "Ryan Brough",
    "email": "[email protected]"
  },
  "industry": "FinTech"
}

JSON Array of GPaths

If preferred, you can submit an JSON array of Key/Value pairs.

[
  {
    "key": "$.company.name",
    "value": "Gratify Payments Inc"
  },
  {
    "key": "$.company.address",
    "value": "Suite 2412 205-50 Lonsdale Ave North Vancouver, BC V7M 2E6 Canada"
  },
  {
    "key": "$.company.url",
    "value": "https://www.gratifypay.com/"
  },
  {
    "key": "$.company.phone",
    "value": "+1 (778) 784-4188"
  },
  {
    "key": "$.company.email",
    "value": "[email protected]"
  },
  {
    "key": "$.linkedinUrl",
    "value": "https://ca.linkedin.com/company/gratify-pay"
  },
  {
    "key": "$.director.name",
    "value": "Ryan Brough"
  },
  {
    "key": "$.director.email",
    "value": "[email protected]"
  },
  {
    "key": "$.industry",
    "value": "FinTech"
  }
]

📘

The above two examples result in equivalent inputs

Results

Results are the outputs generated after processing the input data through the API’s verification and enrichment processes. These results provide detailed insights into the verification status of the merchant, including any relevant compliance findings or actionable insights. Accessible through the /merchants/{merchantId}/results endpoint.

Result output formats vary based on operation. For example, enrichment results will have enriched values, optional evidence and additional findings, while verification results will have the verification result and optional evidence

Example

{
  "key": "$.articlesOfIncorporation.businessNumber",
  "type": "enrich",
  "name": "Business Number",
  "source": {
    "file": "$.articlesOfIncorporation"
  },
  "method": "ocr",
  "data": {
    "metadata": [
      {
        "width": 0.17343294620513916,
        "id": "49ec0173-4ed5-489f-af89-2a7041481b7d",
        "page": 1,
        "top": 0.5622087121009827,
        "left": 0.0663570761680603,
        "height": 0.012485399842262268
      },
      {
        "width": 0.09639288485050201,
        "id": "6ebfb860-1964-47f7-873e-2686d87b4b75",
        "page": 1,
        "top": 0.5619584918022156,
        "left": 0.33841702342033386,
        "height": 0.010510648600757122
      },
      {
        "width": 0.10443806648254395,
        "id": "1835460c-40e7-4d88-8a21-3832379d875b",
        "page": 1,
        "top": 0.5791763663291931,
        "left": 0.06592530757188797,
        "height": 0.013188788667321205
      }
    ],
    "evidence": [
      "10.1.png"
    ],
    "confidence": 1,
    "ids": [
      "49ec0173-4ed5-489f-af89-2a7041481b7d",
      "6ebfb860-1964-47f7-873e-2686d87b4b75",
      "1835460c-40e7-4d88-8a21-3832379d875b"
    ],
    "excerpt": [
      "Example excerpt 1",
      "Example excerpt 2",
      "Example excerpt 3"
    ],
    "type": "enrich",
    "value": "123456789",
    "key": "$.articlesOfIncorporation.businessNumber"
  },
  "status": "COMPLETE"
}

Configurations

Configurations define the rules applied to the input data. They determine how data is enriched, verified, analyzed, and actioned, customizing the processing pathways to suit specific business requirements or compliance standards. Accessed via the /configs endpoint.

📘

Configurations are currently read-only through the API and managed by Gratify staff

Example

This configuration defined the enrichment that results in the above result. This enrichment is triggered once the $.articlesOfIncorporation input is provided, and the result is stored under $.articlesOfIncorporation.businessNumber

{
  "tenantId": "tenant_9e17e73d-33d5-428d-936b-b60a46457e01",
  "key": "$.articlesOfIncorporation.businessNumber",
  "type": "enrich",
  "name": "Business Number",
  "source": {
    "file": "$.articlesOfIncorporation"
  },
  "method": "ocr",
  "extract": "The company business number"
}

Data Flow Visualized

Below is a visual depiction of how data flows through Gratify KYB. The diagram shows 8 configurations - 2 inputs, 2 enrichments and 4 verifications.

Highlights

  • The process moves left to right - once Articles of Incorporation are uploaded, processes kick off that extract Business Number and Company Name.
  • Once Business Number is extracted and Certificate of Amendment is uploaded, a Business Number verification kicks off which determines if the two pieces of data match
  • The process continues with the other verifications, each triggering when all their dependencies are satisfied