Bulk Status

Endpoint Overview

GET /api/v1/bulk-solver/status/{client_id}

Description

This API endpoint allows you to check the status of a previously submitted bulk processing job. After initiating a bulk upload operation through the Bulk Upload API, you can use this endpoint to track the progress of your job, determine if it has completed successfully, and retrieve the download link for the processed results when available.

Key Benefits

Real-time status tracking of bulk processing jobs

Immediate access to download links upon job completion

Simple integration with a single client ID parameter

Efficient monitoring of large-scale data processing operations

Use Cases

Financial Services

E-commerce

Enterprise Solutions

Track status of bulk GSTIN verification requests for vendor onboarding

Monitor progress of customer KYC document verification batches

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 authentication using JWT
Content-Type	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
client_id	String	Yes	The Client ID obtained from the Bulk Upload API that uniquely identifies your bulk processing job

Request Body

No request body is required for this endpoint.

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the details of the bulk processing job
data.client_id	String	Client ID obtained from the Bulk Upload API
data.type_of_job	String	Specifies the type of file being processed (e.g., "gstin")
data.job_status	String	Current status of the task: "pending", "completed", "failed", or "success"
data.download_link	String	URL to download the solution upon completion (only available when job_status is "completed" or "success")
status_code	Integer	HTTP status code of the response
message_code	String	Brief status message code
message	String or null	Detailed message about the response (if applicable)
success	Boolean	Indicates whether the API call was successful

Example Successful Response

{
    "data": {
        "client_id": "bulk_solver_MtgsMgkeieLxIwovtpRT",
        "type_of_job": "gstin",
        "job_status": "success",
        "download_link": "https://bulk-request-docs.s3.amazonaws.com/bulk_solver_MtgsMgkeieLxIwovtpRT-bulk-2024-01-11-064415133845.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5FYWPQJEB%2F20240122%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20240122T092821Z&X-Amz-Expires=600&X-A"
    },
    "status_code": 200,
    "message_code": "success",
    "message": null,
    "success": true
}

Possible Error Responses

Invalid Client ID

Authentication Error

{
    "data": null,
    "status_code": 404,
    "message_code": "error",
    "message": "No job found with the provided client_id",
    "success": false
}

This error occurs when the provided client_id does not match any existing bulk processing job.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code

Implement proper error handling for authentication failures

Set up automatic token refresh mechanisms to handle token expiration

Use HTTPS for all API communications to ensure data security

User Experience Guidelines

Implement polling with appropriate intervals (e.g., every 30 seconds) to check job status

Display meaningful progress indicators to users while jobs are pending

Provide clear download options when jobs complete successfully

Implement proper error handling and user-friendly error messages

Code Samples

cURL

Python

Node.js

Related APIs

Bulk Upload API: Used to initiate bulk processing jobs and obtain the client_id

Bulk Download API: Alternative method to download processed results

Bulk Job Management API: Used to manage and control bulk processing jobs

Compliance and Legal Considerations

When downloading and storing processed data, ensure compliance with data protection regulations such as GDPR or PDPA. The download links are temporary and expire after a short period (typically 10 minutes), so implement proper download handling. Processed data may contain sensitive information, so ensure appropriate security measures are in place for storing and handling the downloaded files.

{ "data": { "client_id": "bulk_solver_MtgsMgkeieLxIwovtpRT", "type_of_job": "gstin", "job_status": "success", "download_link": "https://bulk-request-docs.s3.amazonaws.com/bulk_solver_MtgsMgkeieLxIwovtpRT-bulk-2024-01-11-064415133845.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5FYWPQJEB%2F20240122%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20240122T092821Z&X-Amz-Expires=600&X-A" }, "status_code": 200, "message_code": "success", "message": null, "success": true }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Bulk Status

Bulk Status#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Path Parameters#

Request Body#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Bulk Status

Description

Use Cases

Technical Implementation

Request Headers

Path Parameters

Request Body

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples