IEC Details

Endpoint Overview

POST /api/v1/corporate/iec-details

Description

This API endpoint retrieves detailed information about an entity based on its Import Export Code (IEC) number. It provides comprehensive data including personal details such as firm name, address, IEC status, and PAN number. This verification service helps businesses validate trade partners and ensure compliance with import/export regulations.

Key Benefits

Instant verification of IEC number validity and status

Access to comprehensive business entity information for KYC processes

Streamlined trade partner verification for import/export operations

Reduced manual verification efforts and associated costs

Use Cases

Financial Services

Trade & Logistics

Compliance

Verify trade finance applicants' IEC credentials before approving loans

Validate import/export businesses during corporate account opening

Confirm IEC status during periodic KYC refreshes for existing clients

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

Request Body

Parameter	Type	Required	Description
iec_number	String	Yes	The Import Export Code (IEC) number to be verified

Example Request

{
    "iec_number": "123456789"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for the response data
data.client_id	String	Unique identifier for the client
data.iec_number	String	The IEC number that was verified
data.personal_details	Object	Container for personal details of the entity
data.personal_details.ie_code	String	Import Export Code of the entity
data.personal_details.name	String	Registered name of the firm/entity
data.personal_details.address	String	Registered address of the firm/entity
data.personal_details.iec_status	String	Current status of the IEC (e.g., "Valid")
data.personal_details.pan	String	PAN number of the firm/entity (partially masked)
data.bank_details	Object	Container for bank details (may be empty)
status_code	Number	HTTP status code of the response
success	Boolean	Indicates if the API call was successful
message	String	Human-readable status message
message_code	String	Machine-readable status code

Example Successful Response

{
    "data": {
        "client_id": "iec_eXYgTyaifZoHqBhxhtbd",
        "iec_number": "123456789",
        "personal_details": {
            "ie_code": "123456789",
            "name": "Angel BizLink",
            "address": "360002 ,Rajkot , RAJKOT ,GUJARAT,360002",
            "iec_status": "Valid",
            "pan": "XXXX1234X"
        },
        "bank_details": {}
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid IEC Number

Authentication Error

{
    "status_code": 400,
    "success": false,
    "message": "Invalid IEC number provided",
    "message_code": "invalid_iec"
}

This error occurs when the provided IEC number format is invalid or does not exist in the system.

Integration Best Practices

Security Recommendations

Store API credentials securely and never expose them in client-side code

Implement proper error handling to prevent leaking sensitive information

Regenerate JWT tokens periodically rather than storing them long-term

Implement IP whitelisting for additional security when possible

User Experience Guidelines

Implement client-side validation of IEC number format before making API calls

Display a loading indicator during API calls to improve perceived performance

Cache verified IEC details (within compliance limits) to reduce redundant API calls

Provide clear error messages to end-users when verification fails

Code Samples

cURL

Python

Node.js

Related APIs

GST Verification API - Verify GST registration details of businesses

PAN Verification API - Verify PAN card details for individuals and businesses

Business Verification API - Comprehensive verification of business entities

Compliance and Legal Considerations

The IEC verification data should be used in accordance with applicable trade and commerce regulations. The data retrieved should be handled securely and in compliance with data protection laws. Ensure you have proper consent before storing any personal information retrieved through this API. The information should only be used for legitimate business purposes such as KYC verification, trade partner validation, or regulatory compliance.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/corporate/iec-details' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "iec_number": "123456789" }'

{ "data": { "client_id": "iec_eXYgTyaifZoHqBhxhtbd", "iec_number": "123456789", "personal_details": { "ie_code": "123456789", "name": "Angel BizLink", "address": "360002 ,Rajkot , RAJKOT ,GUJARAT,360002", "iec_status": "Valid", "pan": "XXXX1234X" }, "bank_details": {} }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

IEC Details

IEC Details#

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

IEC Details

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples