--- title: "External Verification (eKYC)" url: "https://developer.incode.com/api-reference/externalverification-ekyc/" section: "api-reference" group: "eKYC" version: "v1.1" status: "live" endpoint: "POST /omni/externalVerification/ekyc" --- # External Verification (eKYC) `POST /omni/externalVerification/ekyc` Base URL: `https://demo-api.incodesmile.com` — Incode demo environment This endpoint verifies phone, email, address, date of birth and tax numbers, specifically social security number (ssn). When making a request use "kyc" in the plugins array. To have the API return specific risk scores for phone, email, ssn (taxId) and address, see examples below. ## Path & query parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `api-version` | header | string | yes | | ## Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `plugins` | array[string] | | | | `firstName` | string | | The following special characters are not supported: `^±!@£$%&*_+¡€#¢§¶•ªº«<>?\\/:;\|=` | | `surName` | string | | The following special characters are not supported: `^±!@£$%&*_+¡€#¢§¶•ªº«<>?\\/:;\|=` | | `middleName` | string | | The following special characters are not supported: `^±!@£$%&*_+¡€#¢§¶•ªº«<>?\\/:;\|=` | | `maternalSurname` | string | | The following special characters are not supported: `^±!@£$%&*_+¡€#¢§¶•ªº«<>?\\/:;\|=` | | `email` | string | | | | `street` | string | | | | `streetNo` | string | | | | `floor` | string | | | | `apartment` | string | | | | `postalCode` | string | | | | `countryCode` | string | | ISO 3166-1 alpha-2 format | | `phone` | string | | Use E.164 format. Hyphens are optional | | `state` | string | | | | `city` | string | | | | `idNumber` | string | | | | `idNumber1` | string | | | | `gender` | string | | | | `taxId` | string | | | | `dateOfBirth` | string (YYYY-MM-DD) | | | | `dlExpireAt` | string (YYYY-MM-DD) | | | | `fullName` | string | | | | `panNumber` | string | | Indian Permanent Account Number (PAN), format: AAAAANNNNA | | `district` | string | | District or Barangay (neighbourhood), used for Philippines KYC | | `idType` | string | | National ID type. Supported for Philippines KYC: SSS, TIN, GSIS | | `issueDate` | string (YYYY-MM-DD) | | ID document issue date. Required for Colombia Civil Register (CO_CIVIL_REGISTER_1) KYC | ## Responses ### 200 OK Response body (`application/json`): | Field | Type | Required | Description | | --- | --- | --- | --- | | `kyc` | array[EkycVerification] | | | | `kyc.key` | string | | Indicates a type of risk, such as addressRiskLevel. The overallLevel key name is an aggregate risk score for all risk types. It can be used to obtain a single risk score for a whole result set. | | `kyc.status` | string | | Explains the risk level, ie "low", "medium", or "high". When doing a social security number check, the API will return status values of nomatch, fuzzy or exact. Fuzzy means there is plausible match between the name and the social security number, like Dave and David both resolve to the same SSN. | | `kyc.sub_label` | string | | Additional info on the status. | | `kyc.message` | string | | | | `kyc.reasonCodes` | array[string] | | | | `income` | array[EkycVerification] | | | | `income.key` | string | | Indicates a type of risk, such as addressRiskLevel. The overallLevel key name is an aggregate risk score for all risk types. It can be used to obtain a single risk score for a whole result set. | | `income.status` | string | | Explains the risk level, ie "low", "medium", or "high". When doing a social security number check, the API will return status values of nomatch, fuzzy or exact. Fuzzy means there is plausible match between the name and the social security number, like Dave and David both resolve to the same SSN. | | `income.sub_label` | string | | Additional info on the status. | | `income.message` | string | | | | `income.reasonCodes` | array[string] | | | | `additionalVerificationInfo` | AdditionalVerificationInfo | | | | `additionalVerificationInfo.creditFileDetails` | CreditFileDetails | | | | `additionalVerificationInfo.creditFileDetails.creditFileNumber` | string | | | | `additionalVerificationInfo.creditFileDetails.creditFileCreationDate` | string | | | ### 400 Bad Request Response body (`application/json`): | Field | Type | Required | Description | | --- | --- | --- | --- | | `timestamp` | integer (int64) | | UTC timestamp in milliseconds | | `status` | integer (int32) | | Custom error code or HTTP status code | | `error` | string | | HTTP status error | | `message` | string | | Custom error message | | `path` | string | | Endpoint path | | `details` | object | | Custom error details | ## Code samples Generated from this endpoint's method, path, and the conventional Incode headers. The base URL is the Incode demo environment; replace `` with a key for your region. ### cURL ```bash curl -X POST https://demo-api.incodesmile.com/omni/externalVerification/ekyc \ -H "x-api-key: " \ -H "api-version: 1.0" \ -H "Content-Type: application/json" \ -d '{ "plugins": [], "firstName": "", "surName": "", "middleName": "", "maternalSurname": "", "email": "", "street": "", "streetNo": "", "floor": "", "apartment": "", "postalCode": "", "countryCode": "", "phone": "", "state": "", "city": "", "idNumber": "", "idNumber1": "", "gender": "", "taxId": "", "dateOfBirth": "", "dlExpireAt": "", "fullName": "", "panNumber": "", "district": "", "idType": "", "issueDate": "" }' ``` ### Node ```js const res = await fetch("https://demo-api.incodesmile.com/omni/externalVerification/ekyc", { method: "POST", headers: { "x-api-key": "", "api-version": "1.0", "Content-Type": "application/json", }, body: JSON.stringify({ "plugins": [], "firstName": "", "surName": "", "middleName": "", "maternalSurname": "", "email": "", "street": "", "streetNo": "", "floor": "", "apartment": "", "postalCode": "", "countryCode": "", "phone": "", "state": "", "city": "", "idNumber": "", "idNumber1": "", "gender": "", "taxId": "", "dateOfBirth": "", "dlExpireAt": "", "fullName": "", "panNumber": "", "district": "", "idType": "", "issueDate": "" }), }); const data = await res.json(); ``` ### Python ```python import requests headers = { "x-api-key": "", "api-version": "1.0", "Content-Type": "application/json", } res = requests.post("https://demo-api.incodesmile.com/omni/externalVerification/ekyc", headers=headers, json={ "plugins": [], "firstName": "", "surName": "", "middleName": "", "maternalSurname": "", "email": "", "street": "", "streetNo": "", "floor": "", "apartment": "", "postalCode": "", "countryCode": "", "phone": "", "state": "", "city": "", "idNumber": "", "idNumber1": "", "gender": "", "taxId": "", "dateOfBirth": "", "dlExpireAt": "", "fullName": "", "panNumber": "", "district": "", "idType": "", "issueDate": "" }) data = res.json() ``` ### Java ```java HttpRequest req = HttpRequest.newBuilder() .uri(URI.create("https://demo-api.incodesmile.com/omni/externalVerification/ekyc")) .header("x-api-key", "") .header("api-version", "1.0") .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString("{\n \"plugins\": [],\n \"firstName\": \"\",\n \"surName\": \"\",\n \"middleName\": \"\",\n \"maternalSurname\": \"\",\n \"email\": \"\",\n \"street\": \"\",\n \"streetNo\": \"\",\n \"floor\": \"\",\n \"apartment\": \"\",\n \"postalCode\": \"\",\n \"countryCode\": \"\",\n \"phone\": \"\",\n \"state\": \"\",\n \"city\": \"\",\n \"idNumber\": \"\",\n \"idNumber1\": \"\",\n \"gender\": \"\",\n \"taxId\": \"\",\n \"dateOfBirth\": \"\",\n \"dlExpireAt\": \"\",\n \"fullName\": \"\",\n \"panNumber\": \"\",\n \"district\": \"\",\n \"idType\": \"\",\n \"issueDate\": \"\"\n}")) .build(); HttpResponse res = HttpClient.newHttpClient() .send(req, HttpResponse.BodyHandlers.ofString()); ``` ### Example response ```json { "success": true, "status": "OK" } ```