KYC Global API Guide

The KYC Global 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-global

Sandbox Endpoint

https://api.beta.satschel.com/v2/kyc/idv-global

Method

POST

Request Headers

Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN.

Request Body

Parameter	Type	Description
`firstName`	string	The user's first name
`lastName`	string	The user's last name
`frontImageBase64`	string	Base64 encoded image of the document's front side.
`backImageBase64`	string	Optional: Base64 encoded image of the document's back side.
`selfieImageBase64`	string	Optional: Base64 encoded selfie photo.
`documentType`	string	The type of document being submitted. Supported values: passport, national_identity_card, driving_licence, voter_id, work_permit`.
`fileType`	string	Optional: File type of images. Supported types are `png, jpeg`, `png`, `pdf`and by default is `png`
`callbackUrl`	string	Optional: Callback URL to receive the verification result.
`documentIssuingCountry`	string	The ISO country code of the document issuer.
`aml`	boolean	Optional: Return AML result if aml is true, by default is false

Example Request Body

{
    "firstName": "test firstnbame",
    "lastName": "test lastname",
    "frontImageBase64": "front image base64 string",
    "backImageBase64": "back image base64 string",
    "selfieImageBase64": "selfie image base64 string",
    "documentType": "passport", 
    "documentIssuingCountry": "USA",
    "fileType": "png",
    "aml": false,
    "callbackUrl": "callback url"
}

Selfie photo

If you provide a selfieImageBase64, 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.

Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN.

Get Response

{
    "message": "ok",
    "data": {
        "id": "UniqueID",
        "status": "completed",
        "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",
                "data": "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": ""
            },
            "weight": {
                "value": ""
            },
            "eyeColor": {
                "value": "BLU"
            },
            "matchPercentage": {
                "value": ""
            },
            "simpliciMatchPercentage": {
                "value": ""
            },
            "mrzLine1": {
                "value": ""
            },
            "mrzLine2": {
                "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"
            }
        },
        "report": {
            "status": "completed",
            "similarity": null,
            "liveliness": null,
            "reject": []
        },
        "similarity": null,
        "metadata": {},
        "newAddress": {},
        "aml": null
    }
}

Additionally, the API will trigger a webhook by calling the provided callback URL

Response Attributes

messagestring : A short string indicating the status or result of the request (e.g., "ok" for successful responses).
dataObject : The main data object containing all the detailed information related to the request.

Data Object

idstring : A unique identifier for the dataset or transaction.Unique identifier for the IDV Object.
statusstring : The status of the data or transaction. In this example, it's marked as "completed".

Document Details

documentobject : 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

dataobject : 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.
  - simpliciMatchPercentageobject: Match Percentage ID Image with selfie Photo(Simplici).

Address Information

addressobject : 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.

Verification Report

report: Contains results of the verification process.

Breakdown Report

report: Contains detailed breakdown of the verification process.

KYC Global

On this page