Create And Geocode A Customer

Developing

POST

/api/v1/public/customer/geocode

Creates a customer record with verified status and resolves their address in a single call, returning coordinates, Street View stills and risk signals. Returns 409 without charging when the customerId already exists under your company, so this endpoint cannot be used to update an existing customer. On success the wallet is debited, including on cache hits, at the rate matching the returned risk level.

Request

Authorization

API Key

Add parameter in header

X-Api-Key

Example:

X-Api-Key: ********************

Body Params application/jsonRequired

Examples

Responses

🟢200

application/json

Customer created, address resolved and the wallet debited.

Bodyapplication/json

🟠400

🟠401

🟠409

Request Example

Shell

JavaScript

Java

Swift

curl --location '/api/v1/public/customer/geocode' \
--header 'X-Api-Key: <api-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "customerId": "CUST-000412",
    "fullName": "Adaeze Okonkwo",
    "fullAddress": "12 Adeola Odeku Street, Victoria Island, Lagos",
    "emailAddress": "adaeze@example.com",
    "phoneNumber": "+2348012345678"
}'

Response Example

200 - Example 1

{
    "status": true,
    "message": "Operation successful.",
    "data": {
        "latitude": 6.4281,
        "longitude": 3.4219,
        "formattedAddress": "string",
        "customerId": "string",
        "fullName": "string",
        "emailAddress": "string",
        "phoneNumber": "string",
        "addressImages": [
            {
                "heading": 90,
                "imageUrl": "http://example.com"
            }
        ],
        "billingInfo": {
            "wasCharged": true,
            "amount": "50.00",
            "currency": "NGN",
            "note": "Address geocode charge"
        },
        "riskSignals": {
            "riskLevel": "Low",
            "locationType": "ROOFTOP",
            "streetViewAvailable": true,
            "streetViewDate": "2023-03",
            "reverseGeocodeMatch": true,
            "streetNumber": "string",
            "route": "string",
            "neighbourhood": "string",
            "lga": "Ikeja",
            "state": "Lagos",
            "country": "Nigeria",
            "postalCode": "string",
            "nearbyPlaces": [
                {
                    "name": "Ikeja City Mall",
                    "category": "shopping_mall",
                    "vicinity": "Obafemi Awolowo Way, Ikeja",
                    "distanceMetres": 180
                }
            ]
        }
    }
}

Modified at 2026-08-06 11:58:31

Geocode An Address