INVESTOR ONBOARDING API DOCUMENTATION
Overview
In Investor Onboarding the term “Investor” refers to the person who will be onboarded to the investor-onboarding platform. The purpose of this Service is to onboard investors with basic verification of Proof Of Address (POA), Proof Of Identity (POI) , Bank Account verification ,video verification and fatca with signature and contract.
How to use this document
This document should be used as a reference for integrating the Signzy APIs and enabling the onboarding application. The section that is on the right side in the documentation contains the JSON requests and responses. The central column on this page will help you with detailed information about each endpoint.
Authentication
Product API Hostname information
Protocol : https://
Pre-Production Hostname : investor-onboarding-preproduction.signzy.tech
Production Hostname : investor-onboarding.signzy.tech
Authorizing your access
In the APIs you have a username and an API key. The key also acts like your password to the APIs. You need to have an access token for making any further API calls, which you can receive by logging in manually or programmatically using these credentials.
Signzy APIs adhere to authentication defined by Swagger 2.0 specifications. Each call to the APIs should include an ‘Authorization’ header or ‘access_token’ query parameter for authentication.
Logging in
For using Signzy APIs you have to first Login into Signzy System which is a simple Rest API(HTTPS) call with JSON parameters as username and password. Following section mentions the data to be input, expected output and meaning of fields in JSON.
API Endpoint – Customer Login API
Preproduction:
Production:
Supported methods: POST
Request Headers
| Content-type | application/json |
Request Body
| Input Parameter | Description | Example |
| username Required | string | The username provided for Customer Login | signzy |
| password Required | string | The password to the username | ****************** |
API Response
A successful API request generates an HTTP 200 response. The response to a request where output format was specified as json, is a JSON array with response status. To get the authentication token, look at the following response having the parameter “id”. The userId is the Customer ID.
| { “id”: “JGzq4yWXJGF6DouxkijfdkfjKJDFHFkdfjXLgjDQTog3Pulb9peRsCpAdT2i8S”, “ttl”: 1209600, “created”: “2020-03-02T15:21:31.457Z”, “userId”: “5e3b02507ffff394831ad6aaaa” } |
The flow for Investor Onboarding:
Step 1: Create Investor
The Api is used for creating investors for Customer that need to be onboarded. For that we need to have a hostname and protocol which are defined in the Authentication section.
Sending Request:
Supported methods: POST
API Endpoint – Create Investor
Preproduction:
Production:
Request Headers
| Content-type | application/json |
| Authorisation | Access token from login |
Request Body
| Input Parameter | Description | Example |
| name Required | String | Name of the investor whose onboarding needs to be conducted | Abhinav |
| email Required | String | Email id of the investor | xyz@gmail.com |
| phone Required | String(10 digit string and first digit is 6,7,8,9) | Phone/contact number of the investor | 758XXXXX86 |
| username Required | String (unique lowercase, alphanumeric string with special characters ‘.’, ‘-’, ‘_’) | Username of the investor to be provided to them for login | fg3uyevf_orlpf534 |
| redirectURL Optional | String | Merchant will redirect to the redirectURL after the onboarding gets completed or if he/she clicks on the logout button. | https://www.test.com |
| prefillData Optional | Object | Some of the data of investors can be prefilled here like Father’s name, place of birth, gender, marital status, date of birth, address etc. | Pune, F, UNMARRIED |
API Response : A successful API request generates an HTTP 200 response. The response to a request where output format was specified as json, is a JSON array with response status. To get the merchant id which is an unique id attached to each application onboarded use to identify the applications, look at the following response having the parameter “id”. The response also provides four Login URLs as follows:
| { “email”: “…. email ….”,”phone”: “…. phone ….”, “username”: “…. username ….”,”id”: “…. id ….”, “customerId”: “…. customerId ….”,”applicationUrl”: “…. applicationUrl ….”,”autoLoginUrL”: “…. autoLoginUrL ….”, “mobileLoginUrl”: “…. mobileLoginUrl ….”,”mobileAutoLoginUrl”: “…. mobileAutoLoginUrl ….”} |
Step 2 : Initiate Investor Onboarding
The Onboarding can be initiated in two ways, one by sending the investor email along with the credentials and Link. You can also use ” Auto Login Url ” to open an iFrame within your application for the user to onboard without leaving your app.
Once the Investor logs in on the link using the Credentials or uses the Auto Login URL, they are Directed to Signzy Investor Onboarding Platform to perform the KYC journey.
Step 3 : Investor Completes Onboarding
During this step an investor onboards through Signzy’s simple video KYC flow using his/her ID documents(Proof of Identity,Proof of Address, Proof of Correspondence Address), bank account, Personal Information, Video verification, and fatca with signature and contract generation and E-Sign.
At the final stage when the Investors have completed all the steps with relevant documents and information, they will see a Submit Button. Upon clicking Submit Button the verification Engine is called and the application is submitted and the status is changed from Draft to Pending.
Post Submission the Investors will be immediately Redirected to the URL specified/configured for Redirection of the Investor to the Customer’s Application/Website.
Step 4: Getting back the results
You can do this in two ways. One, by using “pullmerchants” API , you can fetch each investor’s onboarding results using merchantId. The second by using the Callback URLs
Data Posted to CallBack URL
After an investor has completed its onboarding, a JSON containing customerId, merchantId and status is posted to the callbackUrl of the customer.
Expected Investor Onboarding Callback Response:
| Property | Accepted values/formats | Description |
| merchantId | String | merchantId(Id for investor) defined for this particular onboarding corresponding to above username |
| customerId | String | customerId is the client ID whose login was used to create the investor |
| status | string | Status of an application(accepted/rejected/pending) |
Fetch details using PullMerchant APIs:
After successful onboard, we can fetch the investor’s details created by customer. We can get the list of investors which are created by customer based on the criteria provided in API request. Keep a time gap of 2-3 minutes before pulling the investor’s data. The below PullMerchant API allows you to pull entire results of investors who have been onboarded.
Sending Requests :
Supported methods: POST
Preproduction: https://investor-onboarding-preproduction.signzy.tech/api/pullmerchants
Production: https://investor-onboarding.signzy.tech/api/pullmerchants
Request Headers
| Content-type | application/json |
| Authorisation | Access token from login |
Request Body
| Input Parameter | Description | Example |
| customerId Required | String | Customer Id of that Customer | 5ebadsefscdsxxxxxxx |
| limitLength Required | Integer | Limit to number of investors that are returned (helpful in pagination) | 100 |
| skipLength Required | Integer | Skip these many investors before generating the list of investors | 15 |
| status Required | String | Status of the application(accepted/rejected/pending/draft) | accepted |
In the response of this API, we will get details of all the investors from 16th onboarding to next 100 onboardings since Inception having status accepted.
The another “pullmerchants” API through which you can fetch each investor’s onboarding results using merchantId is shown below:
Sending Requests :
Supported methods: POST
Preproduction:
Production:
Request Headers
| Content-type | application/json |
| Authorisation | Access token from login |
Request Body
| Input Parameter | Description | Example |
| customerId Required | String | Customer Id of that Customer | 5ebadsefscdsxxxxxxxx |
| merchantId Required | String | Merchant Id of Investor | 5dedfabdacxxxxxxxxxx |
| extraFields Optional | Array | ExtraFields required to be appended in response (Possible values : ‘CAMS’) | Possible value : ‘CAMS’ |
Expected Response
| { “customerId”: “…. customerId ….”, “limitLength”: “…. limitLength ….”, “skipLength”: “…. skipLength ….”, “status”: “…. status ….”, “id”: 1, “result”: [ { “_id”: “…. _id ….”, “email”: “…. email ….”, “phone”: “…. phone ….”, “name”: “…. name ….”, “username”: “…. username ….”, “customerId”: “…. customerId ….”, “merchantId”: “…. merchantId ….”, “status”: “…. status ….”, “reason”: “Your application has been rejected due to undermentioned reasons:”, “rejectionClassification”: [ “..rejectionClassification..” ], “addressType”:”Permanent/Correspondence/Related Person address which will be have value when particular ID card is a address proof”, “verificationData”: { “idCards” :[{ “type”: “..type..”, “purpose”: [ “POI/POA” ], “addressType” : “..addressType..”, “name”: “..name..”, “idNo”: “..idNo..”, “dob”: “..dob..”, “address”: “”, “state”: “”, “issueDate”: “”, “images”: [ “..images…” ], “verificationStatus”: { “verified”: true / false, “message”: “..message..”, “isSet”: 1 }, “faceExtraction”: { “cropped”: “..cropped..” } }], “documents”: [ { “type”: “cheque”, “beneficiaryMobile”: “..beneficiaryMobile..”, “beneficiaryAccount”: “..beneficiaryAccount..”, “beneficiaryName”: “..beneficiaryName..”, “beneficiaryIFSC”: “..beneficiaryIFSC..”, “bankName”: “..bankName..”, “branchName”: “..branchName..”, “images”: “..images..” }, { “type”: “..type..”, “beneficiaryMobile”: “..beneficiaryMobile..”, “beneficiaryAccount”: “..beneficiaryAccount..”, “beneficiaryName”: “..beneficiaryName..”, “beneficiaryIFSC”: “..beneficiaryIFSC..”, “bankName”: “..bankName..”, “branchName”: “..branchName..”, “images”: [], “bankTransferOutput”: { “active”: “no/yes”, “nameMatch”: “no/yes”, “mobileMatch”: “no/yes”, “signzyReferenceId”: “..signzyReferenceId..”, “auditTrail”: { “nature”: “..nature..”, “value”: “..value..”, “timestamp”: “..timestamp..” } }, “verifyAmountOutput”: { “amountMatch”: “true/false”, “owerName”: “..owerName..”, “mobile”: “..mobile..”, “mmid”: “..mmid..” } } ], “video”: { “url”: “..url..”, “matchImage”: “..matchImage..”, “signzyVerifiableString”: “..signzyVerifiableString..”, “videoMatch”: { “matchAudioScore”: “..matchAudioScore..”, }, “matchImageEla”: { “task”: “..task..”, “essentials”: { “url”: “..url..” }, “id”: “..id..”, “patronId”: “..patronId..”, “result”: “..result..”, }, “forensics”: { “staticRisk”: { “staticPhoto”: false / true, “ageGroup”: “..ageGroup..”, }, “videoLandMarks”: { “result”: “..result..”, }, “videoFaceMatch”: { “videoImages”: [“..videoImages..”], “finalMatchImage”: “..finalMatchImage..”, “matchStatistics”: { “coVariance”: “..coVariance..”, “matchPercentage”: “..matchPercentage..” }, }, “exif”: { “message”: “..message..”, “metadataFound”: “true”, “image”: { “make”: “..make..”, “model”: “..model..”, “xResolution”: “”, “yResolution”: “”, “resolutionUnit”: “”, “software”: “”, “modifyDate”: “{..modifyDate..}”, “yCbCrPositioning”: “”, “exifOffset”: “..exifOffset..”, “gpsInfo”: “” }, “gps”: { “gpsAltitudeRef”: “”, “gpsLatitudeRef”: “”, “gpsLatitude”: [], “gpsLongitudeRef”: “”, “gpsLongitude”: [], “gpsAltitude”: “”, “gpsTimeStamp”: [], “gpsProcessingMethod”: “”, “gpsDateStamp”: “” }, “isSet”: 1 } }, “faceLandmarks”: { “result”: “..result..”, “isSet”: 1 } }, “contract”: { “signedContract”: “..signedContract uploaded PDF directURL..” }, “fatca”: { “pep”: “NO/YES”, “rpep”: “NO/YES”, “residentForTaxInIndia”: “NO/YES”, “relatedPerson”: “NO/YES” }, “signature”: { “signatureImageUrl”: “…signatureImageUrl…” }, “formData”: { “gender”: “MALE/FEMALE”, “maritalStatus”: “UNMARRIED/MARRIED”, “nomineeRelationShip”: “FATHER/SPOUSE”, “nomineeTitle”: “..nomineeTitle…”, “maidenTitle”: “Ms./Mrs.”, “maidenName”: “….maidenName….”, “panNumber”: “..panNumber..”, “aadhaarNumber”: “..aadhaarNumber..”, “motherTitle”: “Mrs./Ms.”, “kycAccountCode”: “..kycAccountCode..”, “kycAccountDescription”: “..kycAccountDescription..”, “occupationDescription”: “..occupationDescription..”, “occupationCode”: “..occupationCode..”, “communicationAddressCode”: “..communicationAddressCode..”, “communicationAddressType”: “..communicationAddressType..”, “nomineeName”: “..nomineeName..”, “motherName”: “..motherName..”, “countryCode”: “..countryCode..”, “mobileNumber”: “..mobileNumber..”, “emailId”: “..emailId..”, “pincode”: “..pincode..”, “communicationAddress”: “..communicationAddress..”, “residentialStatus”: “..residentialStatus..”, “citizenshipCountryCode”: “..citizenshipCountryCode..”, “citizenshipCountry”: “..citizenshipCountry..”, “annualIncome”: “… refer Table 1.1”, “placeOfBirth”: “….” }, “info”: { “name”: “..name..”, “dob”: “..dob..”, “emailId”: “..emailId..”, “phone”: “..phone..”, “communicationAddress”: “..communicationAddress..”, “permanentAddress”: “..permanentAddress..” } }, “formFilledData”: { “identityProof”: { “type”: “..type..”, “purpose”: [ “..purpose..” ], “name”: “..name..”, “idNo”: “..idNo..”, “dob”: “..dob..”, “expiryDate”: “”, “verify”: “true/false”, “address”: “”, “state”: “”, “issueDate”: “”, “images”: [ “..images..” ], “proofType”: “..proofType..” }, “addressProof”: [ { “purpose”: [ “..purpose..” ], “name”: “..name..”, “idNo”: “..idNo..”, “dob”: “..dob..”, “verify”: “true/false”, “address”: “..address..”, “expiryDate”: “”, “state”: “”, “issueDate”: “”, “addressType”: “..addressType..”, “proofType”: “..proofType..”, “images”: [ “..images..”, ], “pincode”: “..pincode..”, “type”: “..type..” }, { “purpose”: [ “..purpose..” ], “name”: “..name..”, “idNo”: “..idNo….”, “dob”: “..dob..”, “verify”: “false/true”, “address”: “…address..”, “expiryDate”: “..expiryDate..”, “issueDate”: “.issueDate..”, “addressType”: “.. addressType..”, “proofType”: “.. proofType..”, “images”: [ “..images..” ], “pincode”: “..pincode..”, “type”: “..type..” } ], “bankAccount”: { “type”: “..type..”, “bankName”: “..bankName..”, “branchName”: “..branchName..”, “images”: [ “..images…” ] }, “formFields”: { “gender”: “..gender..”, “maritalStatus”: “..maritalStatus..”, “nomineeRelationShip”: “..nomineeRelationShip..”, “maidenTitle”: “..maidenTitle…”, “maidenName”: “..maidenName..”, “panNumber”: “..panNumber..”, “aadhaarNumber”: “..aadhaarNumber..”, “motherTitle”: “..motherTitle…”, “residentialStatus”: “..residentialStatus..”, “occupationDescription”: “..occupationDescription..”, “occupationCode”: “..occupationCode..”, “kycAccountCode”: “..kycAccountCode..”, “kycAccountDescription”: “..kycAccountDescription..”, “communicationAddressCode”: “..communicationAddressCode..”, “communicationAddressType”: “..communicationAddressType..”, “citizenshipCountryCode”: “..citizenshipCountryCode..”, “citizenshipCountry”: “..citizenshipCountry..”, “applicationStatusCode”: “..applicationStatusCode..”, “applicationStatusDescription”: “..applicationStatusDescription..”, “mobileNumber”: “..mobileNumber..”, “countryCode”: “..countryCode..”, “emailId”: “..emailId..”, “motherName”: “..motherName..”, “permanentAddressCode”: “..permanentAddressCode..”, “permanentAddressType”: “..permanentAddressType..”, “nomineeTitle”: “..nomineeTitle…”, “nomineeName”: “..nomineeName..”, “annualIncome”: “… refer Table 1.1”, “placeOfBirth”: “….” }, “fatca”: { “pep”: “NO/YES”, “rpep”: “NO/YES”, “residentForTaxInIndia”: “NO/YES”, “relatedPerson”: “NO/YES”, “addressType”: “..addressType..”, “countryCodeJurisdictionResidence”: “..countryCodeJurisdictionResidence..”, “countryJurisdictionResidence”: “..countryJurisdictionResidence..”, “taxIdentificationNumber”: “..taxIdentificationNumber..”, “placeOfBirth”: “..placeOfBirth..”, “countryCodeOfBirth”: “..countryCodeOfBirth..”, “countryOfBirth”: “..countryOfBirth..”, “addressCity”: “..addressCity..”, “addressDistrict”: “..addressDistrict..”, “addressStateCode”: “..addressStateCode..”, “addressState”: “..addressState..”, “addressCountryCode”: “..addressCountryCode..”, “addressCountry”: “..addressCountry..”, “addressPincode”: “..addressPincode..”, “address”: “..address..”, “relatedPersonType”: “..relatedPersonType..”, “relatedPersonKycNumber”: “..relatedPersonKycNumber..”, “relatedPersonKycNumberExists”: “..relatedPersonKycNumberExists..”, “relatedPersonIdentityProof”: { “name”: “..name..”, “fatherName”: “..fatherName..”, “dob”: “..dob..”, “number”: “..number..” }, “relatedPersonTitle”: “..relatedPersonTitle…” }, “signature”: { “signatureImageUrl”: “..signatureImageUrl..”, “consent”: “true/false” }, “photo”: { “photoUrl”: “..photoUrl..” }, “video”: { “url”: “..url..”, “matchImage”: “..matchImage..”, “signzyVerifiableString”: “..signzyVerifiableString..”, “seconds”: [ “..seconds…” ] }, “contract”: { “signedContract”: “..signedContract..” } }, “verificationResult”: { “idCards”: [{ “status”: “..status..”, “type”: “..type..”, “purpose”: “..purpose..”, “number”: “..number..” }, { “status”: “Safe/ Risky/ Uncertain”, “type”: “..type..”, “purpose”: “..purpose..”, “number”: “..number..” } ], “overalStatus”: “Safe/ Risky/ Uncertain”, “bankAccount”: “Safe/ Risky/ Uncertain”, “amlStatus”: “Safe/ Risky/ Uncertain” } } ], “merchantCamsJson”: {“…Investors data parsed in CAMS JSON…”}} |