Natural Persons

This section describes API operations for managing Natural Person Entity data.

Get Natural Person Information

GetNaturalPersonByEntityID

GET https://api.icomplykyc.com/api/v2/entities/natural-persons/:id

Get personal information, KYC data, AML risk screening data, and document authentication result for a Natural Person with the specified entity ID.

Authentication Type: Api Key

Sample Query: https://api.icomplykyc.com/api/v2/natural-persons/12e34567-fcff-4c10-9dd3-da74422e1c30

Path Parameters

Name

Type

Description

id*

String

The entity ID

{
    "code": 200,
    "status": "success",
    "message": "",
    "data": {
        "kycMetaData": {
            "entityID": "1234567a-6722-4907-8265-7b4e02fab134",
            "createdDateTime": "2020-11-17",
            "lastUpdate": "2020-11-17",
            "nextKYCReview": "2022-11-17",
            "kycStatus": "Approved",
            "externalID": null,
            "tags": []
        },
        "personalInformation": {
            "firstName": "John",
            "middleName": "James",
            "lastName": "Doe",
            "dateOfBirth": "1965-03-11",
            "phone": "6021234567",
            "email": "[email protected]",
            "city": "Phoenix",
            "stateProvince": "AZ",
            "countryCode": "USA",
            "postalCode": "12345",
            "address": "123 Someplace Dr",
            "linkedEntities": [
                {
                    "relationship": "Advisor",
                    "entityID": "1234567a-9d0b-4d5c-ac37-8f4cdc8b5398"
                },
                {
                    "relationship": "CEO",
                    "entityID": "1234567a-b04f-4ae0-b8fe-92fae197cb87"
                }
            ]
        },
        "identityVerification": [
            {
                "id": "1234561c-77a0-4878-996d-95525574de21",
                "identityVerification": true,
                "identityStatus": "Accepted",
                "identityIssues": [],
                "dataSources": null,
                "nextReviewDate": "2022-11-17"
            },
            {
                "id": "1234561c-7c5b-4579-a2bf-494f1ab0c651",
                "identityVerification": true,
                "identityStatus": "Accepted",
                "identityIssues": [],
                "dataSources": null,
                "nextReviewDate": "2022-11-17"
            }
        ],
        "documentAuthentication": [
            {
                "id": "1234561c-aec2-4f33-915a-b2fb51b82007",
                "docAuth": true,
                "docAuthStatus": "Accepted",
                "docIssuerCountry": "United States",
                "docIssuerStateProvince": null,
                "docType": "ID Card",
                "docExpiryDate": "2023-03-11",
                "docNumber": "D12345678",
                "docScanConfidence": 100,
                "dataMatch": true,
                "templateMatch": true,
                "docIssues": []
            },
            {
                "id": "1234561c-f82f-418a-8377-c170d180f4ed",
                "docAuth": true,
                "docAuthStatus": "Accepted",
                "docIssuerCountry": null,
                "docIssuerStateProvince": null,
                "docType": "ID Card",
                "docExpiryDate": "0001-01-01",
                "docNumber": 123456,
                "docScanConfidence": 100,
                "dataMatch": true,
                "templateMatch": false,
                "docIssues": [
                    "The ID verification result failed",
                    "The face match result failed"
                ]
            }
        ],
        "biometrics": [],
        "supportingDocuments": {
            "supportDocs": true,
            "docsPending": [],
            "docsReview": [],
            "docsAccepted": [
                "1234561c-4e43-4ff7-877c-2d5854c17913",
                "1234561c-20e2-4e10-bd2b-9c699bf29cdf"
            ]
        },
        "amlScreening": [
            {
                "id": 1027,
                "ongoing": false,
                "screenDate": "2020-11-17",
                "nextReview": "2022-11-17",
                "searchTerm": "John James Doet",
                "searchTypes": [
                    "person"
                ],
                "searchFuzziness": 60,
                "searchCoverage": [
                    "Adverse Media",
                    "Pep",
                    "Warning",
                    "Fitness Probity"
                ],
                "pending": 0,
                "accepted": 1,
                "unknown": 0,
                "sanctions": 0,
                "politicalExposure": 0,
                "adverseMedia": 1,
                "linkedEntityIds": [
                    "1234561ca-6722-4907-8265-7b4e02fab134"
                ]
            }
        ]
    }
}

{
    "code": 404,
    "status": "failure",
    "message": "there is no natural person entity with given id",
    "data": null
}

GetNaturalPersonEntityIDBySearchParameter

GET https://api.icomplykyc.com/api/v2/entities/natural-persons

Find a natural person record based on query string parameters including first name, last name, phone, email and external ID.

Authentication Type: Api Key

Sample Query: https://api.icomplykyc.com/api/v2/natural-persons?firstName=john&lastName=doe&phone=555-010-0123

Query Parameters

Name

Type

Description

firstName

String

First Name of the Natural Person

lastName

String

Last Name of the Natural Person

phone

String

Phone Number of the Natural Person

String

Email of the Natural Person

externalID

String

Search by external ID

{
    "code": 200,
    "status": "success",
    "message": "",
    "data": [
        "1234567f-3cd2-496a-a3d6-6809f0ed6a03",
        "1234567b-bd37-4acd-8b13-c449f6830f17",
        "12345678-2fb1-452a-860c-59dfbdd61411"
    ]
}

GetAllImagesByEntityID

GET https://api.icomplykyc.com/api/v2/natural-persons/:id/images

Get all ID document images associated with a Natural Person Entity. The endpoint returns a Binary Zip file which contains all the ID document images uploaded by this user.

Authentication Type: Api Key

Sample Query: https://api.icomplykyc.com/api/v2/natural-persons/12e34567-fcff-4c10-9dd3-da74422e1c30/images

Path Parameters

Name

Type

Description

String

The Natural Person Entity ID

Binary Zip archive containing images: 1234567a-6788-4907-8265-7b4e02fab134_images.zip

Sample contents of archive:

1234567890_Preprocessed_Image_driverLicense_1234567-ed49-471c-8342-1dc3a0290589.jpg

31234567890_Preprocessed_BackImage_driverLicense_1234567-34d0-4fdb-a809-195a6049ad2b.jpg

{
    "code": 404,
    "status": "failure",
    "message": "there is no natural person with given id",
    "data": null
}

Add Natural Person

Sample Request Body

To create a natural person, initiate a POST request to https://api.icomplykyc.com/api/v2/entities/natural-persons with the following JSON payload.

{
	"kycMetaData": {
		"kycStatus": "approved",
		"externalID": "JohnDoe555"
	},
	"kycServices": {
		"requestDoc": true,
        "requestIDV": true,
		"requestBio": true,
		"requestAML": true
	},
	"personalInformation": {
		"firstName": "John",
		"middleName": "David",
		"lastName": "Doe",
		"dateOfBirth": "1969-12-31",
		"phone": "555-010-0123",
		"email": "[email protected]",
		"address": "777 Columbia St",
		"city": "New Westminster",
		"stateProvince": "BC",
		"countryCode": "CA",
		"postalCode": "V3M 1B6",
		"linkedEntities":
        [{
            "relationship": "CEO",
            "entityId":"0134b239-b04f-4ae0-b8fe-92fae197cb87"   
        }, {
            "relationship": "Advisor",
            "entityId":"012344ad-9d0b-4d5c-ac37-8f4cdc8b5398"
        }]
	},
	"identityVerification": {
		"identityVerification": true,
		"identityStatus": "pending"
	},
	"documentAuthentication": {
		"docAuthStatus": "accepted",
		"docIssuerCountry": "Canada",
        "docIssuerStateProvince":"BC",
		"docType": "driver's license",
		"docExpiryDate": "2022-09-25",
		"docNumber": "A2131-27701-65925"
	},
	"biometrics": {
		"bioAuthStatus": "rejected",
		"bioAuthType": "selfie upload",
		"faceMatchResult": true,
		"biometricDate": "2020-09-25"
	},
	"amlScreening": {
        "ongoing":false,
        "searchTerm":
        {
            "name":"John Doe",
            "yearOfBirth":1969,
            "countries":["US"]
        },
        "searchType":"person",
        "searchFuzziness":60,
        "searchCoverage":["sanction", "pep", "adverse-media-violent-crime"],
        "linkedEntityIds": ["0134b239-b04f-4ae0-b8fe-92fae197cb87", "1d4284ad-9d0b-4d5c-ac37-8f4cdc8b5398"]
    }
}

AddNaturalPerson

POST https://api.icomplykyc.com/api/v2/entities/natural-persons

Authentication Type: Api Key

Sample Query: https://api.icomplykyc.com/api/v2/entities/natural-persons

Request Body

Name

Type

Description

Raw*

JSON

See above sample payload body

{
    "code": 201,
    "status": "success",
    "message": "natural person entity was successfully created",
    "data": {
        "id": "a5b493fe-8732-44c3-b09d-02682c2d3e0d"
    },
    "errors": [
        "Could not link entity (012344ad-9d0b-4d5c-ac37-8f4cdc8b5398) with organization"
    ]
}

{
    "code": 400,
    "status": "failure",
    "message": "natural person entity could not be created",
    "data": null,
    "errors": [
        "First name is missing",
        "Email is missing"
    ]
}

{
    "code": 201,
    "status": "success",
    "message": "natural person entity was successfully created",
    "data": {
        "id": "1234546-fcff-4c10-9dd3-da74422e1c30"
    },
    "errors": []
}

{
    "code": 409,
    "status": "failure",
    "message": "email is already in use",
    "data": null
}

PreviousEntities NextLegal Entities

Last updated 3 years ago