Digipin Reverse

Endpoint Overview

POST /api/v1/utils/digipin/reverse

Description

The Digipin Reverse API enables you to retrieve geographical coordinates (latitude and longitude) from a Digipin code. Digipin is a location encoding system that converts geographical coordinates into a short, memorable alphanumeric code. This reverse lookup service allows you to decode these Digipin codes back to their original latitude and longitude values, enabling location-based services and mapping applications.

This API is essential for applications that need to convert user-friendly location codes into precise geographical coordinates for navigation, delivery services, location sharing, and geospatial analysis.

Key Benefits

Precise Location Retrieval: Convert compact Digipin codes to exact geographical coordinates

Enhanced User Experience: Enable users to share locations using short, memorable codes instead of complex coordinates

Integration Ready: Simple JSON API that integrates seamlessly with mapping and location services

Reliable Performance: Built on robust infrastructure with high availability and fast response times

Use Cases

Logistics & Delivery

Real Estate & Hospitality

Emergency & Public Services

Last-Mile Delivery: Convert customer-shared Digipin codes to coordinates for accurate delivery routing

Warehouse Management: Use Digipin codes for precise inventory location tracking within facilities

Fleet Management: Enable drivers to navigate to locations using simple Digipin references

Pickup Services: Allow customers to share pickup locations using easy-to-remember codes

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
digipin	string	Yes	The Digipin code to be reversed into coordinates (format: XXX-XXX-XXXX)

Example Request

{
    "digipin": "459-T7P-L38L"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container object holding the response data
data.client_id	string	Unique identifier for the API request session
data.digipin	string	The original Digipin code that was processed
data.latitude	number	Latitude coordinate (decimal degrees format)
data.longitude	number	Longitude coordinate (decimal degrees format)
status_code	number	HTTP status code of the response
success	boolean	Indicates whether the API call was successful
message	string	Human-readable status message
message_code	string	Machine-readable status code identifier

Example Successful Response

{
    "data": {
        "client_id": "digipin_reverse_aKwlRchefrZaIUnzmcSy",
        "digipin": "459-T7P-L38L",
        "latitude": 15.50934,
        "longitude": 78.6709
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Digipin Format

Authentication Error

Digipin Not Found

{
    "data": null,
    "status_code": 400,
    "success": false,
    "message": "Invalid Digipin format provided",
    "message_code": "invalid_format"
}

Returned when the Digipin code doesn't match the expected format (XXX-XXX-XXXX).

Integration Best Practices

Security Recommendations

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

Implement token refresh mechanisms to handle expired authentication tokens

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

Validate and sanitize Digipin inputs on both client and server sides before making API calls

Implement rate limiting in your application to prevent abuse and ensure fair usage

User Experience Guidelines

Provide clear error messages to users when Digipin codes are invalid or not found

Implement loading states while API requests are processing to improve perceived performance

Cache frequently requested Digipin lookups to reduce API calls and improve response times

Validate Digipin format on the client side before making API requests to provide immediate feedback

Display coordinates in user-friendly formats appropriate for your application context

Code Samples

cURL

Python

Node.js

Related APIs

Digipin Generation API - Convert latitude/longitude coordinates into Digipin codes for location encoding and sharing
Location Validation API - Verify the accuracy and validity of geographical coordinates before processing
Geocoding Services - Convert addresses to coordinates and vice versa for comprehensive location services
Distance Calculator API - Calculate distances between multiple Digipin locations for routing applications

Compliance and Legal Considerations

Ensure compliance with data privacy regulations (GDPR, CCPA) when handling location data. Obtain proper user consent before processing location information. Be aware of location accuracy limitations and inform users accordingly. Consider implementing data retention policies for location lookups and maintain audit logs for compliance purposes. Some regions may have restrictions on location data usage - verify local regulations before implementation.

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/reverse' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "digipin": "459-T7P-L38L" }'

{ "data": { "client_id": "digipin_reverse_aKwlRchefrZaIUnzmcSy", "digipin": "459-T7P-L38L", "latitude": 15.50934, "longitude": 78.6709 }, "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