# Multi-Bureau Check

## Run a multi-bureau check

To run a Multi-Bureau Check, you must [create a check ](https://docs.complycube.com/documentation/api-reference/core-resources/checks/create-a-check)with `type` set to `multi_bureau_check`.

This check can only be performed on a [client](https://docs.complycube.com/documentation/api-reference/core-resources/clients) of type `person`. Furthermore, the provided address must contain all **required** attributes in line with our [verifiable client attributes table.](https://app.gitbook.com/s/KyFKMqftsmT6qln9zo5y/identity-verification/multi-bureau-check/service-coverage) 

[Learn more about Multi-Bureau Checks](https://app.gitbook.com/s/KyFKMqftsmT6qln9zo5y/identity-verification/multi-bureau-check).

{% hint style="info" %}
This service includes a **2+2 check** variant that applies a more exhaustive and stringent matching engine. Get in touch with your Account Manager or [contact us](https://www.complycube.com/sales) to enable it.
{% endhint %}

## Check request

<table><thead><tr><th width="262.4">Attribute</th><th width="93">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>clientId</code></td><td>string</td><td>The ID of the client associated with this check. (<strong>Required</strong>)</td></tr><tr><td><code>type</code></td><td>string</td><td>This must be set to <code>multi_bureau_check</code>. (<strong>Required</strong>)</td></tr><tr><td><code>addressId</code></td><td>string</td><td>The ID of the address. (<strong>Required</strong>)</td></tr><tr><td><code>options</code></td><td>object</td><td>The optional settings for the check. Also, see the <a href="#the-options-object">options</a> object below. (<em>Optional</em>)</td></tr></tbody></table>

### The `options` object&#x20;

<table><thead><tr><th width="261.2809747140587">Attribute</th><th width="92.86814292903878">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>twoPlusTwo</code></td><td>boolean</td><td>This will verify at least two identity attributes with two or more separate bureaus. When this attribute is not provided, it will <strong>default to false.</strong></td></tr></tbody></table>

## Example requests

#### Simple request

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST https://api.complycube.com/v1/checks \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
          "clientId":"CLIENT_ID",
          "addressId":"ADDRESS_ID",
          "type": "multi_bureau_check"
        }'
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const check = await complycube.check.create("CLIENT_ID", {
        addressId: "ADDRESS_ID",
        type: "multi_bureau_check"
});
```

{% endtab %}

{% tab title="Python" %}

```python
check = cc_api.check.create(
    'CLIENT_ID', 
    'multi_bureau_check', 
    addressId='ADDRESS_ID'
)
```

{% endtab %}

{% tab title="PHP" %}

```php
$result = $ccapi->checks()->create('CLIENT_ID',
                                   ['type' => 'multi_bureau_check',
                                   'addressId' => 'ADDRESS_ID']);
```

{% endtab %}

{% tab title=".NET" %}

```csharp
var checkRequest = new CheckRequest {
  clientId = "CLIENT_ID",
  addressId = "ADDRESS_ID",
  type = "multi_bureau_check"
};

var check = await checkApi.CreateAsync(checkRequest);
```

{% endtab %}
{% endtabs %}

#### Request with optional attributes

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST https://api.complycube.com/v1/checks \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
          "clientId":"CLIENT_ID",
          "addressId":"ADDRESS_ID",
          "type": "multi_bureau_check",
          "options": {
                    "twoPlusTwo": true
          }
        }'
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const { ComplyCube } = require("@complycube/api");

const complycube = new ComplyCube({ apiKey: "<YOUR_API_KEY>" });

const check = await complycube.check.create("CLIENT_ID", {
    type: "multi_bureau_check",
    addressId: "ADDRESS_ID",
    options: {
        twoPlusTwo: true
    }
});
```

{% endtab %}

{% tab title="Python" %}

```python
from complycube import ComplyCubeClient

cc_api = ComplyCubeClient(api_key='<YOUR_API_KEY>')

request = {
    'addressId': 'ADDRESS_ID',
    'options': {
        'twoPlusTwo': True
    }
}

check = cc_api.checks.create('CLIENT_ID', 'multi_bureau_check', **request)
```

{% endtab %}

{% tab title="PHP" %}

```php
use ComplyCube\ComplyCubeClient;

$ccapi = new ComplyCubeClient('<YOUR_API_KEY>');
$check = [
    'type' => 'multi_bureau_check',
    'addressId' => 'ADDRESS_ID',
    'options' => [
        'twoPlusTwo' => true
    ]
];

$result = $ccapi->checks()->create('CLIENT_ID', $check);
```

{% endtab %}

{% tab title=".NET" %}

```csharp
using ComplyCube.Net;
using ComplyCube.Net.Resources.Checks;

var checkApi = new CheckApi(new ComplyCubeClient("<YOUR_API_KEY>"));

var checkRequest = new CheckRequest {
  clientId = "CLIENT_ID",
  type = "multi_bureau_check",
  addressId = "ADDRESS_ID"
};

checkRequest.options = new CheckRequestOptions {
  twoPlusTwo = true
};

var check = await checkApi.CreateAsync(checkRequest);
```

{% endtab %}
{% endtabs %}

## Result object

The `result` object is only returned when the status of the check is `complete` . It has two components - `outcome` and `breakdown`.

### Outcome

The outcome attribute represents the overall check result. Returned values include:

1. `clear`: Indicates sufficient client attributes are successfully matched against bureaus, and hence the client's identity is verified.
2. `attention`: Indicates that at least one of the client attributes is only partially matched, or none were matched at all, requiring attention.

### Breakdown

The breakdown comprises the following objects, which correspond to client attributes that are matched:

* `name`: Result and breakdown of whether the client's name has been matched.&#x20;
* `dob`: Result and breakdown of whether the client's DOB has been matched.&#x20;
* `address`: Result and breakdown of whether the client's address has been matched.&#x20;
* `idNumber`: Result and breakdown of whether the client's ID number has been matched. An ID number may to an [SSN, Social Insurance Number, National Identity Number, or Tax Number](https://docs.complycube.com/documentation/api-reference/core-resources/clients#the-persondetails-object).

Each of the aforementioned objects will constitute the following:

* `outcome`: For a given attribute, indicates whether a match was found with any of the bureaus. An outcome will have one of the following values:
  * `clear`: Indicates an attribute **fully** **matched** with data held by bureaus.
  * `attention`: Indicates an attribute **partially matched** with data held by bureaus.&#x20;
  * `not_processed`: Indicates an attribute was **not found** by bureaus.
* `breakdown`: An array of objects detailing the match source. The object has the following attributes:
  * `status`: Indicates whether a source or bureau has matched a client attribute.
    * `clear`: Indicates the source has **fully matched** the data attribute.
    * `attention`: Indicates the source has **partially matched** the data attribute.&#x20;
  * `source`: The source or bureau type that has matched the attribute. Values include:
    * `credit_agency`
    * `government_authority`
    * `commercial_database`
    * `consumer_database`
    * `utility_authority`
    * `proprietary_database`
    * `telecom_agency`
    * `postal_authority`
    * `other_source`
* `country`: The country of the source or bureau that has matched the attribute. This will be the [two-letter country ISO code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).&#x20;
* `hits`: The number of times an attribute has been fully or partially matched by sources of a given type.

## Sample Response

```javascript
{
   "id": "614cfa9460fe4700098f3af1",
   "entityName": "John Doe",
   "type": "multi_bureau_check",
   "clientId": "5e94b75d01bce00008c86f02",
   "addressId": "6149f415cb31190008991522",
   "status": "complete",
   "result": {
      "outcome": "attention",
      "breakdown": {
         "name": {
            "outcome": "clear",
            "breakdown": [
               {
                  "status": "clear",
                  "source": "credit_agency",
                  "country": "US",
                  "hits": 1
               },
               {
                  "status": "clear",
                  "source": "government_authority",
                  "country": "US",
                  "hits": 1
               }
            ]
         },
         "address": {
            "outcome": "clear",
            "breakdown": [
               {
                  "status": "clear",
                  "source": "government_authority",
                  "country": "US",
                  "hits": 1
               }
            ]
         },
         "dob": {
            "outcome": "clear",
            "breakdown": [
               {
                  "status": "clear",
                  "source": "commercial_database",
                  "country": "US",
                  "hits": 1
               },
               {
                  "status": "clear",
                  "source": "credit_agency",
                  "country": "US",
                  "hits": 1
               }
            ]
         },
         "idNumber": {
            "outcome": "attention",
            "breakdown": [
               {
                  "status": "attention",
                  "source": "government_authority",
                  "country": "US",
                  "hits": 1
               }
            ]
         },
         "additionalChecks": {
            "outcome": "not_processed"
         }
      }
   },
   "createdAt": "2021-04-04T17:25:21.116Z",
   "updatedAt": "2021-04-04T17:25:26.116Z"
}
```