Create Client

Endpoint Overview

POST /api/v1/itr/create-client

Description

This API endpoint creates a new client in the ITR (Income Tax Return) system and returns a unique client ID. The client ID serves as a persistent identifier for subsequent API calls related to this user's ITR processing. This endpoint is the first step in the ITR filing workflow, establishing the user's identity in the system.

Key Benefits

Quick client registration with minimal required information

Secure authentication using existing credentials

Unique client ID generation for tracking all subsequent ITR operations

Seamless integration into existing user management systems

Use Cases

Financial Services

HR & Payroll

Tax Software

Integrate ITR filing capabilities into banking applications

Enable tax preparation services within financial planning platforms

Automate client onboarding for tax advisory firms

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 authentication using JWT format
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
username	String	Yes	Login username (typically PAN number in format like ABCDE1234F)
password	String	Yes	Login password for the ITR portal
expiry	Integer	No	Expiry

Example Request

{
    "username": "APBPG7589H",
    "password": "Lakshay@1407"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the response data
data.client_id	String	Unique identifier for the created client
status_code	Integer	HTTP status code of the response
message_code	String	Short code indicating the result status
message	String	Human-readable description of the result
success	Boolean	Indicates whether the request was successful

Example Successful Response

{
    "data": {
        "client_id": "itr_HgCSFcWUnhynhGAKBiha"
    },
    "status_code": 200,
    "message_code": "success",
    "message": "Client created successfully",
    "success": true
}

Possible Error Responses

Authentication Error

Invalid Credentials

Missing Parameters

{
    "status_code": 401,
    "message_code": "unauthorized",
    "message": "Invalid or missing authentication token",
    "success": false
}

This error occurs when the JWT token is missing, expired, or invalid.

Integration Best Practices

Security Recommendations

Store the client_id securely as it will be used for all subsequent API calls

Implement proper encryption for storing user credentials

Use environment variables for API keys and sensitive configuration

Implement request timeout and retry mechanisms for reliability

User Experience Guidelines

Provide clear feedback to users during the client creation process

Implement proper error handling to display user-friendly messages

Store the client_id in your database and associate it with your user records

Consider implementing a status indicator during the API call process

Code Samples

cURL

Python

Node.js

Related APIs

Fetch ITR Status: Check the status of an ITR filing using the client_id

Submit ITR Details: Submit detailed ITR information for processing

Download ITR Acknowledgement: Retrieve the acknowledgement document for a filed ITR

Verify ITR Filing: Verify if an ITR has been successfully filed

Compliance and Legal Considerations

This API handles sensitive personal and financial information. Ensure your implementation complies with data protection regulations like GDPR or local data privacy laws. The credentials provided should be handled securely and not stored in plaintext. Users should be informed about how their credentials will be used and processed.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/itr/create-client' \ --header 'Content-Type: application/json' \ --data-raw '{ "username": "APBPG7589H", "password": "Lakshay@1407" }'

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Create Client

Create Client#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Create Client

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples