# Perform Proof of Address Check

## Overview <a href="#overview" id="overview"></a>

This guide shows you how to run a Proof of Address check using the ComplyCube API.

{% hint style="success" %}
You can try this check right away using our [Demo Postman Collection](https://docs.complycube.com/documentation/integration-resources/postman#demo-collection). It’s publicly accessible and **requires no account**.
{% endhint %}

## Integration steps <a href="#create-an-applicant" id="create-an-applicant"></a>

<figure><img src="https://2950143584-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fsw26JqCBnT6AEIbxAYyk%2Fuploads%2FX5KkbEyaMHzL3jmwA3Re%2Fdocumentation-POA%20Check.png?alt=media&#x26;token=0f09057f-d660-4feb-9dcd-05fb273d01e2" alt=""><figcaption><p>Proof of Address Check API Guide</p></figcaption></figure>

{% stepper %}
{% step %}

#### Create a client <a href="#create-an-applicant" id="create-an-applicant"></a>

The first step in creating any check is to add a **client** from your backend server. A client can represent either a **person** or a **company**.

The response will contain an `id` (the Client ID). It is required for the next step.

**Example request for creating a client**&#x20;

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

```bash
curl -X POST https://api.complycube.com/v1/clients \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
          "type": "person",
          "email": "john.doe@example.com",
          "personDetails":{
               "firstName": "John",
               "lastName" :"Doe",
               "dob": "1990-01-01"
          }
        }'
```

{% endtab %}

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

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

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

const client = await complycube.client.create({
  type: "person",
  email: "john.doe@example.com",
  personDetails: {
    firstName: "John",
    lastName: "Doe",
    dob: "1990-01-01"
  }
});
```

{% endtab %}

{% tab title="Python" %}

```python
from complycube import ComplyCubeClient

cc_api = ComplyCubeClient(api_key='<YOUR API KEY>')

new_client = {
    'type':'person',
    'email':'john.doe@example.com',
    'personDetails': {
        'firstName':'John',
        'lastName':'Doe',
        'dob':'1990-01-01'
    }
}

client = cc_api.clients.create(**new_client)
```

{% endtab %}

{% tab title="PHP" %}

```php
use ComplyCube\ComplyCubeClient;

$ccapi = new ComplyCubeClient('<YOUR_API_KEY>');

$result = $ccapi->clients()->create([
    'type' => 'person',
    'email' => 'john.doe@example.com',
    'personDetails' => [
        'firstName' => 'John',
        'lastName' => 'Doe',
        'dob' => '1990-01-01'
    ]
]);
```

{% endtab %}

{% tab title=".NET" %}

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

var clientApi = new ClientApi(new ComplyCubeClient("<YOUR_API_KEY>"));

var newclient = new ClientRequest {
  type = "person",
    email = "john.doe@example.com",
    personDetails = new PersonDetails {
      firstName = "John",
        lastName = "Doe",
        dob = "1990-01-01"
    }
}

var client = await clientApi.CreateAsync(newclient);
```

{% endtab %}
{% endtabs %}

**Example response**

```javascript
{
    "id": "5eb04fcd0f3e360008035eb1",
    "type": "person",
    "email": "john.doe@example.com",
    "personDetails": {
        "firstName": "John",
        "lastName": "Doe",
        "dob": "1990-01-01"
    },
    "createdAt": "2025-01-04T17:24:29.146Z",
    "updatedAt": "2025-01-04T17:24:29.146Z"
}
```

{% endstep %}

{% step %}

#### Create an address

Create an address by providing the **Client ID** and address details.

The response will contain an `id` (the Address ID). It is required later.

**Example request for creating an address**

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

```bash
curl -X POST https://api.complycube.com/v1/addresses \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
            "clientId":"5eb04fcd0f3e360008035eb1",
            "line": "47th Test Avenue 323",
            "city": "Manhattan",
            "postalCode": "10001",
            "state": "NY",
            "country": "US"
        }'
```

{% endtab %}

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

```javascript
const address = await complycube.address.create("5eb04fcd0f3e360008035eb1", {
  line: "47th Test Avenue 323",
  city: "Manhattan",
  postalCode: "10001",
  state: "NY",
  country: "US"
});
```

{% endtab %}

{% tab title="Python" %}

```python
new_address = {    
    'line': '47th Test Avenue 323',
    'city': 'Manhattan',
    'postalCode': '10001',
    'state': 'NY',
    'country': 'US'
}

address = cc_api.addresses.create('5eb04fcd0f3e360008035eb1',**new_address)
```

{% endtab %}

{% tab title="PHP" %}

```php
$address = $ccapi->address()->create(
    '5eb04fcd0f3e360008035eb1',
    [
        'line' => '47th Test Avenue 323',
        'city' => 'Manhattan',
        'postalCode' => '10001',
        'state' => 'NY',
        'country' => 'US'
    ]
);
```

{% endtab %}

{% tab title=".NET" %}

```csharp
var addressRequest = new AddressRequest {
  clientId = "5eb04fcd0f3e360008035eb1",
  line = "47th Test Avenue 323",
  city = "Manhattan",
  postalCode = "10001",
  state = "NY",
  country = "US"
};

var address = await addressApi.CreateAsync(addressRequest);
```

{% endtab %}
{% endtabs %}

**Example response**

```javascript
{
    "id": "5ebd40714f23960008c81528",
    "clientId":"5eb04fcd0f3e360008035eb1",
    "line": "47th Test Avenue 323",
    "city": "Manhattan",
    "postalCode": "10001",
    "state": "NY",
    "country": "US",
    "createdAt": "2021-01-04T17:25:21.116Z",
    "updatedAt": "2021-01-04T17:25:21.116Z"
}
```

{% endstep %}

{% step %}

#### Create a document <a href="#create-an-applicant" id="create-an-applicant"></a>

Create a document by providing the **Client ID** and **document type** (e.g. bank statement).

The response will contain an `id` (the Document ID). It is required for the next step.

**Example request for creating a document**

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

```bash
curl -X POST https://api.complycube.com/v1/documents \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
          "clientId":"5eb04fcd0f3e360008035eb1",
          "type": "bank_statement"
        }'
```

{% endtab %}

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

```javascript
const document = await complycube.document.create("5eb04fcd0f3e360008035eb1", {
  type: "bank_statement"
});
```

{% endtab %}

{% tab title="Python" %}

```python
document = cc_api.documents.create(
    '5eb04fcd0f3e360008035eb1',
    type='bank_statement'
)
```

{% endtab %}

{% tab title="PHP" %}

```php
$doc = $ccapi->documents()->create(
    '5eb04fcd0f3e360008035eb1',
    ['type' => 'bank_statement']
);
```

{% endtab %}

{% tab title=".NET" %}

```csharp
var docRequest = new DocumentRequest {
  clientId = "5eb04fcd0f3e360008035eb1",
  type = "bank_statement"
};

var document = await docApi.CreateAsync(docRequest);
```

{% endtab %}
{% endtabs %}

**Example response**

The response will contain an `id` (the Document ID). It is required for the next step.

```javascript
{
    "id": "5ebd40714f23960008c81527",
    "type": "bank_statement",
    "createdAt": "2025-01-04T17:25:21.116Z",
    "updatedAt": "2025-01-04T17:25:21.116Z"
}
```

{% endstep %}

{% step %}

#### Upload document

Upload a BASE64-encoded image of the proof of address document.

Images must be in **JPG**, **PNG**, or **PDF** format and between **34 KB** and **4 MB** in size.

Below is a sample BASE64-encoded file. Download it, copy its contents, and paste them into the `data` attribute when making the request

{% file src="<https://content.gitbook.com/content/sw26JqCBnT6AEIbxAYyk/blobs/vCjFkxXWT2Tp3vMDbsBX/base64-encoded-bank-statement-sample.txt>" %}
Sample - BASE64 encoded bank statement
{% endfile %}

**Example request for uploading an image of a document**

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

```bash
 curl -X POST https://api.complycube.com/v1/documents/5ebd40714f23960008c81527/upload/front \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
         "fileName": "bank-statement-sample.pdf",
         "data": "<BASE64_DATA_CONTENT>"
        }'
```

{% endtab %}

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

```javascript
const frontImage = await complycube.document.upload("5ebd40714f23960008c81527", {
    fileName: "bank-statement-sample.pdf",
    data: "<BASE64_DATA_CONTENT>"
}, "front");
```

{% endtab %}

{% tab title="Python" %}

```python
front_image = cc_api.documents.upload(
    '5ebd40714f23960008c81527', 
    'front',
    fileName='bank-statement-sample.pdf',
    data='<BASE64_DATA_CONTENT>'
)
```

{% endtab %}

{% tab title="PHP" %}

```php
$up = $ccapi->documents()->upload(
    '5ebd40714f23960008c81527', 
    'front', 
    [
        'fileName' => 'bank-statement-sample.pdf',
        'data' => '<BASE64_DATA_CONTENT>'
    ]
);
```

{% endtab %}

{% tab title=".NET" %}

```csharp
var docFront = new ImageRequest {
  fileName = "bank-statement-sample.pdf",
  data = "<BASE64_DATA_CONTENT>"
};

var img = await docApi.UploadImageAsync(
    "5ebd40714f23960008c81527",
    "front",
    docFront
);

```

{% endtab %}
{% endtabs %}

**Example response**

The response will contain an `id` (the Check ID). It is required for the next step.

```javascript
{
    "id": "5eb169302d868c0008828591",
    "fileName": "bank-statement-sample.pdf",
    "documentSide": "front",
    "downloadLink": "/documents/5ebd40714f23960008c81527/images/5eb169302d868c0008828591/download",
    "contentType": "application/pdf",
    "size": 182716,
    "createdAt": "2025-01-04T17:25:21.116Z",
    "updatedAt": "2025-01-04T17:25:21.116Z"
}
```

{% endstep %}

{% step %}

#### Create a check

Create a check by providing the **Client ID**, **Document ID**, and **check type**.

The response will contain an `id` (the Check ID). It is required for the next step.

**Example request for creating a check**

{% 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":"5eb04fcd0f3e360008035eb1",
          "documentId":"5ebd40714f23960008c81527",
          "type": "proof_of_address_check"
        }'
```

{% endtab %}

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

```javascript
const check = await complycube.check.create("5eb1276d96be4a0008713af5", {
    documentId: "5ebd40714f23960008c81527",
    type: "proof_of_address_check"
});
```

{% endtab %}

{% tab title="Python" %}

```python
check = cc_api.checks.create(
    '5eb1276d96be4a0008713af5',
    'proof_of_address_check',
    documentId='5ebd40714f23960008c81527'
)
```

{% endtab %}

{% tab title="PHP" %}

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

{% endtab %}

{% tab title=".NET" %}

```csharp
var checkRequest = new CheckRequest {
  clientId = "5eb04fcd0f3e360008035eb1",
  documentId = "5ebd40714f23960008c81527",
  type = "proof_of_address_check"
};

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

{% endtab %}
{% endtabs %}

**Example response**

```javascript
{
    "id": "65c12a6426d2ab000814037e",
    "entityName": "John Doe",
    "type": "proof_of_address_check",
    "clientId": "5eb04fcd0f3e360008035eb1",
    "documentId": "5ebd40714f23960008c81527",
    "status": "pending",
    "createdAt": "2025-01-04T17:25:21.116Z",
    "updatedAt": "2025-01-04T17:25:21.116Z"
}
```

{% endstep %}

{% step %}

#### Retrieve results

ComplyCube will then run the check. You can retrieve its [outcome and detailed breakdown](https://app.gitbook.com/s/kAhgmUKSf8CFUFVL3GEe/check-types/proof-of-address-check#result-object) via the API, or review the results in the Portal.

If you have [set up webhooks](https://docs.complycube.com/documentation/integration-resources/webhooks), you’ll also receive a notification once the check is complete.

**Example request for retrieving the check outcome**

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

```bash
curl -X GET https://api.complycube.com/v1/checks/5ebd40714f23960008c81527 \
     -H 'Authorization: <YOUR_API_KEY>'
```

{% endtab %}

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

```javascript
const check = await complycube.check.get("5ebd40714f23960008c81527");
```

{% endtab %}

{% tab title="Python" %}

```python
check = cc_api.checks.get('5ebd40714f23960008c81527')
```

{% endtab %}

{% tab title="PHP" %}

```php
$check = $ccapi->checks()->get('5ebd40714f23960008c81527');
```

{% endtab %}

{% tab title=".NET" %}

```csharp
var check = await checkApi.GetAsync("5ebd40714f23960008c81527");
```

{% endtab %}
{% endtabs %}

**Example response**

```json
{
   "id": "65c12a6426d2ab000814037e",
   "entityName": "John Doe",
   "type": "document_check",
   "clientId": "5eb04fcd0f3e360008035eb1",
   "documentId": "5ebd40714f23960008c81527",
   "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"
         },
         "geoLocationAnalysis": {
            "ipInAddressCountry": "clear",
            "ipProximityToAddress": "clear"
         }
      }
   },
   "createdAt": "2025-01-04T17:25:21.116Z",
   "updatedAt": "2025-01-04T17:25:21.116Z"
}
```

{% endstep %}
{% endstepper %}