# Multi-Bureau Check

## Run a multi-bureau check

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

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

[Learn more about Multi-Bureau Checks](/documentation/product-guides/identity-verification/multi-bureau-check.md).

{% 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

<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" %}

```json
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.
* `dob`: Result and breakdown of whether the client's DOB has been matched.
* `address`: Result and breakdown of whether the client's address has been matched.
* `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](/documentation/api-reference/core-resources/clients.md#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.
  * `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.
  * `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).
* `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"
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.complycube.com/documentation/api-reference/check-types/multi-bureau-check.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.