DigiLocker API

This document provides a comprehensive analysis of three DigiLocker API responses, categorizing fields as either Always Present or Optional based on the data patterns observed.

1. Aadhaar Data API Response

Always Present Fields

Field Path	Data Type	Description	Example Value
`aadhaar_data.Certificate.CertificateData.KycRes.@code`	String	Unique response code	"abc123def456ghi789jkl012mno345"
`aadhaar_data.Certificate.CertificateData.KycRes.@ret`	String	Response status	"Y"
`aadhaar_data.Certificate.CertificateData.KycRes.@ts`	String	Timestamp	"2025-01-15T10:30:45.123+05:30"
`aadhaar_data.Certificate.CertificateData.KycRes.@ttl`	String	Time to live	"2026-01-15T10:30:45"
`aadhaar_data.Certificate.CertificateData.KycRes.@txn`	String	Transaction ID	"UKC:abc123def456ghi789jkl012mno34520250115103045"
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.@uid`	String	Masked Aadhaar number	"xxxxxxxx1234"
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.Poi.@dob`	String	Date of birth	"15-06-1995"
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.Poi.@gender`	String	Gender	"M"
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.Poi.@name`	String	Full name	"John Doe Smith"
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.Poa.@country`	String	Country	"India"
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.Poa.@dist`	String	District	"Mumbai"
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.Poa.@state`	String	State	"Maharashtra"
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.Poa.@pc`	String	Postal code	"400001"
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.Poa.@vtc`	String	Village/Town/City	"MUMBAI"
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.Poa.@po`	String	Post Office	"Mumbai GPO"
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.Poa.@subdist`	String	Sub District	"Mumbai City"
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.LData.@name`	String	Name in local language	"जॉन डो स्मिथ"
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.LData.@lang`	String	Language code	"13"
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.Pht`	String	Base64 encoded photo	"/9j/4AAQSkZJRgABAgAAAQABAAD..."
`aadhaar_data.Certificate.Signature.@xmlns`	String	XML namespace	"http://www.w3.org/2000/09/xmldsig#"
`aadhaar_data.Certificate.Signature.KeyInfo.X509Data.X509Certificate`	Array	Certificate chain	Array of base64 certificates
`aadhaar_data.Certificate.Signature.KeyInfo.X509Data.X509SubjectName`	Array	Certificate subject names	Array of subject strings
`aadhaar_data.Certificate.Signature.SignatureValue`	String	Digital signature	Base64 encoded signature
`aadhaar_data.Certificate.Signature.SignedInfo.CanonicalizationMethod.@Algorithm`	String	Canonicalization algorithm	"http://www.w3.org/2001/10/xml-exc-c14n#"
`aadhaar_data.Certificate.Signature.SignedInfo.SignatureMethod.@Algorithm`	String	Signature algorithm	"http://www.w3.org/2000/09/xmldsig#rsa-sha1"
`aadhaar_data.Certificate.Signature.SignedInfo.Reference.DigestMethod.@Algorithm`	String	Digest algorithm	"http://www.w3.org/2001/04/xmlenc#sha256"
`aadhaar_data.Certificate.Signature.SignedInfo.Reference.DigestValue`	String	Digest value	"abc123def456ghi789jkl012mno345pqr678stu901vwx234yz567"
`aadhaar_data.Certificate.Signature.SignedInfo.Reference.Transforms.Transform.@Algorithm`	String	Transform algorithm	"http://www.w3.org/2000/09/xmldsig#enveloped-signature"
`aadhaar_xml`	String	XML representation	Full XML string

Optional Fields

Field Path	Data Type	Description	Notes
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.@tkn`	String	Token	Always empty string in samples
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.Poa.@house`	String	House details	Present but varies
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.Poa.@lm`	String	Landmark	Present but varies
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.Poa.@loc`	String	Locality	Present but varies
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.Poa.@street`	String	Street address	Present but varies
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.LData.@country`	String	Country in local language	Always space character
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.LData.@dist`	String	District in local language	"मुंबई"
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.LData.@pc`	String	Postal code in local language	"400001"
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.LData.@state`	String	State in local language	"महाराष्ट्र"
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.LData.@house`	String	House in local language	Present but varies
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.LData.@lm`	String	Landmark in local language	Present but varies
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.LData.@loc`	String	Locality in local language	Present but varies
`aadhaar_data.Certificate.CertificateData.KycRes.UidData.LData.@street`	String	Street in local language	Present but varies
`aadhaar_data.Certificate.Signature.SignedInfo.Reference.@URI`	String	Reference URI	Always empty string

2. Document List API Response

Always Present Fields

Field Path	Data Type	Description	Example Value
`issued_files.items`	Array	Array of issued documents	Array of document objects
`issued_files.items[].date`	String	Document issue date	"15-01-2025"
`issued_files.items[].description`	String	Document description	"Aadhaar Card"
`issued_files.items[].doctype`	String	Document type code	"ADHAR"
`issued_files.items[].issuer`	String	Issuing authority	"Unique Identification Authority of India (UIDAI)"
`issued_files.items[].issuerid`	String	Issuer identifier	"in.gov.uidai"
`issued_files.items[].mime`	Array	Supported MIME types	["application/json", "application/xml", "application/pdf"]
`issued_files.items[].name`	String	Document name	"Aadhaar Card"
`issued_files.items[].type`	String	Document type	"file"
`issued_files.items[].uri`	String	Document URI	"in.gov.uidai-ADHAR-abc123def456ghi789jkl012mno345"

Optional Fields

Field Path	Data Type	Description	Notes
`issued_files.items[].parent`	String	Parent document	Always empty string in samples
`issued_files.items[].size`	String	Document size	Always empty string in samples

3. PAN Verification API Response

Always Present Fields

Field Path	Data Type	Description	Example Value
`document_data.Certificate.@issuedAt`	String	Issued at location	"DigiLocker"
`document_data.Certificate.@language`	String	Language code	"99"
`document_data.Certificate.@name`	String	Document name	"PAN Verification Record"
`document_data.Certificate.@number`	String	PAN number	"ABCDE1234F"
`document_data.Certificate.@status`	String	Document status	"A"
`document_data.Certificate.@type`	String	Document type	"PANCR"
`document_data.Certificate.CertificateData.PAN.@num`	String	PAN number	"ABCDE1234F"
`document_data.Certificate.CertificateData.PAN.@verifiedOn`	String	Verification timestamp	"15-01-2025 12:30:45"
`document_data.Certificate.IssuedBy.Organization.@name`	String	Issuing organization	"Income Tax Department"
`document_data.Certificate.IssuedBy.Organization.@type`	String	Organization type	"CG"
`document_data.Certificate.IssuedBy.Organization.Address.@country`	String	Country code	"IN"
`document_data.Certificate.IssuedTo.Person.@dob`	String	Date of birth	"15-06-1995"
`document_data.Certificate.IssuedTo.Person.@gender`	String	Gender	"MALE"
`document_data.Certificate.IssuedTo.Person.@name`	String	Full name	"JOHN DOE SMITH"
`document_data.Certificate.IssuedTo.Person.@uid`	String	Unique identifier	"abc123def456ghi789jkl012mno345pqr678"
`document_data.Certificate.IssuedTo.Person.Address.@country`	String	Country code	"IN"
`document_data.Certificate.IssuedTo.Person.Address.@type`	String	Address type	"permanent"
`document_data.Certificate.QRMeta`	String	QR code data	Base64 encoded image
`document_data.Certificate.Signature.@xmlns`	String	XML namespace	"http://www.w3.org/2000/09/xmldsig#"
`document_data.Certificate.Signature.KeyInfo.X509Data.X509Certificate`	Array	Certificate chain	Array of base64 certificates
`document_data.Certificate.Signature.KeyInfo.X509Data.X509SubjectName`	Array	Certificate subject names	Array of subject strings
`document_data.Certificate.Signature.SignatureValue`	String	Digital signature	Base64 encoded signature
`document_data.Certificate.Signature.SignedInfo.CanonicalizationMethod.@Algorithm`	String	Canonicalization algorithm	"http://www.w3.org/2001/10/xml-exc-c14n#"
`document_data.Certificate.Signature.SignedInfo.SignatureMethod.@Algorithm`	String	Signature algorithm	"http://www.w3.org/2000/09/xmldsig#rsa-sha1"
`document_data.Certificate.Signature.SignedInfo.Reference.DigestMethod.@Algorithm`	String	Digest algorithm	"http://www.w3.org/2001/04/xmlenc#sha256"
`document_data.Certificate.Signature.SignedInfo.Reference.DigestValue`	String	Digest value	"xyz789abc123def456ghi789jkl012mno345pqr678stu901"
`document_data.Certificate.Signature.SignedInfo.Reference.Transforms.Transform.@Algorithm`	String	Transform algorithm	"http://www.w3.org/2000/09/xmldsig#enveloped-signature"
`document_xml`	String	XML representation	Full XML string

Optional Fields

Field Path	Data Type	Description	Notes
`document_data.Certificate.@issueDate`	String	Issue date	Always empty string in samples
`document_data.Certificate.@validFromDate`	String	Valid from date	Always empty string in samples
`document_data.Certificate.IssuedBy.Organization.@code`	String	Organization code	Always empty string in samples
`document_data.Certificate.IssuedBy.Organization.@tin`	String	TIN number	Always empty string in samples
`document_data.Certificate.IssuedBy.Organization.@uid`	String	Organization UID	Always empty string in samples
`document_data.Certificate.IssuedBy.Organization.Address.@district`	String	District	Always empty string in samples
`document_data.Certificate.IssuedBy.Organization.Address.@house`	String	House	Always empty string in samples
`document_data.Certificate.IssuedBy.Organization.Address.@landmark`	String	Landmark	Always empty string in samples
`document_data.Certificate.IssuedBy.Organization.Address.@line1`	String	Address line 1	Always empty string in samples
`document_data.Certificate.IssuedBy.Organization.Address.@line2`	String	Address line 2	Always empty string in samples
`document_data.Certificate.IssuedBy.Organization.Address.@locality`	String	Locality	Always empty string in samples
`document_data.Certificate.IssuedBy.Organization.Address.@pin`	String	PIN code	Always empty string in samples
`document_data.Certificate.IssuedBy.Organization.Address.@state`	String	State	Always empty string in samples
`document_data.Certificate.IssuedBy.Organization.Address.@type`	String	Address type	Always empty string in samples
`document_data.Certificate.IssuedBy.Organization.Address.@vtc`	String	Village/Town/City	Always empty string in samples
`document_data.Certificate.IssuedTo.Person.@title`	String	Title	Always empty string in samples
`document_data.Certificate.IssuedTo.Person.@swd`	String	SWD	Always empty string in samples
`document_data.Certificate.IssuedTo.Person.@swdIndicator`	String	SWD indicator	Always empty string in samples
`document_data.Certificate.IssuedTo.Person.@maritalStatus`	String	Marital status	Always empty string in samples
`document_data.Certificate.IssuedTo.Person.@religion`	String	Religion	Always empty string in samples
`document_data.Certificate.IssuedTo.Person.@phone`	String	Phone number	Always empty string in samples
`document_data.Certificate.IssuedTo.Person.@email`	String	Email address	Always empty string in samples
`document_data.Certificate.IssuedTo.Person.Address.@district`	String	District	Always empty string in samples
`document_data.Certificate.IssuedTo.Person.Address.@house`	String	House	Always empty string in samples
`document_data.Certificate.IssuedTo.Person.Address.@landmark`	String	Landmark	Always empty string in samples
`document_data.Certificate.IssuedTo.Person.Address.@line1`	String	Address line 1	Always empty string in samples
`document_data.Certificate.IssuedTo.Person.Address.@line2`	String	Address line 2	Always empty string in samples
`document_data.Certificate.IssuedTo.Person.Address.@locality`	String	Locality	Always empty string in samples
`document_data.Certificate.IssuedTo.Person.Address.@pin`	String	PIN code	Always empty string in samples
`document_data.Certificate.IssuedTo.Person.Address.@state`	String	State	Always empty string in samples
`document_data.Certificate.IssuedTo.Person.Address.@vtc`	String	Village/Town/City	Always empty string in samples
`document_data.Certificate.IssuedTo.Person.Photo.@format`	String	Photo format	Always empty string in samples
`document_data.Certificate.Signature.SignedInfo.Reference.@URI`	String	Reference URI	Always empty string

Key Observations

1. Digital Signature Structure

All three APIs maintain consistent digital signature structures with:

X.509 certificate chains
RSA-SHA1 signature algorithm
SHA256 digest algorithm
XML canonicalization

2. Address Field Patterns

Aadhaar API: Address fields are consistently populated
PAN API: Address fields are consistently empty strings
List API: No address information

3. Local Language Support

Aadhaar API: Provides data in both English and local language (Hindi/Marathi)
PAN API: English only
List API: English only

4. Empty String Patterns

Many fields consistently return empty strings rather than being omitted entirely, suggesting these are placeholders for future data or optional fields that are not currently utilized.

5. Data Consistency

All APIs maintain consistent structure across different users
Certificate chains and signature algorithms are standardized
MIME type arrays are consistent across document types

6. Additional Fields in Viren's Response

New Address Fields: @po (Post Office) and @subdist (Sub District) were found in Viren's data
Enhanced Local Language Support: Viren's response includes additional local language fields like @dist, @pc, and @state in the LData section
Field Variation: Some users may have more complete address information than others, suggesting data completeness varies by region or data source

Recommendations for API Consumers

Always check for empty strings rather than missing fields
Validate digital signatures using the provided certificate chains
Handle both English and local language data for Aadhaar responses
Use the @ret field to verify successful responses
Parse XML data when available for additional metadata
Implement proper error handling for missing or malformed data

DigiLocker API

On this page