EPAN extraction V2

Introduction:

The EPAN extraction API provided by Signzy Technologies Private Limited allows you to extract the Electronic PAN (EPAN) details of an individual from a valid password-protected PDF or zip file or an XML file. This API endpoint can be integrated with your existing systems to automate the process of EPAN extraction, reducing manual effort and increasing efficiency.

The API accepts a direct URL to the file and the associated password (for PDF and zip files), and returns a JSON response containing the extracted EPAN details, including the name, father's name, date of birth, gender, photo, PAN number, and validity of the PAN. Additionally, the API also returns the X509 data of the digital signature certificate (DSC) associated with the file.

In case the provided link is not a valid document or not in the proper format, the API returns an error message indicating the same.

In the following sections, we will discuss the details of the API endpoint, including the request and response structures, as well as the constraints and limitations to keep in mind while using this API.

Use Cases

This API is especially useful for businesses that require customer verification for KYC (Know Your Customer) purposes. For instance, banks, financial institutions, and telecom companies can use this API to verify the identity of their customers, by extracting the necessary information from their submitted documents.

The EPAN extraction API can also be used in other scenarios where identity verification is required. For example, it can be used in the insurance industry to verify the identity of policyholders, or in the healthcare industry to verify the identity of patients.

Overall, the EPAN extraction API is a powerful tool that can streamline identity verification processes and help businesses comply with regulatory requirements.

API description

API Endpoint's

Identity Object

POST https://preproduction.signzy.tech/api/v2/patrons/<patron-id>/identities

POST https://signzy.tech/api/v2/patrons/<patron-id>/identities

Headers

Key	Value
Authorization	access token (returned as id field of login request)
Content-type	application/json

Request Data

{
    "type": "individualPan",
    "email": "[email protected]",
    "callbackUrl": "https://your-domain.com/your-callback-system",
    "images": []
}

PARAMETERS	DESCRIPTION	TYPE	VALUE (COMPULSORY OR OPTIONAL)
type	Supported type parameter for creation of Identity objects individualPan businessPan aadhaar passport drivingLicence cheque voterid	String	COMPULSORY
email	E-mail can't be empty	String	COMPULSORY
callbackUrl	callbackUrl is where the data is posted on each activity performed on this Identity object.	String	COMPULSORY
images	urls's to be extracted	List	COMPULSORY

Response

{
              "type": "individualPan",
              "email": "[email protected]",
              "callbackUrl": "https://your-domain.com/your-callback-system",
              "images": [
                "<urls-to-uploaded-files>"
              ],
              "autoRecognition": [],
              "verification": [],
              "forgeryCheck": [],
              "accessToken": "..access-token-for-the-snoop-request..",
              "id": "..itemId-for-the-snoop-request....",
              "patronId": "..your-id-into-signzy-system-(userId-returned-from-the-login-call).."
            }

Snoops

POST https://preproduction.signzy.tech/api/v2/snoops

POST https://signzy.tech/api/v2/snoops

Headers

Key	Value
Authorization	access token (returned as id field of login request)
Content-type	application/json

Request Data

{
    "service": "Identity",
    "itemId": "<..itemId-from-the-Identity-Object-request....>",
    "task": "ePan",
    "accessToken": "<..access-token-from-the-Identity-Object-request..>",
    "essentials": {
        "file": "...remote url of the file...",
        "password": "password of the file",
        "type": "type  of pan"
    }
}

Request Body

The request body must be a JSON object with the following properties:

Property	Type	Required	Description
service	string	Yes	The name of the service being used. In this case, it must be "Identity".
itemId	string	Yes	The ID of the item being processed.
accessToken	string	Yes	The access token for the user.
task	string	Yes	The name of the task being performed. In this case, it must be "ePan".
essentials	object	Yes	An object containing the essential information required for the task.

Essentials Object

The essentials object contains the following properties:

Property	Type	Required	Description
file	string	Yes	The URL of the file to be processed. Must be a direct link to a zip, xml or pdf file.
password	string	No	Required only for zip and pdf files. The password to decrypt the file.
type	string	Yes	The type of the file being processed. Must be one of "individualPan", "companyPan", or "partnershipPan".

Input Parameters

Here are the details of the input parameters that can be used in the request body:

Parameter	Required	Type	Description
service	Yes	string	The name of the service being used. In this case, it must be "Identity".
itemId	Yes	string	The ID of the item being processed.
accessToken	Yes	string	The access token for the user.
task	Yes	string	The name of the task being performed. In this case, it must be "ePan".
file	Yes	string	The URL of the file to be processed. Must be a direct link to a zip, xml or pdf file.
password	No	string	Required only for zip and pdf files. The password to decrypt the file.
type	Yes	string	The type of the file being processed. Must be one of "individualPan", "companyPan", or "partnershipPan".

Response

{
    "service": "Identity",
    "itemId": "<Identity-object-id>",
    "task": "autoRecognition",
    "essentials": {},
    "accessToken": "<Identity-access-token>",
    "id": "ID-of-the-snoop-request",
    "response": {
        "files": [
            "<url-to-the-front-side>"
        ],
        "type": "individualPan | businessPan",
        "id": ...integer...,
        "instance": {},
        "result": {
            "name": "..name..",
            "fatherName": "..fatherName..",
            "dob": "..dob..",
            "number": "..pan number.."
        "gender": "..gender..",
            "photo": "..directURL to photo..",
            "timestamp": "",
            "x509Data": {
                "version": 2,
                "subject": {
                    "countryName": "..countryName..",
                    "organizationName": "..organizationName..",
                    "organizationalUnitName": "..organizationalUnitName..",
                    "postalCode": "..postalCode..",
                    "stateOrProvinceName": "..stateOrProvinceName..",
                    "streetAddress": "..streetAddress..",
                    "houseIdentifier": "..houseIdentifier..",
                    "commonName": "..commonName.."
                },
                "issuer": {
                    "countryName": "..countryName..",
                    "organizationName": "..organizationName..",
                    "organizationalUnitName": "..organizationalUnitName..",
                    "commonName": "..commonName.."
                },
                "serial": "..serial..",
                "notBefore": "..notBefore..",
                "notAfter": "..notAfter..",
                "subjectHash": "..subjectHash..",
                "signatureAlgorithm": "..signatureAlgorithm..",
                "fingerPrint": "..fingerPrint..",
                "publicKey": {
                    "algorithm": "..algorithm.."
                },
                "altNames": [],
                "extensions": {
                    "authorityKeyIdentifier": "..authorityKeyIdentifier..",
                    "subjectKeyIdentifier": "..subjectKeyIdentifier..",
                    "basicConstraints": "..basicConstraints..",
                    "keyUsage": "..keyUsage..",
                    "subjectAlternativeName": "..subjectAlternativeName..",
                    "extendedKeyUsage": "..extendedKeyUsage..",
                    "certificatePolicies": "..certificatePolicies..",
                    "authorityInformationAccess": "..authorityInformationAccess..",
                    "cRLDistributionPoints": "..cRLDistributionPoints.."
                }
            },
            "isValidEPANDSC": "..true/false..",
        }
    }
}

Response Parameters:

Property	Example Value	Description
result.name	"John Doe"	Name of the person as mentioned in the PAN card
result.fatherName	"David Doe"	Name of the father/husband of the person as mentioned in the PAN card
result.dob	"01/01/1980"	Date of birth of the person as mentioned in the PAN card
result.number	"ABCDE1234F"	Unique PAN number of the person
result.gender	"Male"	Gender of the person as mentioned in the PAN card
result.photo	""	Direct URL to the photo of the person as mentioned in the PAN card. This is applicable only if the photo is available in the PAN card
result.timestamp	"2023-04-19T14:30:00Z"	The date and time when the API returned the response
result.x509Data		Information regarding the digital signature attached to the PAN card
result.isValidEPANDSC	true/false	Indicates whether the PAN card is valid or not
x509Data.version	2	The version of the digital signature attached to the PAN card
x509Data.subject	{"countryName": "India", "organizationName": "ABC Ltd."}	Details of the subject of the digital signature attached to the PAN card
x509Data.issuer	{"countryName": "India", "organizationName": "XYZ Ltd."}	Details of the issuer of the digital signature attached to the PAN card
x509Data.serial	"1234567890"	The serial number of the digital signature attached to the PAN card
x509Data.notBefore	"01/01/2021"	The date when the digital signature became valid
x509Data.notAfter	"01/01/2026"	The date when the digital signature will expire
x509Data.subjectHash	"5e5b5fb9"	The hash value of the subject of the digital signature attached to the PAN card
x509Data.signatureAlgorithm	"SHA256"	The algorithm used to create the digital signature attached to the PAN card
x509Data.fingerPrint	"1A:2B:3C:4D:5E:6F:7G:8H:9I:1J:2K:3L:4M:5N:6O:7P:8Q:9R:1S:2T"	The fingerprint of the digital signature attached to the PAN card
x509Data.publicKey.algorithm	"RSA"	The algorithm used to create the public key of the digital signature attached to the PAN card
x509Data.altNames	[]	Alternative names for the subject of the digital signature attached to the PAN card
x509Data.extensions	{"authorityKeyIdentifier": "...", "subjectKeyIdentifier": "..."}	Extensions of the digital signature attached to the PAN card.

Status Codes

Status Code	Description
200	OK - The request was successful, and the API returned the requested data.
400	Bad Request - The request was invalid or could not be understood by the server. This can happen if the provided file link is not valid, or if the password provided for a password-protected file is incorrect or missing.
401	Unauthorized - The provided access token is invalid or expired.
404	Not Found - The requested resource was not found.
500	Internal Server Error - An error occurred on the server while processing the request. This could be due to an issue with the API or an issue with the server itself.

Troubleshooting

Issue	Description	Troubleshooting Tips
Missing required input	If a required input is missing, the API will return an error status code.	Check the API documentation to ensure all required inputs have been provided.
Invalid input format	If an input is not in the correct format, the API will return an error status code.	Check the API documentation for the correct input format.
Unsupported input value	If an input value is not supported by the API, it will return an error status code.	Check the API documentation for the supported input values.
Authentication issues	If the authentication credentials are incorrect or missing, the API will return an authentication error status code.	Check the API documentation for the correct authentication credentials.
Network issues	If there are network issues, such as connectivity problems or slow response times, the API may return an error status code or timeout.	Check the network connection and try again.

These are some of the common issues that may occur while providing the required inputs for the API. By following the troubleshooting tips provided, you can resolve these issues and successfully use the API.