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

200: OK

{
    "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": "[e-mail]",
            "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"
                ]
            }
        ]
    }
}

404: Not Found

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

400: Bad Request

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
email	String	Email of the Natural Person
externalID	String	Search by external ID

200: OK

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

400: Bad Request Malformed Parameters

401: Unauthorized Unauthorized

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
id	String	The Natural Person Entity ID

200: OK

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

404: Not Found

{
    "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": "[e-mail]",
		"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

200: OK

{
    "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"
    ]
}

400: Bad Request

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

201: Created

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

409: Conflict

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