Quickstart

1. Get your API keys

The first step is to reach out to our sales team and request API keys for your account. You will receive two API keys: a live API key and a test API key.

Live API key

The live API key provides access to the real production service.

Client data in the production service is pooled together and matched against existing records. If you submit a record that indicates someone committed fraud, that information will be available when other clients look up that applicant.

Production is a regulated environment, so be careful to only upload correct information. If you accidentally upload information that is inaccurate, let our team know right away and we will rollback any mistakes.

Test API key

The test API key provides access to a sandbox environment where you can learn how to use the service and experiment with test records.

The sandbox environment is completely isolated. Only you can see what is uploaded. You will submit and match with your own records to learn how the matching engine and overall service works before moving on to the production environment.

2. Submit a test record

Now it’s time to submit your first record in the test environment.

Unique Reference

A reference must be provided for each record. Make each reference unique so that new records do not replace existing records.

HTTP Request
PUT /reports/my-loan-1

Request Body
{
  "status": "rejected",
  "flags": [
    "identity-theft"
  ],
  "entities": [
    {
      "role": "applicant",
      "entity_name": "ABC Inc",
      "dba": "Royal Flush Entertainment",
      "entity_type": "corporation",
      "entity_number": "777777777",
      "established": "2019-05"
    }
  ],
  "individuals": [
    {
      "role": "director",
      "legal_name": "Mitchel Chernoff",
      "dob": "1962-06-18",
      "addresses": [
        {
          "type": "home",
          "address": "715 15th St, Castlegar, BC, V1N 2K8"
        }
      ],
      "phones": [
        {
          "type": "work",
          "phone": "250-365-8480"
        }
      ],
      "sin": "046-45-4286"
    }
  ]
}

3. View the test record

Search for the record you uploaded by using the reference you initially provided.

HTTP Request
GET /reports/my-loan-1

4. Match on business data

Try to submit a record with similar business information. This will generate a match.

HTTP Request
PUT /reports/my-loan-2

Request Body
{
  "status": "submitted",
  "entities": [
    {
      "role": "applicant",
      "entity_name": "ABC Inc",
      "dba": "Cannabis Delivery Network",
      "entity_type": "corporation",
      "entity_number": "420420420",
      "established": "2020-04-20"
    }
  ],
  "individuals": [
    {
      "role": "director",
      "legal_name": "Marc Bray",
      "dob": "1981-11-16",
      "addresses": [
        {
          "type": "home",
          "address": "4880 St Marys Rd, Winnipeg, Manitoba, R3C 3N9"
        }
      ],
      "phones": [
        {
          "type": "personal",
          "phone": "204-952-1899"
        }
      ],
      "sin": "087-440-293"
    }
  ]
}

View the matching records by looking up the search hits. It can take a couple seconds for submitted records to go through the matching engine.

HTTP Request
GET /reports/my-loan-2/hits

In the response, you will only see matching information. The rest of the data will be masked. This is consistent with how you will view matching records in the production environment.

Learn more about data masking.

5. Match on personal data

Match on individual data instead of business data this time.

HTTP Request
PUT /reports/my-loan-3

Request Body
{
  "status": "submitted",
  "entities": [
    {
      "role": "applicant",
      "entity_name": "The Berry Pie Factory Ltd",
      "entity_type": "corporation",
      "entity_number": "314314314",
      "established": "2020-03-14"
    }
  ],
  "individuals": [
    {
      "role": "director",
      "legal_name": "Mitchel Chernoff",
      "dob": "1962",
      "addresses": [
        {
          "type": "home",
          "address": "4318 Queens Bay, Castlegar, BC, V0G 2G0"
        }
      ],
      "phones": [
        {
          "type": "work",
          "phone": "250-365-8480"
        }
      ],
      "sin": "046-45-4286"
    }
  ]
}

View the matching records by looking up the search hints. In the production environment you will receive a webhook if there are matching records.

HTTP Request
GET /reports/my-loan-3/hits

6. Submit data with different fields

If you submit a record with different fields from all other records, it will not generate any matches.

HTTP Request
PUT /reports/my-loan-4

Request Body
{
  "status": "submitted",
  "entities": [
    {
      "role": "applicant",
      "entity_name": "Yoga With Hannah",
      "entity_type": "sole-proprietorship",
      "entity_number": "555555555",
      "established": "2020"
    }
  ],
  "individuals": [
    {
      "role": "partner",
      "legal_name": "Hannah Powell",
      "dob": "1992-10-15",
      "emails": [
        {
          "type": "personal",
          "email": "hannahpow92@gmail.com"
        }
      ],
      "sin": "745 295 253"
    }
  ]
}

If you look up matching records, it will return empty results.

HTTP Request
GET /reports/my-loan-4/hits

7. Test your own records

Now that you’re getting a feel for how Lenders API works, try matching some of your own records. Continue practicing in the test sandbox environment until you’re ready to use the live production environment.