{ "openapi": "3.0.0", "info": { "title": "kyc-internal", "version": "1.0.0" }, "servers": [ { "url": "https://test-api.sandbox.co.in", "description": "test" }, { "url": "https://api.sandbox.co.in", "description": "prod" } ], "security": [], "components": {}, "paths": { "/kyc/pan/search": { "post": { "summary": "Search PAN", "operationId": "searchPAN", "tags": [ "PAN" ], "parameters": [ { "name": "Authorization", "in": "header", "description": "JWT access token", "required": true, "example": "{{access_token}}", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for identification", "required": true, "example": "{{api_key}}", "schema": { "type": "string" } }, { "name": "x-api-version", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "x-accept-cache", "in": "header", "required": false, "description": "Pass true to accept the cached response. If the header is not passed, or if false is sent as the value, the request will hit the origin.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "@entity", "pan", "consent", "reason" ], "properties": { "@entity": { "type": "string", "enum": [ "in.co.sandbox.kyc.pan_search.request" ], "description": "Entity type identifier for the PAN search request." }, "pan": { "type": "string", "description": "10-character Permanent Account Number to look up. Must follow the standard PAN format: five letters, four digits, one letter.", "pattern": "^[A-Z]{5}[0-9]{4}[A-Z]{1}$", "minLength": 10, "maxLength": 10 }, "consent": { "type": "string", "enum": [ "Y", "y" ], "description": "Explicit consent from the end user to look up their PAN details. Must be passed as \"Y\" or \"y\" to proceed." }, "reason": { "type": "string", "description": "Purpose for initiating the PAN search, such as identity verification or KYC compliance. Used for audit and compliance traceability.", "minLength": 1 } } }, "example": { "@entity": "in.co.sandbox.kyc.pan_search.request", "pan": "XXXPX1234A", "consent": "y", "reason": "For KYC" } } } }, "responses": { "200": { "description": "200 - OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "timestamp", "transaction_id", "data" ], "properties": { "code": { "type": "integer", "description": "HTTP status code of the response." }, "timestamp": { "type": "integer", "description": "Unix timestamp in milliseconds indicating when the response was generated." }, "transaction_id": { "type": "string", "format": "uuid", "description": "Unique identifier for this API transaction, used for support and traceability." }, "data": { "type": "object", "required": [ "@entity", "pan", "status", "category" ], "properties": { "@entity": { "type": "string", "enum": [ "in.co.sandbox.kyc.pan_search.response" ], "description": "Entity type identifier for the PAN search response." }, "status": { "type": "string", "enum": [ "valid", "invalid" ], "description": "Validity status of the PAN as reported by the income tax authority." }, "message": { "type": "string", "nullable": true, "description": "Additional context about the result, typically present when status is invalid." }, "pan": { "type": "string", "description": "The queried PAN.", "pattern": "^[A-Z]{5}[0-9]{4}[A-Z]{1}$", "minLength": 10, "maxLength": 10 }, "full_name": { "type": "string", "nullable": true, "description": "Full name of the PAN holder as registered with the income tax authority." }, "name_pan_card": { "type": "string", "nullable": true, "description": "Name as printed on the PAN card. May differ from full_name, which reflects the income tax database record." }, "category": { "type": "string", "enum": [ "Individual", "Company", "Firm", "HUF", "Trust", "Government", "Body of Individuals", "Association of Persons", "Local Authority", "Artificial Judicial Person", "Pan not Available" ], "description": "Category of the PAN holder, derived from the fourth character of the PAN." }, "gender": { "type": "string", "nullable": true, "description": "Gender of the PAN holder. Returns null for non-individual categories such as companies and firms." }, "date_of_birth": { "type": "string", "nullable": true, "description": "Date of birth of an individual, or date of incorporation for a company or firm. Format: DD-MM-YYYY." }, "masked_aadhaar_number": { "type": "string", "nullable": true, "description": "Aadhaar number with the first eight digits masked, shown only when Aadhaar is linked to the PAN. Returns null for non-individual categories." }, "email": { "type": "string", "format": "email", "nullable": true, "description": "Email address registered with the PAN." }, "mobile_number": { "type": "string", "nullable": true, "description": "Mobile number registered with the PAN." }, "first_name": { "type": "string", "nullable": true, "description": "First name of the PAN holder. For non-individual categories, this field contains the full registered name." }, "middle_name": { "type": "string", "nullable": true, "description": "Middle name of the PAN holder. Returns null when not available or for non-individual categories." }, "last_name": { "type": "string", "nullable": true, "description": "Last name of the PAN holder. Returns null for non-individual categories." }, "aadhaar_seeding_status": { "type": "string", "enum": [ "y", "n", "na" ], "description": "Indicates whether the PAN is linked to an Aadhaar number. \"y\" means linked, \"n\" means not linked, \"na\" means not applicable for non-individual categories." }, "address": { "type": "object", "nullable": true, "description": "Address of the PAN holder as registered with the income tax authority.", "properties": { "@entity": { "type": "string", "enum": [ "in.co.sandbox.kyc.pan_search.address" ], "description": "Entity type identifier for the address object." }, "full_address": { "type": "string", "nullable": true, "description": "Complete address as a single formatted string." }, "street": { "type": "string", "nullable": true, "description": "Street or locality component of the address." }, "city": { "type": "string", "nullable": true, "description": "City component of the address." }, "state": { "type": "string", "nullable": true, "description": "State component of the address." }, "pincode": { "type": "integer", "nullable": true, "description": "6-digit postal code." }, "country": { "type": "string", "nullable": true, "description": "Country component of the address." } } } } } } }, "examples": { "successful response for individual": { "summary": "Successful response for individual", "value": { "code": 200, "timestamp": 1763727760000, "transaction_id": "88ca194e-7853-4951-a239-26bb5b1fee67", "data": { "@entity": "in.co.sandbox.kyc.pan_search.response", "status": "valid", "pan": "XXXPX1234A", "full_name": "AARAV SHARMA", "category": "Individual", "gender": "male", "date_of_birth": "21-04-1985", "masked_aadhaar_number": "XXXXXXXXX012", "email": "johndoe@email.com", "mobile_number": "999999999", "first_name": "JOHN", "middle_name": "RONALD", "last_name": "DOE", "aadhaar_seeding_status": "y", "address": { "@entity": "in.co.sandbox.kyc.pan_search.address", "full_address": "Mangal Kanaka Niwas, Main Cross 3rd, Bengaluru, Bengaluru-Karnataka, India", "street": "Main Cross 3rd", "city": "Bengaluru", "state": "Karnataka", "pincode": 581615, "country": "India" } } } }, "successful response for company": { "summary": "Successful response for company", "value": { "code": 200, "timestamp": 1717082916254, "transaction_id": "0ef44ca0-ca3d-4a8d-8936-fb92ad63cedf", "data": { "@entity": "in.co.sandbox.kyc.pan_search.response", "status": "valid", "pan": "XXXCX1234A", "full_name": "JOHN DOE TECHNOLOGIES PRIVATE LIMITED", "category": "Company", "gender": null, "date_of_birth": "02-10-2008", "masked_aadhaar_number": null, "email": "company@email.com", "mobile_number": "111111111", "aadhaar_seeding_status": "na", "first_name": "JOHN DOE TECHNOLOGIES PRIVATE LIMITED", "last_name": null, "middle_name": null, "address": { "@entity": "in.co.sandbox.kyc.pan_search.address", "full_address": "Quarter - A, Block - B Sample Area, ABC Street MUMBAI MAHARASTRA INDIA 700011", "street": "ABC Street", "city": "MUMBAI", "state": "MAHARASTRA", "pincode": 700011, "country": "India" } } } }, "invalid pan": { "summary": "Invalid PAN", "value": { "code": 200, "timestamp": 1763727760000, "transaction_id": "c0e6f784-c0ec-4375-8b60-017d7570f59c", "data": { "@entity": "in.co.sandbox.kyc.pan_search.response", "pan": "XXXFX1234J", "category": "Firm", "status": "invalid" } } } } } } }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "timestamp", "transaction_id", "message" ], "properties": { "code": { "type": "integer", "description": "HTTP status code of the response." }, "timestamp": { "type": "integer", "description": "Unix timestamp in milliseconds indicating when the response was generated." }, "transaction_id": { "type": "string", "format": "uuid", "description": "Unique identifier for this API transaction, used for support and traceability." }, "message": { "type": "string", "description": "Human-readable description of the validation error." } } }, "examples": { "invalid pan pattern": { "summary": "Invalid PAN pattern", "value": { "code": 422, "timestamp": 1763727760000, "transaction_id": "65a16945-6293-47d9-931d-6e790fab226f", "message": "Invalid Pan pattern" } }, "consent required": { "summary": "Consent required", "value": { "code": 422, "timestamp": 1718020448513, "transaction_id": "222fd34c-e55d-4b5a-9791-49887b23d2b8", "message": "invalid parameter: Consent is required." } }, "reason cannot be empty": { "summary": "Reason cannot be empty", "value": { "code": 422, "timestamp": 1718020660106, "transaction_id": "2a81a954-9242-4e48-9bb2-23eb234b1edf", "message": "Reason cannot be empty" } } } } } } } } }, "/kyc/pan/search/lite": { "post": { "summary": "Search PAN Lite", "operationId": "searchPANLite", "tags": [ "PAN" ], "parameters": [ { "name": "Authorization", "in": "header", "description": "JWT access token", "required": true, "example": "{{access_token}}", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for identification", "required": true, "example": "{{api_key}}", "schema": { "type": "string" } }, { "name": "x-api-version", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "x-accept-cache", "in": "header", "required": false, "description": "Pass true to accept the cached response. If the header is not passed, or if false is sent as the value, the request will hit the origin.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "@entity", "pan", "consent", "reason" ], "properties": { "@entity": { "type": "string", "enum": [ "in.co.sandbox.kyc.pan_search_lite.request" ], "description": "Entity type identifier for the PAN search Lite request." }, "pan": { "type": "string", "description": "10-character Permanent Account Number to look up. Must follow the standard PAN format: five letters, four digits, one letter.", "pattern": "^[A-Z]{3}[ABCFGHJLPT][A-Z][0-9]{4}[A-Z]$", "minLength": 10, "maxLength": 10 }, "consent": { "type": "string", "enum": [ "Y", "y" ], "description": "Explicit consent from the end user to look up their PAN details. Must be passed as \"Y\" or \"y\" to proceed." }, "reason": { "type": "string", "description": "Purpose for initiating the PAN search, such as identity verification or KYC compliance. Used for audit and compliance traceability.", "minLength": 1 } } }, "example": { "@entity": "in.co.sandbox.kyc.pan_search_lite.request", "pan": "XXXPX1234A", "consent": "y", "reason": "for KYC" } } } }, "responses": { "200": { "description": "200 - OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "timestamp", "transaction_id" ], "properties": { "code": { "type": "integer", "description": "HTTP status code of the response." }, "timestamp": { "type": "integer", "description": "Unix timestamp in milliseconds indicating when the response was generated." }, "transaction_id": { "type": "string", "format": "uuid", "description": "Unique identifier for this API transaction, used for support and traceability." }, "data": { "type": "object", "properties": { "@entity": { "type": "string", "enum": [ "in.co.sandbox.kyc.pan_search_lite.response" ], "description": "Entity type identifier for the PAN search Lite response." }, "pan": { "type": "string", "description": "The queried PAN.", "pattern": "^[A-Z]{3}[ABCFGHJLPT][A-Z][0-9]{4}[A-Z]$", "minLength": 10, "maxLength": 10 }, "full_name": { "type": "string", "nullable": true, "description": "Full name of the PAN holder as registered with the income tax authority." }, "status": { "type": "string", "enum": [ "valid", "invalid" ], "description": "Validity status of the PAN as reported by the income tax authority." }, "category": { "type": "string", "description": "Category of the PAN holder, derived from the fourth character of the PAN." } } } } }, "examples": { "successful response": { "summary": "Successful response", "value": { "code": 200, "timestamp": 1688557921287, "transaction_id": "ec2c8ac5-79d4-4ef2-a022-95da12d7d6c5", "data": { "@entity": "in.co.sandbox.kyc.pan_search_lite.response", "pan": "XXXPX1234A", "full_name": "JOHN RONALD DOE", "status": "valid", "category": "Individual" } } }, "invalid pan": { "summary": "Invalid PAN", "value": { "code": 200, "timestamp": 1782394507406, "transaction_id": "7da536df-84af-4842-9ad9-cfbff484275a", "data": { "@entity": "in.co.sandbox.kyc.pan_search_lite.response", "pan": "IHPPM6269F", "status": "invalid", "category": "individual" } } } } } } }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "timestamp", "transaction_id", "message" ], "properties": { "code": { "type": "integer", "description": "HTTP status code of the response." }, "timestamp": { "type": "integer", "description": "Unix timestamp in milliseconds indicating when the response was generated." }, "transaction_id": { "type": "string", "format": "uuid", "description": "Unique identifier for this API transaction, used for support and traceability." }, "message": { "type": "string", "description": "Human-readable description of the validation error." } } }, "examples": { "invalid pan pattern": { "summary": "Invalid PAN pattern", "value": { "code": 422, "timestamp": 1782394737209, "transaction_id": "8cb1eb54-ff5f-440c-b020-a0ad2b76af8c", "message": "Invalid PAN pattern" } }, "consent required": { "summary": "Consent required", "value": { "code": 422, "timestamp": 1782462501262, "transaction_id": "8879c031-0ae3-4004-824b-8a0c48fd034f", "message": "invalid parameter: Consent is required." } }, "reason cannot be empty": { "summary": "Reason cannot be empty", "value": { "code": 422, "timestamp": 1782462571342, "transaction_id": "bd41872d-e467-4254-bc44-58d397e62b11", "message": "Reason cannot be empty" } } } } } } } } }, "/kyc/pan/basic": { "get": { "summary": "PAN Verification [Basic]", "operationId": "verifyPANBasic", "tags": [ "PAN" ], "parameters": [ { "name": "pan", "in": "path", "description": "10-character Permanent Account Number to verify. Must follow the standard PAN format: five letters, four digits, one letter.", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{5}[0-9]{4}[A-Z]{1}$" } }, { "name": "consent", "in": "query", "description": "Explicit consent from the end user to verify their PAN details. Must be passed as \"Y\" or \"y\" to proceed.", "required": true, "schema": { "type": "string", "enum": [ "Y", "y" ] } }, { "name": "reason", "in": "query", "description": "Purpose for initiating the PAN verification, such as identity verification or KYC compliance. Used for audit and compliance traceability.", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "Authorization", "in": "header", "description": "JWT access token", "required": true, "example": "{{access_token}}", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "API key for identification", "required": true, "example": "{{api_key}}", "schema": { "type": "string" } }, { "name": "x-api-version", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "x-accept-cache", "in": "header", "required": false, "description": "Pass true to accept the cached response. If the header is not passed, or if false is sent as the value, the request will hit the origin.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 - OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "timestamp", "transaction_id", "data" ], "properties": { "code": { "type": "integer", "description": "HTTP status code of the response." }, "timestamp": { "type": "integer", "description": "Unix timestamp in milliseconds indicating when the response was generated." }, "transaction_id": { "type": "string", "format": "uuid", "description": "Unique identifier for this API transaction, used for support and traceability." }, "data": { "type": "object", "required": [ "@entity", "pan", "status", "category" ], "properties": { "@entity": { "type": "string", "enum": [ "pan" ], "description": "Entity type identifier for the PAN verification response." }, "pan": { "type": "string", "description": "The verified PAN.", "pattern": "^[A-Z]{5}[0-9]{4}[A-Z]{1}$", "minLength": 10, "maxLength": 10 }, "full_name": { "type": "string", "description": "Full name of the PAN holder as registered with the income tax authority." }, "status": { "type": "string", "enum": [ "VALID", "INVALID" ], "description": "Validity status of the PAN as reported by the income tax authority." }, "category": { "type": "string", "enum": [ "Individual", "Company", "Firm", "HUF", "Trust", "Government", "Body of Individuals", "Association of Persons", "Local Authority", "Artificial Judicial Person", "Pan not Available" ], "description": "Category of the PAN holder, derived from the fourth character of the PAN." } } } } }, "examples": { "successful response for individual": { "summary": "Successful response for individual", "value": { "code": 200, "timestamp": 1688557921287, "transaction_id": "ec2c8ac5-79d4-4ef2-a022-95da12d7d6c5", "data": { "@entity": "pan", "pan": "XXXPX1234A", "full_name": "JOHN RONALD DOE", "status": "VALID", "category": "Individual" } } } } } } }, "422": { "description": "422 - Unprocessable Entity", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "timestamp", "transaction_id", "message" ], "properties": { "code": { "type": "integer", "description": "HTTP status code of the response." }, "timestamp": { "type": "integer", "description": "Unix timestamp in milliseconds indicating when the response was generated." }, "transaction_id": { "type": "string", "format": "uuid", "description": "Unique identifier for this API transaction, used for support and traceability." }, "message": { "type": "string", "description": "Human-readable description of the validation error." } } }, "examples": { "Invalid PAN": { "summary": "Invalid PAN pattern", "value": { "code": 422, "timestamp": 1707480990556, "transaction_id": "8e4d4578-28d0-4f23-bf0f-3f1b5a0c2f7b", "message": "Invalid Pan pattern" } } } } } } } } } } }