IEC Verification API

The following document outlines the details of the IEC Verification API.

API Description

Objective

The IEC Verification API retrieves Importer Exporter Code (IEC) details for a given firm based on the provided IEC number, offering firm information, IEC status, ownership details, and compliance verification.

Input	Output
The IEC Number	The Details associated with the IEC. The complete list of output fields is available in the Success Response Details section

Did You know?

The Importer Exporter Code (IEC) is a mandatory identification number required for import or export from India.
IEC is issued by the Directorate General of Foreign Trade (DGFT) and is a 10-character alphanumeric code.
The IEC is necessary for businesses engaged in international trade to comply with Indian foreign trade regulations.

API URL

https://ind-engine.thomas.hyperverge.co/v1/iecVerification

API Endpoint

iecVerification

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should send all data through a POST request.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your idfirm for accessing the API.

API Request Details

Method - `POST`

Headers

Parameter	Mandatory or Optional	Description	Valid Values
`content-type`	Mandatory	This parameter defines the media type for the request payload.	application/json
`appId`	Mandatory	The application ID shared by HyperVerge	Not Applicable - this is a unique value
`appKey`	Mandatory	The application key shared by HyperVerge	Not Applicable - this is a unique value
`transactionId`	Mandatory	The unique ID for the customer journey.	Not Applicable - this is a unique value related to a transaction in your application

Input

The following table provides the details of the parameter required for the API's request body:

Parameter	Mandatory or Optional	Description	Allowed Values	Default Value
`iecNumber`	Mandatory	The IEC number to be verified	Format: 10-character alphanumeric code	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/iecVerification' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "iecNumber": "<Enter_the_IEC_Number>"
}'

Success Responses

The following code snippet demonstrates a success response from the API:

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "errdata": null,
    "data": {
      "iec_number": "<IEC_Number>",
      "iec_status": "<IEC_Status>",
      "firm_name": "<Name_Of_The_Firm>",
      "nature_of_concern": "<Type_Of_firm>",
      "category_of_exporters": "<Category_Of_Exporter>",
      "dob_incorporation": "<Date_Of_Incorporation_in_DD-MM-YYYY_Format>",
      "pan_number": "<Firm_PAN_Number>",
      "file_number": "<File_Number>",
      "file_date": "<File_Date_in_DD-MM-YYYY_Format>",
      "firm_mobile": "<Firm_Mobile_Number>",
      "firm_email": "<Firm_Email_Address>",
      "address": "<Registered_Address_Of_The_Firm>",
      "branch_details": [],
      "owner_details": [
        {
          "serial_number": "<Serial_Number>",
          "pan_number": "<Owner_PAN_Number>",
          "name": "<Name_Of_The_Owner>",
          "father_name": "<Father_Name_Of_The_Owner>",
          "address": "<Address_Of_The_Owner>"
        },
        {
          "serial_number": "<Serial_Number>",
          "pan_number": "<Owner_PAN_Number>",
          "name": "<Name_Of_The_Owner>",
          "father_name": "<Father_Name_Of_The_Owner>",
          "address": "<Address_Of_The_Owner>"
        }
      ],
      "RCMC": [
        {
          "slno": "<Serial_Number>",
          "rcmcNumber": "<RCMC_Number>",
          "issueDate": "<RCMC_Issue_Date_in_DD-MM-YYYY_Format>",
          "issueAuthority": "<Issuing_Authority>",
          "productsForWhichRegistered": "<Products_Registered_For>",
          "expiryDate": "<RCMC_Expiry_Date_in_DD-MM-YYYY_Format>",
          "status": "<RCMC_Status>",
          "source": "<Source>",
          "exporterType": "<Type_Of_Exporter>",
          "validityPeriod": "<Validity_Period>",
          "validatedByEpc": "<Validation_By_EPC>"
        },
        {
          "slno": "<Serial_Number>",
          "rcmcNumber": "<RCMC_Number>",
          "issueDate": "<RCMC_Issue_Date_in_DD-MM-YYYY_Format>",
          "issueAuthority": "<Issuing_Authority>",
          "productsForWhichRegistered": "<Products_Registered_For>",
          "expiryDate": "<RCMC_Expiry_Date_in_DD-MM-YYYY_Format>",
          "status": "<RCMC_Status>",
          "source": "<Source>",
          "exporterType": "<Type_Of_Exporter>",
          "validityPeriod": "<Validity_Period>",
          "validatedByEpc": "<Validation_By_EPC>"
        }
      ],
      "iec_issue_date": "<IEC_Issue_Date_in_DD-MM-YYYY_Format>",
      "del_status": "<Deletion_Status>",
      "dgft_ra_office": "<DGFT_RA_Office>",
      "iec_cancelled_date": "<IEC_Cancellation_Date>",
      "iec_suspended_date": "<IEC_Suspension_Date>"
    },
    "message": "<Success_Message>",
    "requestid": "<Request_ID>",
    "sequenceId": "<Sequence_ID>"
  }
}

Success Response Details

The following table outlines the details of the success response from the API:

Parameter	Type	Description
status	string	Indicates whether the API request was successful
statusCode	string	HTTP status code returned by the server
result	object	Container for the response data and metadata
errdata	object	Any error data returned during the request
iec_number	string	The IEC assigned to the firm
iec_status	string	The current status of the IEC
firm_name	string	The name of the registered firm
nature_of_concern	string	The type of business entity
category_of_exporters	string	Classification of the exporter based on business activities
dob_incorporation	string	Date when the firm was incorporated or established
pan_number	string	Permanent Account Number (PAN) assigned by tax authorities
file_number	string	Reference number for the IEC application file
file_date	string	Date when the IEC application was filed
firm_mobile	string	Contact mobile number of the firm
firm_email	string	Official email address of the firm for correspondence
address	string	Registered address of the firm including contact details and PIN code
branch_details	array	List of additional branches of the firm
owner_details	array	List of proprietors or owners associated with the firm
serial_number	string	Sequential identifier for the owner entry
pan_number	string	Permanent Account Number of the individual owner
name	string	Full name of the proprietor or director
father_name	string	Name of the proprietor's or director's father
address	string	Residential address of the proprietor or director
RCMC	object	Registration-cum-Membership Certificate (RCMC) details
slno	string	Serial number for the RCMC entry
rcmcNumber	string	Unique identifier assigned to the RCMC
issueDate	string	Date when the RCMC was issued
issueAuthority	string	Name of the Export Promotion Council that issued the certificate
productsForWhichRegistered	string	Product categories covered under the RCMC
expiryDate	string	Date when the RCMC certification expires
status	string	Additional status information about the RCMC
source	string	Source of the RCMC information in the system
exporterType	string	Classification of the exporter as Active or Expired
validityPeriod	string	Duration for which the RCMC remains valid
validatedByEpc	string	Type of exporter as validated by the Export Promotion Council

Failure Response

The following code snippet displays a failure response from the API:

{
    "status": "failure",
    "statusCode": 404,
    "error": "IEC number not found",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    
    }
}

Error Responses

The following are some error responses from the API:

{
    "status": "failure",
    "statusCode": 400,
    "error": "Please provide valid IEC number",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

{
    "status": "failure",
    "statusCode": 400,
    "error": "IEC Number must be 10 characters long",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    
    }
}

{
    "message": "Input Validation Error: requires property \"iecNumber\"",
    "statusCode": 400,
    "status": "failure"
}

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

{
    "status": "failure",
    "statusCode": 500,
    "error": "Internal Server Error",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    
    }
}

{
    "status": "failure",
    "statusCode": 503,
    "error": "source not available", 
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Failure and Error Response Details

A failure or error response from the module contains a failure status, with a relevant status code and error message.
The following table lists all error responses.

Status Code	Error Message	Error Description
400	Input Validation Error: requires property "iecNumber"	This occurs when the invalid parameter is present in request body
400	IEC Number must be 10 characters long	This occurs when the IEC number is empty or less than 10 digits
400	Please provide valid IEC number	This occurs when the IEC number is invalid
401	Missing/Invalid credentials	The request is either missing the mandatory `appId` and `appKey` combination or has invalid values
404	IEC number not found	No matching record is found against the IEC Number
500	Internal Server Error	Check API request headers and/or contact HyperVerge team for investigation
503	source not available	Issue from server side

API Description​

Objective​

API URL​

API Endpoint​

Overview​

Authentication​

API Request Details

Method - POST

Headers

Input​

Request​

Success Responses​

Success Response Details​

Failure Response​

Error Responses​

Failure and Error Response Details​