GST Upload

Endpoint Overview

POST /api/v1/ocr/gst

Description

This API endpoint enables the extraction of information from GST (Goods and Services Tax) documents through OCR (Optical Character Recognition) technology. It processes uploaded GST certificate images or PDFs and returns structured data including registration details, business information, and tax identification numbers. This service helps businesses automate data entry, verify GST registrations, and streamline compliance processes.

Key Benefits

Automated extraction of GST registration details without manual data entry

High accuracy OCR processing specifically optimized for Indian GST certificates

Structured data output for easy integration with business systems and databases

Reduces processing time from minutes to seconds compared to manual verification

Use Cases

Financial Services

E-commerce

Enterprise Solutions

Automated KYC verification for business clients during onboarding

Validation of vendor GST details before processing payments

Streamlining business loan application processing by verifying tax compliance

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	JWT Bearer token for authentication. Format: `Bearer <your_token>`
Content-Type	Yes	Must be set to `multipart/form-data` for file upload

Request Body

1. For File Upload

Parameter	Type	Required	Description
file	Image	Yes	Upload Cheque Image
use_pdf	Boolean	No	Set to true if the file type is PDF

2. For Base64 Input

Parameter	Type	Required	Description
base_64	String	Yes	Cheque Image in Base64 format

3. For Image URL Input

Parameter	Type	Required	Description
link	String	Yes	Cheque Image Link/URL

Example Request

# Multipart form data with file upload
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="gst_certificate.pdf"
Content-Type: application/pdf

Process Response

Response Parameters

Parameter	Type	Description
success	Boolean	Indicates if the API request was successful
data	Object	Contains the extracted GST information
data.gstin	String	GST Identification Number
data.legal_name	String	Legal name of the business entity
data.trade_name	String	Trade name of the business
data.date_of_registration	String	Date when GST was registered
data.constitution_of_business	String	Business constitution type
data.taxpayer_type	String	Type of taxpayer
data.nature_of_business_activity	Array	List of business activities
data.principal_place_of_business	String	Primary business address
data.additional_place_of_business	Array	Additional business locations
data.state_jurisdiction	String	State jurisdiction details
data.center_jurisdiction	String	Central jurisdiction details
data.is_verified	Boolean	Verification status of the document
data.verification_score	Number	Confidence score of the verification
request_id	String	Unique identifier for the request

Example Successful Response

{
  "success": true,
  "data": {
    "gstin": "29AADCB2230M1ZP",
    "legal_name": "ACME CORPORATION PRIVATE LIMITED",
    "trade_name": "ACME CORP",
    "date_of_registration": "01/07/2017",
    "constitution_of_business": "Private Limited Company",
    "taxpayer_type": "Regular",
    "nature_of_business_activity": [
      "Factory / Manufacturing",
      "Wholesale Business",
      "Retail Business"
    ],
    "principal_place_of_business": "123, TECH PARK, ELECTRONIC CITY PHASE 1, BANGALORE, Karnataka, 560100",
    "additional_place_of_business": [
      "456, BUSINESS HUB, MG ROAD, BANGALORE, Karnataka, 560001"
    ],
    "state_jurisdiction": "Karnataka",
    "center_jurisdiction": "Range-14",
    "is_verified": true,
    "verification_score": 0.95
  },
  "request_id": "req_9f8e7d6c5b4a3210"
}

Possible Error Responses

Authentication Error

Invalid Image

Invalid File Format

Server Error

{
    "error": null,
    "message": "Your token is invalid. Please ensure that correct token is being used.",
    "status_code": 401,
    "success": false,
    "message_code": "invalid_token"
}

Occurs when the JWT token is missing, invalid, or expired.

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 gracefully

Use HTTPS for all API communications to ensure data encryption in transit

Implement proper error handling to avoid exposing sensitive information in error messages

User Experience Guidelines

Provide clear feedback to users while the document is being processed

Implement a timeout handling mechanism as OCR processing may take several seconds

Allow users to review extracted information before submission to backend systems

Provide options for manual correction in case of OCR inaccuracies

Code Samples

cURL

Python

Node.js

Related APIs

PAN Card OCR: Extract information from PAN cards using OCR technology

Aadhaar Card OCR: Process Aadhaar cards to extract personal information

Business Registration OCR: Extract data from various business registration documents

Invoice OCR: Process and extract structured data from invoice documents

Compliance and Legal Considerations

When using this API, ensure you have proper consent from users before processing their GST documents. The API requires explicit consent to be provided in the request. GST information is considered business-sensitive data in India, and its processing may be subject to data protection regulations. Ensure your usage complies with applicable laws including the Information Technology Act, 2000 and any relevant data protection regulations.

{ "success": true, "data": { "gstin": "29AADCB2230M1ZP", "legal_name": "ACME CORPORATION PRIVATE LIMITED", "trade_name": "ACME CORP", "date_of_registration": "01/07/2017", "constitution_of_business": "Private Limited Company", "taxpayer_type": "Regular", "nature_of_business_activity": [ "Factory / Manufacturing", "Wholesale Business", "Retail Business" ], "principal_place_of_business": "123, TECH PARK, ELECTRONIC CITY PHASE 1, BANGALORE, Karnataka, 560100", "additional_place_of_business": [ "456, BUSINESS HUB, MG ROAD, BANGALORE, Karnataka, 560001" ], "state_jurisdiction": "Karnataka", "center_jurisdiction": "Range-14", "is_verified": true, "verification_score": 0.95 }, "request_id": "req_9f8e7d6c5b4a3210" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

GST Upload

GST Upload#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

1. For File Upload#

2. For Base64 Input#

3. For Image URL Input#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

GST Upload

Description

Use Cases

Technical Implementation

Request Headers

Request Body

1. For File Upload

2. For Base64 Input

3. For Image URL Input

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples