Verification Service API

A unified microservice for Ghana Post GPS digital address lookups and Ghana Card identity validation.

Base URL
Authentication
No API key is required. The service internally authenticates with upstream providers (Ghana Post GPS & GRA) using its own credentials configured at startup.

All endpoints accept application/json or application/x-www-form-urlencoded bodies and always respond with application/json. CORS is open on all origins.

GPS Endpoints
POST /gps-details Resolve a Ghana digital address to location details
Converts a Ghana Post GPS code (e.g. GW-1191-7271) into full location details including region, district, coordinates and postal code.
Request Body
FieldTypeDescription
addressrequired string Ghana Post digital address code (e.g. GA-585-7449)
Example Request
{ "address": "GW-1191-7271" }
curl -X POST [base]/gps-details \
  -H "Content-Type: application/json" \
  -d '{"address":"GW-1191-7271"}'
Example Response
{
  "code":    "000",
  "message": "Address found",
  "data": {
    "CenterLatitude":  5.618912058437649,
    "CenterLongitude": -0.25725493105593,
    "GPSName":  "GC11917271",
    "PostCode": "GC1191",
    "Region":   "Greater Accra",
    "District": "Ga Central",
    "Street":   "1563"
  }
}
Response Codes
200"000" success · "404" not found · "422" error
Try it

            

          

        

      


      
      

        

          POST
          /verify-gps-details
          Alias for /gps-details
        

        

          

            Identical to /gps-details. Provided for compatibility with existing integrations.
          

          
Accepts the same request body and returns the same response as /gps-details.

        

      


      
      

        

          POST
          /geo-location
          Resolve coordinates to a Ghana digital address
        

        

          

            Converts a latitude/longitude pair into a Ghana Post GPS code and full location details.
          


          
Request Body

          

            
FieldTypeDescription

            

              latituderequired
              number
              Latitude (decimal degrees)
            

            

              longituderequired
              number
              Longitude (decimal degrees)
            

          


          
Example Request

          

            

              
              
            

            
{ "latitude": 5.618912, "longitude": -0.257255 }

            
curl -X POST [base]/geo-location \
  -H "Content-Type: application/json" \
  -d '{"latitude":5.618912,"longitude":-0.257255}'

          


          
Example Response

          
{
  "code":    "000",
  "message": "Address found",
  "data": {
    "GPSName":    "GC11917271",
    "PostCode":   "GC1191",
    "Region":     "Greater Accra",
    "District":   "Ga Central",
    "PostalArea": "Nii Boi Man 1191",
    "Street":     "1563"
  }
}


          
Response Codes

          

            
200"000" success · "404" not found · "422" error

          


          
          

            
Try it

            

              

                
                
              

              

                
                
              

            

            
            

              

                
                
              

              

            

          

        

      

    


    


    
    

      
Identity Endpoints


      
      

        

          POST
          /card-validation
          Validate a Ghana Card number via GRA
        

        

          

            Verifies a Ghana Card number against the Ghana Revenue Authority (GRA) API.
            Returns a boolean status indicating whether the card is valid.
          


          
Request Body

          

            
FieldTypeDescription

            

              IDrequired
              string
              Ghana Card number (format: GHA-XXXXXXXXX-X)
            

            

              Typeoptional
              string
              Defaults to "validatePin"
            

          


          
Example Request

          

            

              
              
            

            
{ "ID": "GHA-712429053-1", "Type": "validatePin" }

            
curl -X POST [base]/card-validation \
  -H "Content-Type: application/json" \
  -d '{"ID":"GHA-712429053-1","Type":"validatePin"}'

          


          
Example Response — Valid Card

          
{
  "success": true,
  "ID":      "GHA-712429053-1",
  "Type":    "validatePin",
  "status":  true,
  "raw":     "true"
}


          
Example Response — Invalid Card

          
{
  "success": true,
  "ID":      "GHA-712429053-0",
  "Type":    "validatePin",
  "status":  false,
  "raw":     "false"
}


          
Response Codes

          

            
200Completed — check status field for result

            
400Missing ID

            
502GRA API unreachable

          


          
          

            
Try it