Perform Proof of Address Check

You can run this check immediately via our Demo Postman collection. It's publicly available and doesn't require an account.

Overview of flow

Proof of Address check API flow

1. Create a client

The first step in creating any check is to create a client from your backend server. For this type of check, a client of type person must be created.

Example request for creating a client

cURL

curl -X POST https://api.complycube.com/v1/clients \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
          "type": "person",
          "email": "[e-mail]",
          "personDetails":{
               "firstName": "John",
               "lastName" :"Doe"
          }
        }'

Node.js

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

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

const client = await complycube.client.create({
  type: "person",
  email: "[e-mail]",
  personDetails: {
    firstName: "John",
    lastName: "Doe"
  }
});

Python

from complycube import ComplyCubeClient
cc_api = ComplyCubeClient(api_key='<YOUR_API_KEY>')

new_client = {
    'type':'person',
    'email':'[e-mail]',
    'personDetails': {
        'firstName':'John',
        'lastName':'Doe'
    }
}

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

PHP

use ComplyCube\ComplyCubeClient;

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

$result = $ccapi->clients()->create([
    'type' => 'person',
    'email' => '[e-mail]',
    'personDetails' => [
        'firstName' => 'John',
        'lastName' => 'Doe'
    ]
]);

.NET

using ComplyCube.Net;
using ComplyCube.Net.Resources.Clients;

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

var newClient = new ClientRequest {
  type = "person",
  email = "[e-mail]",
  personDetails = new PersonDetails {
    firstName = "John",
    lastName = "Doe"
  }
}

var client = await clientApi.CreateAsync(newClient);

Example response

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

{
    "id": "5eb04fcd0f3e360008035eb1",
    "type": "person",
    "email": "[e-mail]",
    "personDetails": {
        "firstName": "John",
        "lastName": "Doe"
    },
    "createdAt": "2021-01-04T17:24:29.146Z",
    "updatedAt": "2021-01-04T17:24:29.146Z"
}

2. Create an address

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

Example request for creating an address

cURL

curl -X POST https://api.complycube.com/v1/addresses \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
          "clientId":"5eb04fcd0f3e360008035eb1",
          "line": "Flat 323",
          "city": "Aldgate",
          "state": "London",
          "country": "GB"
        }'

Node.js

const address = await complycube.address.create("5eb04fcd0f3e360008035eb1", {
  line: "Flat 323",
  city: "Aldgate",
  state: "London",
  country: "GB"
});

Python

new_address = {    
    'line': 'Flat 323',
    'city': 'Aldgate',
    'state': 'London',
    'country': 'GB'
}

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

PHP

$address = $ccapi->address()->create(
    '5eb04fcd0f3e360008035eb1',
    [
        'line' => 'Flat 323',
        'city' => 'ManhAldgateattan',
        'state' => 'London',
        'country' => 'GB'
    ]
);

.NET

var addressRequest = new AddressRequest {
  clientId = "5eb04fcd0f3e360008035eb1",
  line = "Flat 323",
  city = "Aldgate",
  state = "London",
  country = "GB"
};

var address = await addressApi.CreateAsync(addressRequest);

Example response

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

{
    "id": "5ebd40714f23960008c81528",
    "clientId":"5eb04fcd0f3e360008035eb1",
    "line": "Flat 323",
    "city": "Aldgate",
    "state": "London",
    "country": "GB",
    "createdAt": "2021-01-04T17:25:21.116Z",
    "updatedAt": "2021-01-04T17:25:21.116Z"
}

3. Create a document

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

Example request for creating a document

cURL

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

Node.js

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

Python

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

PHP

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

.NET

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

var document = await docApi.CreateAsync(docRequest);

Example response

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

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

4. Upload front side image of an ID

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

Images should be JPG, PNG, or PDF.

Below is a sample BASE64encoded file. Download it, and copy its content. Then paste into the data attribute when making the request.

203KB

base64-encoded-bank-statement-sample.txt

Sample - BASE64 encoded bank statement

Example request for uploading an image of a document

cURL

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

Node.js

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

Python

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

PHP

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

.NET

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

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

Example response

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

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

5. Create a check

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

Example request for creating a check

cURL

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

Node.js

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

Python

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

PHP

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

.NET

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

var check = await checkApi.CreateAsync(checkRequest);

Example response

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

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

6. Retrieve outcome

ComplyCube will perform the check. You can retrieve a check's outcome and breakdown via the API.

If you have set up webhooks, a notification is sent upon completion of the check.

Example request for retrieving the check outcome

cURL

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

Node.js

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

Python

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

PHP

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

.NET

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

Example response

{
   "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": "2020-01-04T17:25:21.116Z",
   "updatedAt": "2020-01-04T17:25:21.116Z"
}

Learn more about result outcome and breakdown ➔