GST Upload

Endpoint Overview

POST /api/v1/ocr/gst

Description

The GST OCR API enables automated extraction of GST (Goods and Services Tax) registration information from GST certificate documents using Optical Character Recognition (OCR) technology. By submitting a GST certificate image or document file, the API intelligently identifies, reads, and returns structured data — most notably the GSTIN (GST Identification Number) — along with a confidence score indicating the accuracy of the extracted data.

This API is built to handle real-world document variations, supporting standard GST registration certificate formats issued by the Government of India. It returns the extracted fields in a clean, machine-readable JSON format, making it easy to integrate into any KYC (Know Your Customer), onboarding, or compliance workflow.

Key Benefits

Automated Data Extraction: Eliminates manual data entry by automatically extracting GSTIN and document metadata from uploaded GST certificates.

Confidence Scoring: Each extracted field includes a confidence score (0–100), enabling downstream systems to flag low-confidence results for manual review.

Standard Document Detection: The API identifies whether the submitted document matches a standard GST registration certificate format, reducing false positives.

Seamless KYC Integration: Accelerates business onboarding and vendor verification workflows by providing instant, structured GST data extraction.

Use Cases

Financial Services

E-Commerce & Marketplaces

HR & Staffing

Loan & Credit Onboarding: Automatically extract and verify GSTIN from GST certificates submitted by business loan applicants, reducing manual document review time.

Merchant Verification: Banks and payment processors can validate merchant GST registrations instantly during account setup and periodic re-KYC processes.

Technical Implementation

Authentication

All API requests must be authenticated using a JWT Bearer Token. Follow the steps below to authenticate your requests:

Obtain API Credentials: Register with Surepass Technologies to receive your API key for the desired environment.

Use the JWT Token: Your JWT token acts as the Bearer token for all API calls. No additional token generation step is required — simply use the token provided by Surepass directly.

Include in Requests: Attach the token to every request using the Authorization header in the following format:

Authorization: Bearer <YOUR_JWT_TOKEN>

⚠️ Use separate tokens for the sandbox and production environments. Do not use a sandbox token against the production endpoint, or vice versa.

Environment	Base URL
Sandbox	`https://sandbox.surepass.app`
Production	`https://kyc-api.surepass.app`

Request Parameters

Request Headers

Header	Required	Description
`Authorization`	Yes	Bearer token for authentication. Format: `Bearer <YOUR_JWT_TOKEN>`
`Content-Type`	Yes	Must be `multipart/form-data` since the request body contains a file upload

Request Body

The request body must be sent as multipart/form-data.

Parameter	Type	Required	Description
`file`	`file`	Yes	The GST certificate document file to be processed. Upload the image or scanned PDF of the GST certificate.

Example Request

📌 The file field must reference a valid local file path. Ensure the file is a clear, legible image or document of the GST registration certificate for optimal OCR accuracy.

Process Response

Response Parameters

The API returns a JSON object with the following structure:

Parameter	Type	Description
`data`	`object`	The top-level data object containing OCR results.
`data.client_id`	`string`	A unique identifier for the OCR request, generated by the Surepass system for tracking purposes.
`data.ocr_fields`	`array`	An array of objects containing extracted OCR field data from the submitted document.
`data.ocr_fields[].document_type`	`string`	The type of document identified by the OCR engine. For GST certificates, this will be `"gst_reg"`.
`data.ocr_fields[].gstin`	`object`	An object containing the extracted GSTIN value and its associated confidence score.
`data.ocr_fields[].gstin.value`	`string`	The extracted GSTIN (GST Identification Number) from the document.
`data.ocr_fields[].gstin.confidence`	`integer`	Confidence score (0–100) indicating the OCR engine's certainty in the extracted GSTIN value. Higher is better.
`data.ocr_fields[].standard_document`	`boolean`	Indicates whether the submitted document matches a standard GST registration certificate format (`true`/`false`).
`status_code`	`integer`	HTTP-equivalent status code for the API response. `200` indicates a successful operation.
`message_code`	`string`	A machine-readable status code for the response. `"success"` indicates the request was processed successfully.
`message`	`string` \| `null`	A human-readable message describing the response. Returns `null` on success.
`success`	`boolean`	Top-level flag indicating whether the API request was successful (`true`) or not (`false`).

Example Successful Response

{
  "data": {
    "client_id": "ocr_gst_qpNcekMYzKlvIMenPCRM",
    "ocr_fields": [
      {
        "document_type": "gst_reg",
        "gstin": {
          "value": "03AAMFB8673Q1ZP",
          "confidence": 97
        },
        "standard_document": true
      }
    ]
  },
  "status_code": 200,
  "message_code": "success",
  "message": null,
  "success": true
}

Possible Error Responses

Unauthorized (401)

Bad Request (400)

Unprocessable Entity (422)

Internal Server Error (500)

{
  "data": null,
  "status_code": 401,
  "message_code": "unauthorized",
  "message": "Authentication credentials were not provided or are invalid.",
  "success": false
}

Cause: This error occurs when the Authorization header is missing, malformed, or contains an invalid/expired JWT token. Ensure you are using a valid Bearer token for the correct environment (sandbox or production).

Integration Best Practices

Security Recommendations

Keep JWT Tokens Confidential: Never expose your JWT Bearer token in client-side code, public repositories, or logs. Store tokens securely using environment variables or secrets management systems.

Use Environment-Specific Tokens: Always use separate JWT tokens for sandbox and production environments. Mixing tokens can result in authentication failures or unintended data exposure.

Rotate Tokens Periodically: Implement a token rotation policy and immediately revoke tokens that may have been compromised.

Transmit Over HTTPS Only: All API calls must be made over HTTPS. Never send requests over plain HTTP, as this exposes the JWT token and document data in transit.

User Experience Guidelines

Validate File Before Upload: Implement client-side validation to ensure the uploaded file is a supported image format (e.g., JPG, PNG, PDF) and does not exceed a reasonable file size limit before submitting to the API.

Use Confidence Scores for Review Flags: If the gstin.confidence score returned is below a threshold (e.g., below 85), consider prompting the user to re-upload a clearer image or routing the record for manual review.

Provide Clear Upload Instructions: Guide end-users to upload flat, well-lit, and unobstructed images of their GST certificates to maximize OCR accuracy and reduce failed extraction attempts.

Handle standard_document: false Gracefully: When the API returns standard_document: false, inform users that the document may not have been recognized as a standard GST certificate and request re-submission with the correct document.

Code Samples

cURL

Python

Node.js

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

{ "data": { "client_id": "ocr_gst_qpNcekMYzKlvIMenPCRM", "ocr_fields": [ { "document_type": "gst_reg", "gstin": { "value": "03AAMFB8673Q1ZP", "confidence": 97 }, "standard_document": true } ] }, "status_code": 200, "message_code": "success", "message": null, "success": true }

GST Upload

GST Upload#

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

GST Upload

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples