> For the complete documentation index, see [llms.txt](https://docs.complycube.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.complycube.com/documentation/api-reference/check-types/proof-of-address-check.md).

# Proof of Address Check

Proof of Address Check API for KYC address verification, OCR extraction, document analysis, and client address validation.

## Run a proof of address check

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

This check can only be performed on a [client](/documentation/api-reference/core-resources/clients.md) of type `person`. Furthermore, the `documentId` provided must have associated image attachments that adhere to our [image specifications](/documentation/api-reference/check-types/document-check.md#image-specifications).

[Learn more about Proof of Address Checks](/documentation/product-guides/kyc-automation-services/proof-of-address-check.md).

{% hint style="info" %}
We will use the **front side** of the document for the Proof of Address Check.
{% endhint %}

## Check request

<table><thead><tr><th width="283.4">Attribute</th><th width="91">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>proof_of_address_check</code>. (<strong>Required</strong>)</td></tr><tr><td><code>documentId</code></td><td>string</td><td>The ID of the document. (<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 <a href="#the-options-object" id="the-options-object"></a>

<table><thead><tr><th width="270.2809747140587">Attribute</th><th>Description</th></tr></thead><tbody><tr><td><code>documentTypeValidation</code></td><td><p><strong>Type</strong>: <code>boolean</code><br></p><p>Enables validation of the detected document type against the permitted document types. Defaults to <strong>false</strong> if not provided.</p></td></tr><tr><td><code>analysisCoverage</code></td><td><p><strong>Type</strong>: <code>array[string]</code><br></p><p>The types of analysis to conduct as part of a proof of address check. You can specify either a whole analysis type, which covers all of its sub-checks, or an individual sub-type for more granular control.</p><p></p><p>Valid analysis types include:</p><ul><li><code>client_validation</code></li><li><code>content_analysis</code></li><li><code>geo_location_analysis</code></li></ul><p></p><p>Valid sub-types include:</p><ul><li><code>client_validation.first_name</code></li><li><code>client_validation.last_name</code></li><li><code>client_validation.address</code></li><li><code>content_analysis.document_age</code></li><li><code>geo_location_analysis.ip_in_address_country</code></li><li><code>geo_location_analysis.ip_proximity_to_address</code></li></ul><p></p><p>When this attribute is not provided, we will conduct all analysis types.</p></td></tr></tbody></table>

## Example 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",
          "documentId":"DOCUMENT_ID",
          "type": "proof_of_address_check"
        }'
```

{% endtab %}

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

```json
const check = await complycube.check.create("CLIENT_ID", {
        documentId: "DOCUMENT_ID",
        type: "proof_of_address_check"
});
```

{% endtab %}

{% tab title="Python" %}

```python
check = cc_api.check.create(
    'CLIENT_ID',
    'proof_of_address_check',
    documentId='DOCUMENT_ID'
)
```

{% endtab %}

{% tab title="PHP" %}

```php
$result = $ccapi->checks()->create(
    'CLIENT_ID',
    [
        'type' => 'proof_of_address_check',
        'documentId' => 'DOCUMENT_ID'
    ]
);
```

{% endtab %}

{% tab title=".NET" %}

```csharp
var checkRequest = new CheckRequest {
  clientId = "CLIENT_ID",
  documentId = "DOCUMENT_ID",
  type = "proof_of_address_check"
};

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 every analysis conducted returned a successful result, and hence the proof of address document is valid.
2. `attention`: Indicates at least one of the analysis results requires attention.

### Breakdown

The breakdown comprises the following objects:

#### `extractedData` object

The data extracted using [Optical Character Recognition (OCR)](https://en.wikipedia.org/wiki/Optical_character_recognition). It has the following constituents:

* `documentDetails`: Data relating to the document.
  * `documentType`: The detected document type. Values include:
    * `bank_statement`
    * `driving_license`
    * `utility_bill`
    * `tax_document`
    * `financial_statement`
    * `council_tax_bill`
    * `insurance_document`
    * `tenancy_agreement`
    * `government_letter`
    * `benefits_statement`
  * `issuer`: The document issuing vendor.
  * `issuingDate`: The issuing date of the document. This will be a [structured date](/documentation/api-reference/core-resources/checks.md#structured-date-format).
* `holderDetails` : Data relating to the document holder.
  * `entityName`: The full extracted name of the document holder.
* `addressDetails` : Data relating to the extracted address.
  * `addressLine`: The extracted address line as a string.
  * `addressCountry`: The address country. This will be the [two-letter country ISO code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
  * `address`: This will be the structured address, which includes the following:
    * `propertyNumber`: The property number.
    * `building`: The building name.
    * `line`: The address line.
    * `city`: The address city.
    * `state`: The address state.
    * `postalCode`: The address postal code.
    * `country`: The address country. This will be the [two-letter country ISO code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
    * `latLong`: The address latitude and longitude geographic coordinates.

#### Analysis

For each conducted analysis, the returned values include:

1. `clear`: Indicates the analysis returned a successful result.
2. `attention`: Indicates a potential falsified or fraudulent document.
3. `not_processed`: Returned when ComplyCube is not able to process the document. This can occur due to a number of reasons, including:
   * The document image is invalid
   * The document image is of poor quality and therefor unreadable

#### `clientValidation` object

The client validation results. It has the following constituents::

* `firstName`: Indicates whether the client provided first name matches the extracted entity name.
* `lastName`: Indicates whether the client provided last name matches the extracted entity name.
* `address`: Indicates whether any of the client provided addresses match the extracted address.

#### `contentAnalysis` object

The content analysis results. It has the following constituents:

* `documentAge`: Indicates the document had expired (when it's a Driving License) or is older than 3 months when it's a Bank Statement, Utility Bill, Tax Document, etc.
* `documentType`: Indicates whether the detected document type matches one of the permitted document types.

#### `geolocationAnalysis` object

The geolocation analysis results. It has the following constituents:

* `ipInAddressCountry`: Indicates the geolocation of the client IP address resides in the extracted address country.
* `ipProximityToAddress`: Indicates the geolocation of the client IP address is within a reasonable distance from the extracted address country.

## Sample Response

```javascript
{
   "id": "614cfa9460fe4700098f3af9",
   "entityName": "John Doe",
   "type": "proof_of_address_check",
   "clientId": "5e94b75d01bce00008c86f02",
   "documentId": "6149f415cb31190008991526",
   "status": "complete",
   "result": {
      "outcome": "clear",
      "breakdown": {
         "extractedData": {
            "holderDetails": {
               "entityName": "John Doe"
            },
            "documentDetails": {
               "documentType": "bank_statement",
               "issuer": "Barclays Bank",
               "issuingDate": {
                  "day": 25,
                  "month": 1,
                  "year": 2021
               }
            },
            "addressDetails": {
               "address": {
                  "propertyNumber": "323",
                  "line": "Common street",
                  "city": "Aldgate",
                  "state": "London",
                  "postalCode": "W99 0RD",
                  "country": "GB",
                  "latLong": "51.5136,-0.077188"
               },
               "addressLine": "323 Common Street Aldgate London W99 0RD",
               "addressCountry": "GB"
            }
         },
         "clientValidation": {
            "firstName": "clear",
            "lastName": "clear",
            "address": "clear"
         },
         "contentAnalysis": {
            "documentAge": "clear",
            "documentType": "not_processed"
         },
         "geoLocationAnalysis": {
            "ipInAddressCountry": "clear",
            "ipProximityToAddress": "clear"
         }
      }
   },
   "createdAt": "2021-04-04T17:25:21.116Z",
   "updatedAt": "2021-04-04T17:25:33.116Z"
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.complycube.com/documentation/api-reference/check-types/proof-of-address-check.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.