DigiPin

Endpoint Overview

POST /api/v1/utils/digipin/

Description

The Digipin Generation API converts geographic coordinates (latitude and longitude) into a unique, human-readable alphanumeric code called a "Digipin". This service provides a standardized way to encode precise geographic locations into short, memorable codes that can be easily shared, stored, and referenced. The Digipin system creates a universal addressing solution that works across different mapping systems and platforms.

This API is particularly valuable for businesses that need to standardize location references, create shareable location codes, or implement location-based services where traditional addresses may be insufficient or unavailable.

Key Benefits

Standardized Location Encoding: Convert any GPS coordinates into a consistent, unique identifier

Human-Readable Format: Generate codes that are easy to share and remember compared to raw coordinates

Universal Compatibility: Works with any location worldwide, regardless of traditional addressing systems

Precise Location Mapping: Maintains high accuracy while providing a simplified reference system

Use Cases

Logistics & Delivery

Real Estate & Construction

Emergency Services

Last-mile delivery optimization for areas without standard addresses

Warehouse and distribution center location coding

Fleet management and route optimization systems

Package tracking and location verification

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	Bearer token for API authentication (JWT format)
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
latitude	String	Yes	The latitude coordinate as a decimal string (e.g., "15.83453574")
longitude	String	Yes	The longitude coordinate as a decimal string (e.g., "78.53027344")

Example Request

{
    "latitude": "15.83453574",
    "longitude": "78.53027344"
}

Process Response

Response Parameters

Parameter	Type	Description
data.client_id	String	Unique client identifier for the request
data.latitude	Number	The processed latitude coordinate as a number
data.longitude	Number	The processed longitude coordinate as a number
data.digipin	String	The generated digipin code (format: XXX-XXX-XXXX)
status_code	Number	HTTP status code of the response
success	Boolean	Indicates whether the request was successful
message	String	Human-readable status message
message_code	String	Machine-readable status code

Example Successful Response

{
    "data": {
        "client_id": "digipin_UlrmHNmUQejqjaETillR",
        "latitude": 15.83453574,
        "longitude": 78.53027344,
        "digipin": "459-285-L38L"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Invalid Longitude

Invalid Latitude

{
    "data": null,
    "status_code": 401,
    "success": false,
    "message": "Invalid or expired authentication token",
    "message_code": "auth_error"
}

Occurs when the Bearer token is invalid, expired, or missing from the request headers.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and implement proper token refresh mechanisms

Use HTTPS for all API communications to protect sensitive location data

Implement rate limiting on your client side to avoid exceeding API quotas

Validate coordinate inputs before sending requests to prevent unnecessary API calls

User Experience Guidelines

Cache generated digipins locally to reduce API calls for frequently accessed locations

Implement fallback mechanisms for network failures or API unavailability

Provide clear error messages to users when coordinate conversion fails

Consider implementing batch processing for multiple coordinate conversions

Code Samples

cURL

Python

Node.js

Related APIs

Reverse Geocoding API - Convert addresses to coordinates for digipin generation
Location Validation API - Validate coordinate accuracy before digipin creation
Bulk Digipin Generation API - Process multiple coordinates in a single request
Digipin Lookup API - Convert digipin codes back to geographic coordinates

Compliance and Legal Considerations

Ensure compliance with local data privacy regulations when processing location data. Be aware that some jurisdictions may have restrictions on location tracking and data storage. Always obtain proper user consent before collecting and processing geographic coordinates. Consider implementing data retention policies and anonymization strategies for stored location information.

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/utils/digipin/' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "latitude": "15.83453574", "longitude": "78.53027344" }'

{ "data": { "client_id": "digipin_UlrmHNmUQejqjaETillR", "latitude": 15.83453574, "longitude": 78.53027344, "digipin": "459-285-L38L" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

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