Get Profile Details

Endpoint Overview

GET /api/v1/itr/get-profile/{client_id}

Description

This API endpoint retrieves comprehensive Income Tax Return (ITR) profile details for a specified client. It provides access to the client's address information, PAN details, contact information, jurisdiction details, and Aadhaar status as recorded in their ITR profile. This endpoint is essential for KYC processes, identity verification, and financial services that require validated tax profile information.

Key Benefits

Retrieve verified ITR profile data directly from official tax records

Access comprehensive personal and contact details in a single API call

Validate client identity using government-recognized documentation

Streamline KYC and onboarding processes with reliable tax information

Use Cases

Financial Services

Fintech

Compliance

Verify customer identity during loan application processing

Validate client information for account opening procedures

Confirm tax residency status for investment products

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication (JWT format)
Content-Type	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
client_id	String	Yes	Unique identifier of the client whose profile details are being requested

No request body is required for this GET endpoint.

Process Response

Response Parameters

The response contains a nested structure with the following main sections:

Parameter	Type	Description
data	Object	Contains the profile details
data.profile_details	Object	Contains address, PAN, contact, jurisdiction, and Aadhaar information
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	Response message
message_code	String	Code indicating the response status

Address Object

Parameter	Type	Description
country	String	Country name as per ITR address details
door_number	String	House number as per ITR address details
street	String	Street name as per ITR address details
pin_code	Integer	Pincode number as per ITR address details
zip_code	Integer	Zipcode number as per ITR address details (may be null)
locality	String	Local area name as per ITR address details
post_office	String	Post office as per ITR address details
city	String	City name as per ITR address
state	String	State name as per ITR address details

PAN Object

Parameter	Type	Description
pan	String	PAN number as per ITR PAN details
name	String	Name as per ITR PAN details
dob	Object	Date of birth with format: {"date": "YYYY-MM-DD"}
gender	String	Gender as per ITR PAN details
category	String	PAN category as per ITR PAN details
address	String	Address as per ITR PAN details
status	String	PAN number status as per ITR PAN details
indian_citizen	String	Indian citizenship check (Yes or No) as per ITR PAN details

Contact Object

Parameter	Type	Description
resident	Boolean	Check residential status
non_resident	Boolean	Check non-residential status
primary_mobile	String	Primary mobile number as per ITR contact details
primary_mobile_belongs_to	String	Primary mobile number belongs to as per ITR contact details
primary_email	String	Primary email ID as per ITR contact details
primary_email_belongs_to	String	Primary email ID belongs to as per ITR contact details
secondary_mobile	String	Secondary mobile number as per ITR contact details
secondary_mobile_belongs_to	String	Secondary mobile number belongs to as per ITR contact details
secondary_email	String	Secondary email ID as per ITR contact details
secondary_email_belongs_to	String	Secondary email ID belongs to as per ITR contact details

Jurisdiction Object

Parameter	Type	Description
area_code	String	Area code as per jurisdiction details
ao_type	String	AO type as per jurisdiction details
range_code	String	Range code as per jurisdiction details
ao_number	String	AO number as per jurisdiction details
jurisdiction	String	Jurisdiction area as per jurisdiction details
building_name	String	Building name as per jurisdiction details
email_id	String	Jurisdiction office email ID as per jurisdiction details
ao_building_id	String	AO building ID as per jurisdiction details

Aadhaar Object

Parameter	Type	Description
aadhaar_number	String	Aadhaar number as per Aadhaar details
aadhaar_status	String	Aadhaar status as per Aadhaar details

Example Successful Response

{
    "data": {
        "profile_details": {
            "address": {
                "country": "INDIA",
                "door_number": "21/H",
                "street": "GORA ROAD",
                "pin_code": 700010,
                "zip_code": null,
                "locality": "Kolkata",
                "post_office": "Intally S.O",
                "city": "MAHWA",
                "state": ""
            },
            "pan": {
                "pan": "AAPPL2222A",
                "name": "SURBHI",
                "dob": {
                    "date": "1989-07-11"
                },
                "gender": "M",
                "category": "Individual",
                "address": "21/H, None, GORA ROAD, None, MAHWA, 700010",
                "status": "Active",
                "indian_citizen": "Yes"
            },
            "contact": {
                "resident": true,
                "non_resident": false,
                "primary_mobile": "9873672577",
                "primary_mobile_belongs_to": "Self",
                "primary_email": "surbhia@gmail.com",
                "primary_email_belongs_to": "Self",
                "secondary_mobile": "",
                "secondary_mobile_belongs_to": "",
                "secondary_email": "",
                "secondary_email_belongs_to": ""
            },
            "jurisdiction": {
                "area_code": "WG",
                "ao_type": "W",
                "range_code": "32",
                "ao_number": "9",
                "jurisdiction": "WARD 33(2)",
                "building_name": "10, MIDDLETON",
                "email_id": "MAHWA.ITO33.2@INCOMETAX.GOV.IN",
                "ao_building_id": "CL04"
            },
            "aadhaar": {
                "aadhaar_number": "",
                "aadhaar_status": "Linked"
            }
        }
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Client ID

Authentication Error

Server Error

{
    "status_code": 400,
    "success": false,
    "message": "Invalid client_id provided",
    "message_code": "invalid_client_id"
}

This error occurs when the provided client_id is invalid or not found in the system.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code

Implement token refresh mechanisms to handle token expiration

Use HTTPS for all API communications to ensure data encryption in transit

Implement proper error handling to avoid exposing sensitive information

User Experience Guidelines

Implement caching strategies to reduce redundant API calls for the same client_id

Display a loading indicator during API calls to improve user experience

Provide clear error messages to end-users when API calls fail

Format and display the retrieved profile data in a user-friendly manner

Code Samples

cURL

Python

Node.js

Related APIs

ITR Filing Status API: Retrieve the status of a client's ITR filing

ITR Document Download API: Download ITR acknowledgment and form documents

PAN Verification API: Verify PAN details independently

Aadhaar Verification API: Verify Aadhaar details independently

Compliance and Legal Considerations

This API provides access to sensitive personal and financial information. Ensure you have proper consent from the individual before accessing their ITR profile data. Usage of this API must comply with relevant data protection regulations including but not limited to the Information Technology Act, 2000 and the Personal Data Protection Bill. Ensure that data retrieved is stored securely and used only for the purpose for which consent was obtained.

{ "data": { "profile_details": { "address": { "country": "INDIA", "door_number": "21/H", "street": "GORA ROAD", "pin_code": 700010, "zip_code": null, "locality": "Kolkata", "post_office": "Intally S.O", "city": "MAHWA", "state": "" }, "pan": { "pan": "AAPPL2222A", "name": "SURBHI", "dob": { "date": "1989-07-11" }, "gender": "M", "category": "Individual", "address": "21/H, None, GORA ROAD, None, MAHWA, 700010", "status": "Active", "indian_citizen": "Yes" }, "contact": { "resident": true, "non_resident": false, "primary_mobile": "9873672577", "primary_mobile_belongs_to": "Self", "primary_email": "surbhia@gmail.com", "primary_email_belongs_to": "Self", "secondary_mobile": "", "secondary_mobile_belongs_to": "", "secondary_email": "", "secondary_email_belongs_to": "" }, "jurisdiction": { "area_code": "WG", "ao_type": "W", "range_code": "32", "ao_number": "9", "jurisdiction": "WARD 33(2)", "building_name": "10, MIDDLETON", "email_id": "MAHWA.ITO33.2@INCOMETAX.GOV.IN", "ao_building_id": "CL04" }, "aadhaar": { "aadhaar_number": "", "aadhaar_status": "Linked" } } }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Get Profile Details

Get Profile Details#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Path Parameters#

Response Parameters#

Address Object#

PAN Object#

Contact Object#

Jurisdiction Object#

Aadhaar Object#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Get Profile Details

Description

Use Cases

Technical Implementation

Request Headers

Path Parameters

Response Parameters

Address Object

PAN Object

Contact Object

Jurisdiction Object

Aadhaar Object

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples