Check Credentials

Endpoint Overview

POST /api/v1/itr/check-credentials

Description

This API endpoint allows you to verify whether a client ID is valid and active in the Surepass system. It provides a simple way to check the status of client credentials before attempting to use them for ITR (Income Tax Return) related operations, ensuring that your integration is properly configured.

Key Benefits

Quick validation of client credentials without initiating a full transaction

Reduces failed API calls due to invalid credentials

Helps troubleshoot integration issues efficiently

Enables proactive monitoring of credential status

Use Cases

Financial Services

Tax Preparation

Enterprise Solutions

Verify client credentials before initiating tax filing processes

Validate system integration during onboarding of new customers

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

Request Body

Parameter	Type	Required	Description
client_id	String	Yes	Unique identifier of the client account to check

Example Request

{
    "client_id": "itr_hIljWFhdruRxPAPTGzQs"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the response data
data.success	Boolean	Indicates whether the client account exists or not
status_code	Integer	HTTP status code of the response
message_code	String	Short code indicating the result of the operation
message	String	Human-readable message describing the result
success	Boolean	Overall success status of the API call

Example Successful Response

{
    "data": {
        "success": true
    },
    "status_code": 200,
    "message_code": "success",
    "message": "Success",
    "success": true
}

Possible Error Responses

Invalid Client ID

Authentication Error

{
    "data": {
        "success": false
    },
    "status_code": 400,
    "message_code": "invalid_client_id",
    "message": "The provided client ID does not exist",
    "success": false
}

Returned when the provided client ID is 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

Implement proper error handling for authentication failures

User Experience Guidelines

Check credentials proactively before initiating user workflows

Implement clear error messages for end-users when credential issues occur

Consider implementing automatic retry with backoff for intermittent failures

Cache credential status appropriately to reduce unnecessary API calls

Code Samples

cURL

Python

Node.js

Related APIs

ITR Status Check - Retrieve the status of an ITR filing

ITR Filing Initiation - Start the ITR filing process

Client Registration - Register a new client in the system

Compliance and Legal Considerations

This API involves checking credentials for tax-related services. Ensure your use complies with local tax regulations and data protection laws. Client IDs should be handled securely and access to this API should be restricted to authorized personnel only.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Check Credentials

Check Credentials#

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

Check Credentials

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples