IRN Verification

Endpoint Overview

POST /api/v1/corporate/irn-verification

Description

The IRN Verification API enables businesses to validate Invoice Reference Numbers (IRN) generated under the GST e-invoicing system in India. This API provides real-time verification of IRN authenticity, registration status, and associated metadata by querying the official Invoice Registration Portal (IRP) database.

IRN is a unique 64-character hash generated for every e-invoice and serves as a critical component of GST compliance. This API helps businesses verify the legitimacy of IRNs received from suppliers, prevent fraud, and ensure compliance with GST regulations.

Key Benefits

Instant Verification: Real-time validation of IRN numbers against the official IRP database

Fraud Prevention: Detect fake or invalid IRNs to prevent fraudulent transactions

Compliance Assurance: Ensure all invoices meet GST e-invoicing requirements

Automated Reconciliation: Streamline invoice verification processes and reduce manual effort

Use Cases

E-commerce & Retail

Financial Services

Enterprise & Manufacturing

Supplier Invoice Validation: Verify IRNs from multiple vendors before processing payments to ensure authenticity

Purchase Order Reconciliation: Automatically validate e-invoices against purchase orders during procurement workflows

Fraud Detection: Identify and flag suspicious or invalid IRNs in high-volume transaction environments

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.app

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

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	JWT Bearer token for authentication (Format: `Bearer YOUR_JWT_TOKEN`)
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
irn_number	string	Yes	64-character hexadecimal IRN hash to be verified. This is the unique Invoice Reference Number generated by the IRP

Example Request

{
    "irn_number": "01e1bf7b5d14563ef9e0b7b2d7a808a35333fe327fcbc1e901bf4db395ab5abc"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Contains the verification results and IRN details
data.client_id	string	Unique identifier for this verification request
data.irn_number	string	The IRN number that was verified
data.status	string	Registration status of the IRN (e.g., "Registered")
data.registered_date	string	Date when the IRN was registered (Format: YYYY-MM-DD)
data.registered_irp	string	Invoice Registration Portal where the IRN is registered (e.g., "NIC1")
status_code	integer	HTTP status code of the response
success	boolean	Indicates whether the API request was successful
message	string	Human-readable message describing the result
message_code	string	Machine-readable code for the message

Example Successful Response

{
    "data": {
        "client_id": "irn_verification_pUQUrxVjuEtpfqveJurQ",
        "irn_number": "01e1bf7b5d14563ef9e0b7b2d7a808a35333fe327fcbc1e901bf4db395ab5abc",
        "status": "Registered",
        "registered_date": "2023-04-30",
        "registered_irp": "NIC1"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid IRN Format

Authentication Error

{
    "status_code": 400,
    "success": false,
    "message": "Invalid IRN format provided",
    "message_code": "invalid_input"
}

This error occurs when the IRN number provided is not in the correct 64-character hexadecimal format.

Integration Best Practices

Security Recommendations

Secure Token Storage: Store JWT tokens securely using environment variables or secure vault services, never hardcode them in your application

Token Rotation: Implement automatic token refresh mechanisms to handle token expiration gracefully

HTTPS Only: Always use HTTPS endpoints to ensure encrypted data transmission

Input Validation: Validate IRN format (64 hexadecimal characters) on the client-side before making API calls to reduce unnecessary requests

Error Handling: Implement comprehensive error handling to manage authentication failures and invalid responses securely

User Experience Guidelines

Real-time Feedback: Provide immediate visual feedback when IRN verification is in progress

Clear Status Indication: Display verification results prominently with color-coded status indicators (green for verified, red for invalid)

Graceful Degradation: Handle API failures gracefully with user-friendly error messages and retry options

Batch Processing: For bulk verification, implement queuing mechanisms to prevent overwhelming users with multiple concurrent requests

Audit Trail: Maintain a verification history log for users to track previous IRN checks

Code Samples

cURL

Python

Node.js

Related APIs

GST Verification API: Validate GSTIN numbers and retrieve business details for comprehensive vendor verification

Company Master Data API: Access detailed company information including registration details and business activities

PAN Verification API: Verify PAN cards of business entities for complete KYC compliance

TAN Verification API: Validate Tax Deduction Account Numbers for organizations

Compliance and Legal Considerations

This API accesses official government data from the Invoice Registration Portal (IRP) system. Users must ensure compliance with:

GST Act and Rules: Adhere to all provisions under the Central Goods and Services Tax Act, 2017

Data Privacy: Handle IRN data in accordance with applicable data protection regulations and use it only for legitimate business purposes

Authorized Use: This API should only be used for verifying invoices in genuine business transactions

Record Retention: Maintain proper audit trails of all IRN verifications as per GST compliance requirements

Rate Limits: Respect API rate limits to ensure fair usage and system stability

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/irn-verification' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "irn_number": "01e1bf7b5d14563ef9e0b7b2d7a808a35333fe327fcbc1e901bf4db395ab5abc" }'

{ "data": { "client_id": "irn_verification_pUQUrxVjuEtpfqveJurQ", "irn_number": "01e1bf7b5d14563ef9e0b7b2d7a808a35333fe327fcbc1e901bf4db395ab5abc", "status": "Registered", "registered_date": "2023-01-01", "registered_irp": "NIC1" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

IRN Verification

IRN Verification#

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

IRN Verification

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples