IRN Verification

Endpoint Overview

POST /api/v1/corporate/einvoice-irn

Description

This API endpoint allows users to verify the authenticity and validity of an Invoice Reference Number (IRN) by analyzing an uploaded invoice document. The service extracts key invoice details including the IRN number, seller and buyer GSTIN, document information, and financial data from the uploaded file, enabling businesses to validate e-invoice compliance with GST regulations.

Key Benefits

Automated extraction of IRN and invoice details from PDF or image files

Instant verification of e-invoice authenticity and compliance

Simplified reconciliation of invoice data against business records

Reduction in manual data entry errors and processing time

Use Cases

Finance & Accounting

Supply Chain

Auditing & Compliance

Verify vendor invoices before processing payments

Automate accounts payable workflows with validated invoice data

Ensure tax compliance by confirming IRN validity

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	multipart/form-data

Request Body

Parameter	Type	Required	Description
file	File	Yes	The invoice document to be verified (PDF or Image format)
base64	String	No	Base64 image
Link	String	No	Image Link
use_pdf	Boolean	No	Set to `true` if the uploaded file is a PDF document

Example Request

   'file=@/path/to/invoice.pdf' \
   'use_pdf=true'

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the extracted invoice information
data.client_id	String	Unique identifier for the verification request
data.seller_gstin	String	GSTIN (Goods and Services Tax Identification Number) of the seller
data.buyer_gstin	String	GSTIN of the buyer
data.document_no	String	Invoice document number
data.document_type	String	Type of document (e.g., INV for Invoice)
data.document_issue_date	String	Date when the invoice was issued (YYYY-MM-DD format)
data.invoice_amount	String	Total invoice amount including taxes
data.total_item	Number	Number of items included in the invoice
data.hsn_code	String	Harmonized System of Nomenclature code for the goods/services
data.irn_number	String	Invoice Reference Number (IRN) generated for the invoice
data.irn_issue_date	String	Date and time when the IRN was generated (YYYY-MM-DD HH:MM:SS format)
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": "einvoice_irn_kzCkdFnyjlqDOxdbwzfz",
        "seller_gstin": "07ABCCS1234R2ZT",
        "buyer_gstin": "07AUJPS1234P2ZX",
        "document_no": "INV-301112345",
        "document_type": "INV",
        "document_issue_date": "2024-11-30",
        "invoice_amount": "11800.0",
        "total_item": 1,
        "hsn_code": "997331",
        "irn_number": "b6a05e2db7cef123456bb8d4253c30b89c7097f513bdfc3138b9f176fd7841",
        "irn_issue_date": "2024-11-30 12:02:00"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid File Format

Authentication Error

IRN Not Found

{
    "status_code": 400,
    "success": false,
    "message": "Invalid file format. Please upload a PDF or image file.",
    "message_code": "invalid_file_format"
}

This error occurs when the uploaded file is not a valid PDF or image format.

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

Validate file types and sizes before uploading to prevent security vulnerabilities

User Experience Guidelines

Implement a progress indicator during file upload and processing

Provide clear error messages to users when verification fails

Display extracted invoice details in a user-friendly format for review

Allow users to retry with a different file if verification fails

Code Samples

cURL

Python

Node.js

Related APIs

E-Invoice Generation API: Create GST-compliant e-invoices with IRN generation

Document OCR API: Extract structured data from various document types

GSTIN Verification API: Validate GSTIN numbers against government database

Compliance and Legal Considerations

This API helps businesses comply with e-invoicing requirements under GST regulations in India. The IRN verification process ensures that invoices meet the standards set by the GST Network (GSTN). Users should ensure they have proper authorization to access the invoice data being verified. All data processing should comply with applicable data protection regulations.

{ "data": { "client_id": "einvoice_irn_kzCkdFnyjlqDOxdbwzfz", "seller_gstin": "07ABCCS1234R2ZT", "buyer_gstin": "07AUJPS1234P2ZX", "document_no": "INV-301112345", "document_type": "INV", "document_issue_date": "2024-11-30", "invoice_amount": "11800.0", "total_item": 1, "hsn_code": "997331", "irn_number": "b6a05e2db7cef123456bb8d4253c30b89c7097f513bdfc3138b9f176fd7841", "irn_issue_date": "2024-11-30 12:02:00" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

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