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/json
Authorization: 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"
}

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/json
Authorization: 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
        }
    }
}

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.
- backImage string: URL to the back side image.
- selfieImage string: 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.
- dateOfBirth object: The birth date of the individual.
- sex object: 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.
- building string: 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

confidencesobject: Various scores and values indicating the confidence in the data's accuracy.

Verification Report

report: Contains results of the verification process.