# Canada

Canada eKYC verification matches submitted individual data against Canadian sources of truth. See the [eKYC API Reference](https://developer.incode.com/docs/ekyc-api-reference) for common response semantics that apply across all sources.

## Available sources

| Source                   | API source string                   | Description                                                                                      |
| ------------------------ | ----------------------------------- | ------------------------------------------------------------------------------------------------ |
| CA RES CREDIT            | `CA_RES_CREDIT`                     | Verifies submitted data against Canadian residential and credit records.                         |
| CA Credit Bureau FINTRAC | {/* TODO: source string unknown */} | Verifies submitted data against Canadian credit bureau records for FINTRAC compliance workflows. |

{/* TODO: Confirm with PM — no existing API documentation is available for CA Credit Bureau FINTRAC. Provide source string, request parameter list, response schema, and overallLevel calculation. Also confirm the customer-facing description covering what the source verifies against and the typical customer use case. */}

## CA RES CREDIT

### Request parameters

| Parameter     | Required  | Description                                                |
| ------------- | --------- | ---------------------------------------------------------- |
| `source`      | Mandatory | Must be `CA_RES_CREDIT`.                                   |
| `country`     | Mandatory | Must be `CA`.                                              |
| `firstName`   | Mandatory | First name of the individual.                              |
| `middleName`  | Optional  | Middle name of the individual.                             |
| `surName`     | Mandatory | Last name of the individual.                               |
| `street`      | Mandatory | Street name and house number.                              |
| `city`        | Mandatory | City of the individual's address (for example, `Toronto`). |
| `state`       | Mandatory | Province.                                                  |
| `postalCode`  | Mandatory | Postal code.                                               |
| `dateOfBirth` | Mandatory | Format: `yyyy-mm-dd`.                                      |
| `phone`       | Optional  | Phone number.                                              |

### Response fields

CA RES CREDIT anchors verification on the source-of-truth register. See the [eKYC API Reference](https://developer.incode.com/docs/ekyc-api-reference) for common match field definitions and status values.

| Field              | Statuses                    | Description                                                                                                 |
| ------------------ | --------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `firstNameMatch`   | `exact`, `nomatch`          | Matches first name submitted against the value in the source of truth.                                      |
| `middleNameMatch`  | `exact`, `nomatch`          | Matches middle name submitted against the value in the source of truth.                                     |
| `lastNameMatch`    | `exact`, `nomatch`          | Matches last name submitted against the value in the source of truth.                                       |
| `fullNameMatch`    | `exact`, `nomatch`          | Matches full name submitted against the value in the source of truth.                                       |
| `dobMatch`         | `exact`, `nomatch`          | Matches date of birth submitted against the value in the source of truth.                                   |
| `streetMatch`      | `exact`, `nomatch`          | Matches street submitted against the value in the source of truth.                                          |
| `cityMatch`        | `exact`, `nomatch`          | Matches city submitted against the value in the source of truth.                                            |
| `stateMatch`       | `exact`, `nomatch`          | Matches province submitted against the value in the source of truth.                                        |
| `postalCodeMatch`  | `exact`, `nomatch`          | Matches postal code submitted against the value in the source of truth.                                     |
| `fullAddressMatch` | `exact`, `fuzzy`, `nomatch` | Matches full address (street, city, state, postal code) submitted against the value in the source of truth. |
| `phoneMatch`       | `exact`, `nomatch`          | Matches phone submitted against the value in the source of truth.                                           |
| `overallLevel`     | `low`, `medium`, `high`     | Overall risk level. See below for calculation logic.                                                        |

### overallLevel calculation

`overallLevel` is calculated based on the risk associated with the submitted full name, postal code, and date of birth:

- `low` when `fullNameMatch`, `postalCodeMatch`, and `dobMatch` are all `exact`.
- `high` when `fullNameMatch`, `postalCodeMatch`, and `dobMatch` are all `nomatch`.
- `medium` for all other combinations.

Contact your Incode representative to customize the `overallLevel` calculation for your use case.

### Sample response

```json
{
    "kyc": [
        { "key": "firstNameMatch", "status": "exact" },
        { "key": "middleNameMatch", "status": "exact" },
        { "key": "lastNameMatch", "status": "nomatch" },
        { "key": "fullNameMatch", "status": "nomatch" },
        { "key": "dobMatch", "status": "exact" },
        { "key": "streetMatch", "status": "exact" },
        { "key": "cityMatch", "status": "exact" },
        { "key": "stateMatch", "status": "exact" },
        { "key": "postalCodeMatch", "status": "exact" },
        { "key": "fullAddressMatch", "status": "fuzzy" },
        { "key": "phoneMatch", "status": "nomatch" },
        { "key": "overallLevel", "status": "medium" }
    ]
}
```

## CA Credit Bureau FINTRAC

{/* TODO: No existing API documentation is available for this source. Request source string, request parameter list, response schema, and overallLevel calculation from PM. */}

Documentation for this source is forthcoming. Contact your Incode representative for details in the meantime.