KYC - AML
KYC - IDV Reports API Guide
The IDV and AML API serves the critical purpose of streamlining identity verification and anti-money laundering checks. By integrating this API, businesses can swiftly confirm customer identities while simultaneously safeguarding against financial crimes. It offers a robust solution for compliance, fraud prevention, and maintaining the integrity of financial transactions.
Before making requests to the KYC Reports API, you need to generate an access token. Follow the guide provided in the Getting Started section of our documentation to generate an access token.
Endpoint
https://api.satschel.com/v2/kyc/idv
Method
POST
Request Headers
Content-Type: application/jsonAuthorization: Bearer YOUR_ACCESS_TOKEN.
Request Body
| Parameter | Type | Description |
|---|---|---|
frontImage | string | Base64 encoded image of the document's front side. Supported types are image/png, image/jpeg |
backImage | string | Base64 encoded image of the document's back side. Supported types are image/png, image/jpeg |
selfieImage | string | Optional: Base64 encoded selfie photo. Supported types are image/png, image/jpeg |
callbackUrl | string | Optional: Callback URL for webhook notifications. |
aml | boolean | Optional: Return AML result if aml is true, by default its false |
Example Request Body
{
"frontImage": "base64EncodedFrontImage",
"backImage": "base64EncodedBackImage",
"callback": "https://example.com/webhook",
"aml": true
}
Selfie photo
If you provide a selfieImage, IDV can compare a photo of a user's ID document with a selfie photo.
Direct Response
If you do not provide a callback in the request body, the KYC report data will be returned directly in the response.
{
"message": "ok",
"data": {
"_id": "uniqueId123",
"status": "completed",
"createdAt": "2023-XX-XXTXX:XX:XX.XXXZ",
"updatedAt": "2023-XX-XXTXX:XX:XX.XXXZ",
"result": {
"document": {
"frontImage": "linkToFrontImage",
"backImage": "linkToBackImage",
"selfieImage": "linkToSelfieImage"
},
"data": {
"firstName": {"value": "FIRSTNAME", "verified": true},
"middleName": {"value": "MIDDLENAME", "verified": true},
"lastName": {"value": "LASTNAME", "verified": true},
"dateOfBirth": {"value": "DOB", "verified": true},
//... other data fields ...
},
//... other result fields ...
}
}
}
Callback Response
If you provide a callback URL, the API will respond with a message and a unique report ID. This report ID can be used to retrieve the KYC report later. This can be set as callback in the Request body API endpoint.
{
"message": "ok",
"data": {
"_id": "c9895dc8-5bc3-41b2-85df-ab4345cd4289"
}
}
To retrieve the full report for kyc and aml make a GET request to the below endpoint. Pass the _id that is obtained from post call.
Endpoint
https://api.satschel.com/v2/kyc/idv/:_id
Method
GET
Request Headers
Content-Type: application/jsonAuthorization: Bearer YOUR_ACCESS_TOKEN.
Get Response
{
"message": "ok",
"data": {
"_id": "UniqueID",
"status": "completed",
"createdAt": "2023-10-09T11:52:42.293Z",
"updatedAt": "2023-10-09T11:53:01.100Z",
"result": {
"document": {
"frontImage": "url",
"backImage": "url",,
"selfieImage": "url",
},
"data": {
"firstName": {
"value": "firstName",
"verified": true
},
"middleName": {
"value": "middleName",
"verified": true
},
"lastName": {
"value": "lastName",
"verified": true
},
"dateOfBirth": {
"value": "1982-11-16",
"verified": true
},
"sex": {
"value": "male"
},
"documentNumber": {
"value": "documentNumber",
"verified": true
},
"dateOfExpiry": {
"value": "2030-11-16",
"verified": true
},
"dateOfIssue": {
"value": "2022-06-07",
"verified": true
},
"age": {
"value": 40
},
"issuingState": {
"value": "State",
"verified": false
},
"nationality": {
"value": "US",
"verified": false
},
"idType": {
"value": "drivers-license",
"verified": true
},
"phone": {
"value": "",
"verified": false
},
"height": {
"value": "6-00 \""
},
"weight": {
"value": ""
},
"eyeColor": {
"value": "BLU"
},
"matchPercentage": {
"value": ""
},
"conclusion": []
},
"address": {
"builiding": {
"value": "APT builiding 989",
"verified": true
},
"address": {
"value": "323Address Street",
"verified": true
},
"city": {
"value": "Houston",
"verified": true
},
"state": {
"value": "state",
"verified": true
},
"zip": {
"value": "zip",
"verified": true
},
"country": {
"value": "USA",
"verified": true
},
"fullAddress": {
"value": "Full Address"
}
},
"confidences": {
"id": 0.9771,
"selfie": null,
"faceMatch": null,
"nameMatch": null,
"selfieSunglasses": 0,
"selfieEyeglasses": 0,
"idMatch": null,
"birthDateMatch": null,
"idQuality": 0.9127,
"idGlareQuality": 1,
"idExpired": 1,
"idCrosscheckDarkweb": null,
"idCrosscheckActivity": null,
"idCrosscheckIdentity": null,
"idAml": null,
"idFraud": null,
"barcode": null,
"barcodeMatch": null
},
"report": {
"status": "",
"similarity": null,
"liveliness": null,
"reject": []
},
"verificationDetail": {
"frontImage": true,
"backImage": true,
"selfieImage": false
},
"ssn": {
"ssnNumber": "",
"verified": false,
"deceased": false
},
"status": "completed",
"similarity": null,
"aml": {
"EDD": {
"riskScore": "70%",
"entity": {
"version": "20230307082704",
"name": "ENTITY",
"listId": "9898",
"listCode": "EUL",
"entityType": "03",
"createdDate": "03/18/2019",
"lastUpdateDate": "03/07/2023",
"source": "EUL",
"OriginalSource": "Enforcement",
"dobs": {
"dob": {
"Y": "1980",
"$t": "01/30/1980"
}
},
"pobs": {
"pob": "KKK, , XYZ"
},
"aliases": {
"alias": [
{
"type": "Alias",
"$t": "XYZ, AB"
},
{
"type": "Alias",
"$t": "XYZ, AB"
}
]
},
"nativeCharNames": {
"nativeCharName": [
{
"charSet": "",
"latinCharName": "XYZ",
"type": "Primary",
"$t": "Руж"
},
{
"charSet": "",
"latinCharName": "XYZ",
"type": "Primary",
"$t": "إاوا..."
}
]
},
"ids": {
"id": {
"type": "Passport",
"$t": "YIUYXYZ"
}
},
"titles": {
"title": ""
},
"sdfs": {
"sdf": [
{
"name": "OtherInformation",
"$t": "NickName: .."
},
{
"name": "DirectID",
"$t": "https://abc"
},
{
"name": "EntityLevel",
"$t": "N/A"
},
{
"name": "Gender",
"$t": "FEMALE"
},
{
"name": "NameSource",
"$t": "US-JJJY"
},
{
"name": "Org_PID",
"$t": "878"
},
{
"name": "OriginalID",
"$t": "787878"
},
{
"name": "Relationship",
"$t": "Associate"
},
{
"name": "SubCategory",
"$t": "Money Laundering"
}
]
},
"addresses": {
"address": [
{
"city": "JJJ",
"country": "BG",
"countryName": "BULGARIA"
},
{
"address1": "ABC ROAD",
"city": "LONDON",
"country": "GB",
"countryName": "UNITED KINGDOM"
},
{
"address1": "72 e ROAD",
"city": "LLANDUDNO",
"country": "GB",
"countryName": "UNITED KINGDOM",
"postalCode": "LL30 2DZ"
},
{
"country": "GB",
"countryName": "UNITED KINGDOM"
},
{
"city": "PLEVEN",
"country": "BG",
"countryName": "BULGARIA"
},
{
"city": "SCHRAMBERG",
"country": "DE",
"countryName": "GERMANY"
},
{
"city": "DUBAI",
"country": "AE",
"countryName": "UNITED ARAB EMIRATES"
}
]
}
},
"disposition": {
"auditList": [
{
"date": "10/09/2023 07:52:59",
"entityId": "10189345248",
"entityVersion": "343",
"status": "Passed by Rules",
"riskScore": "70%",
"userId": "",
"note": "Automatically Generated (Rule ID - 1)"
}
]
}
},
"GWL": {
"riskScore": "100%",
"entity": {
"version": "232343",
"name": "XYZ",
"listId": "7",
"listCode": "FB",
"entityType": "03",
"createdDate": "07/01/2022",
"lastUpdateDate": "07/01/2022",
"source": "FBI",
"OriginalSource": "XYZ",
"dobs": {
"dob": {
"D": "30",
"M": "01",
"Y": "1990",
"$t": "01/30/1990"
}
},
"pobs": {
"pob": "Bulgaria"
},
"aliases": {
"alias": [
{
"type": "Alias",
"$t": "'XXXXXXXXX'"
},
{
"type": "Alias",
"$t": "XXXXXXXXXX"
},
{
"type": "Alias",
"$t": "XXXXXXXXXXX"
},
{
"type": "Alias",
"$t": "XXXXXXXXXXXX"
}
]
},
"sdfs": {
"sdf": [
{
"name": "Gender",
"$t": "XXXX"
},
{
"name": "LanguagesSpoken",
"$t": "Bulgarian"
},
{
"name": "LanguagesSpoken",
"$t": "English"
},
{
"name": "LanguagesSpoken",
"$t": "German"
},
{
"name": "OtherInformation",
"$t": "XYZ."
}
]
},
"otherIds": {
"childId": [
"453",
"6478434906",
"647845907",
"435"
]
}
},
"disposition": {
"auditList": [
{
"date": "10/09/2023 07:52:59",
"entityId": "4543",
"entityVersion": "3454534",
"status": "Open",
"riskScore": "100%",
"userId": "",
"note": "Automatically Generated"
}
]
}
}
}
}
}
}
Additionally, the API will trigger a webhook by calling the provided callback URL
Response Attributes
- message
string: A short string indicating the status or result of the request (e.g., "ok" for successful responses). - data
Object: The main data object containing all the detailed information related to the request.
Data Object
- id
string: A unique identifier for the dataset or transaction.Unique identifier for the IDV Object. - status
string: The status of the data or transaction. In this example, it's marked as "completed". - createdAt
string: The timestamp indicating when this data entry was created. - updatedAt
string: The timestamp showing the last time this data entry was updated. - result
object: A comprehensive object that carries detailed results.
Document Details
- document
object: Contains links to various images related to the verification process.
- frontImagestring: URL to the front side image.
- backImagestring: URL to the back side image.
- selfieImagestring: URL to the selfie image for verification.
Personal Information
- data
object: Houses personal details and attributes.
- firstNameobject, middleNameobject, lastNameobject: Objects for the respective name parts containing the value and a boolean to indicate if it's verified.
- dateOfBirthobject: The birth date of the individual.
- sexobject: Gender of the individual.
- documentNumberobject: The number of the document used for verification.
- ageobject: Age of the individual.
- issuingStateobject: ID document issuing State.
- nationalityobject: Nationality of the individual.
- idTypeobject: ID document Type .
- heightobject: height of the individual.
- weightobject: weight of the individual.
- eyeColorobject: Eye colour of the individual.
- matchPercentageobject: Match Percentage ID Image with selfie Photo.
Address Information
- address
object: Contains address details.
- buildingstring: Name or number of the building.
- addressstring: The main address line.
- citystring, statestring, zipstring, countrystring: Components of the address.
- fullAddressstring: A combined string of the full address.
Confidence Scores
- confidences
object: Various scores and values indicating the confidence in the data's accuracy.
Verification Report
- report: Contains results of the verification process.
Anti-Money Laundering (AML) Data
- aml
object: Information related to anti-money laundering checks.
- EDDobjectand GWLobject: Different sections of AML data. They include risk scores, entity details, and a disposition object which contains an audit list with details like date, entityId, and more. - EDD
object:
- riskScorestring: The risk score associated with the entity. In this case, it's 70%.
- entityobject: Contains the details of the entity.
- entityobject: Contains the details of the entity.
- entityobject: Contains the details of the entity.
- versionobject: The version ID of the entity's details.
- nameobject: Name of the entity.
- listId & listCodeobject: These likely represent identifiers for a specific list or database in which the entity is found.
- entityTypeobject: The type of entity, represented here by the code "03".
- createdDate & lastUpdateDateobject: The dates when the entity was created and last updated, respectively.
- source & OriginalSourceobject: Sources from which the entity's information has been derived.
- dobsobject: Date of birth of the entity.
- pobsobject: Place of birth of the entity.
- aliasesobject: A list of other names or pseudonyms associated with the entity.
- nativeCharNamesobject: Names in native characters.
- idsobject: Identifying documents, like a passport.
- titlesobject: Any titles associated with the entity.
- sdfsobject: Other miscellaneous details like gender, nickname, etc.
- addressesobject: Addresses associated with the entity.
- dispositionobject: Describes how the entity has been treated or assessed.
- auditListobject: A list detailing audits or checks that have been made on the entity. - GWL
object:
- riskScoreobject: The risk score associated with this entity, in this case, 100%.
- entityobject: Contains the details of the entity, similar to the "EDD" structure but with some differences.
- versionobject: Version ID of the entity's details.
- nameobject: Name of the entity.
- listId & listCodeobject: Identifiers for the specific list or database.
- entityTypeobject: Type of entity.
- createdDate & lastUpdateDateobject: Creation and last update dates.
- source & OriginalSourceobject: Data sources.
- dobsobject: Date of birth.
- pobsobject: Place of birth.
- aliasesobject: List of aliases.
- sdfsobject: Miscellaneous details about the entity.
- otherIdsobject: Other identifying numbers.
- dispositionobject: Details about the treatment or assessment of the entity.
- auditListobject: List detailing audits/checks on the entity.
Updated over 1 year ago