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

# Natural Persons

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

### Get Natural Person Information

## GetNaturalPersonByEntityID

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | String | The entity ID |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "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": "jdoe@outlook.com",
            "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"
                ]
            }
        ]
    }
}
```

{% endtab %}

{% tab title="404: Not Found " %}

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

{% endtab %}

{% tab title="400: Bad Request " %}

{% endtab %}
{% endtabs %}

## GetNaturalPersonEntityIDBySearchParameter

<mark style="color:blue;">`GET`</mark> `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              |

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}

{% tab title="400: Bad Request Malformed Parameters" %}

{% endtab %}

{% tab title="401: Unauthorized Unauthorized" %}

{% endtab %}
{% endtabs %}

## GetAllImagesByEntityID

<mark style="color:blue;">`GET`</mark> `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 |

{% tabs %}
{% tab title="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

{% endtab %}

{% tab title="404: Not Found " %}

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

{% endtab %}
{% endtabs %}

### 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.

```json
{
	"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": "johndoe22@gmail.com",
		"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

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark> | JSON | See above sample payload body |

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}

{% tab title="400: Bad Request " %}

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

{% endtab %}

{% tab title="201: Created " %}

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

{% endtab %}

{% tab title="409: Conflict " %}

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

{% endtab %}
{% endtabs %}