HomeGuidesAPI Reference
Guides

Business Address Verification 👔

Suggest Edits

Overview

The Address Verification Service accepts the lastName, Street name, LGA, phone number, kyc type and searchParameter and returns detailed information on the address verified to the customer's webhook. This article will guide you on integrating to the Business Address Verification Service.

🚧

Important!

Before you proceed, ensure you review the prerequisites for integrating to our APIs for a more detailed guide.

API Endpoint

{{Prod}}/sfx-v4-verify/v4/id-service/

Headers

Our service accepts headers for authentication. See below the headers to pass to the API

HeaderTypeDescription
useridStringThis is your user id retrieved from the portal. Check the getting started article to understand how to retrieve your userid
apiKeyStringThis is your api key retrieved from the portal. Check the getting started article to understand how to retrieve your apiKey

Request

Request ParameterStatusDescriptiontypeTest Data
firstNameOptionalThe first name will be passed into this fieldStringJohn
lastNameRequiredThe last name will be passed into this fieldStringDoe
dobOptionalThe date of birth will be passed into this fielddateString04-04-1944
phoneRequiredThe phone number will be passed into this fieldString08098289033
verificationTypeRequiredThis field is used to identify the service being called. Ensure to use the value provided exactly as providedStringBUSINESS-ADDRESS-VERIFICATION
kycTypeOptionalThis field depicts the Identity type to be used for the verificationenum : {nin, bvn, frsc, drivers_license }frsc
callbackUrlRequiredThe callback url is inputted hereString"https://webhook.site/7518d538-18ad-4eeb-b944-e168c54d020f"
searchParameterRequiredThe lD number will be passed into this fieldStringPQR41659AA50
streetRequiredThe street name will be passed into this fieldString270 Murtala Muhammed Way, Alagomeji. Yaba
lgaRequiredThe local government area will be passed into this fieldStringsurulere
cityOptionalThe city will be passed into this fieldStringlagos
stateRequiredThe state will be passed into this fieldStringlagos
landmarkRequiredThe landmark will be passed into this fieldStringBeside GTbank
canContactPocRequiredConsentbooleantrue
businessTypeRequiredBusiness TypeStringformal
companyNameRequiredRegistered Business Nameenum : {Formal , Informal }John
rcNumberRequiredStringRC111111
{
    "firstName": "John",
    "lastName": "Doe",
    "phone": "08098289033",
    "companyName": "John",
    "businessType": "formal",
    "rcNumber": "RC111111",
    "kycType": "frsc",
    "verificationType": "BUSINESS-ADDRESS-VERIFICATION",
    "callbackUrl":"https://webhook.site/71f0e4a3-84a0-405d-97e6-9d4f1530ea86",
    "searchParameter": "PQR41659AA50",
    "street": "27 Murtala Muhammed Way, Alagomeji. Yaba",
    "lga": "surulere",
    "city": "lagos",
    "state": "lagos",
    "landmark": "Beside GTbank",
    "canContactPoc":true
}

Initial Response

(This is the response you would get when you submit a response for Business Address Verification)

Response ParameterTypeDescription
responseCodeStringPlease reference Response Codes page for details on all possible responses.
descriptionStringThis is a description of the response received.
verificationTypeStringThe same verificationType passed in request will be returned here
verificationStatusStringThis field lets you know if the identity verification was successful. Options are:

VERIFIED: This means that the ADDRESS-VERIFICATION is valid.
NOT VERIFIED This means that the ADDRESS-VERIFICATION is invalid
PENDING This status means that the verification could not be completed. Refer to the responseCode for the specific failure reason.
transactionStatusStringThis indicates the wallet debit status. The options are successful or failed.
transactionReferenceStringIf you supplied a transactionReference, the same will be returned here. Else, we would generate a reference and return that to you in this field.
transactionDateStringDate the transaction was done
searchParameterStringDriver's License number used for the address verification
responseJsonThis is a json containing all the actual BUSINESS ADDRESS VERIFICATION data as retrieved from the service provider.
{
    "responseCode": "00",
    "description": "Successful",
    "verificationType": "BUSINESS-ADDRESS-VERIFICATION",
    "verificationStatus": "VERIFIED",
    "transactionStatus": "SUCCESSFUL",
    "transactionReference": "1630321373727-SPO2UM82-1718896065326-890d7a19-0b65-4141-9f03-a28318ffd237",
    "transactionDate": "1718896067007",
    "searchParameter": "PQR41659AA50",
    "callBackUrl": null,
    "livenessScore": null,
    "paymentRef": null,
    "response": {
        "id": 4196334,
        "customerReference": "1630321373727-SPO2UM82-1718896065326-890d7a19-0b65-4141-9f03-a28318ffd237",
        "status": 0,
        "statusCode": 0,
        "message": null,
        "error": null,
        "applicant": {
            "organisationId": 164295,
            "customerReference": "1630321373727-SPO2UM82-1718896065326-890d7a19-0b65-4141-9f03-a28318ffd237",
            "firstname": "John",
            "lastname": "Doe",
            "phone": "+2348098289033",
            "dob": null,
            "gender": null,
            "maritalStatus": null,
            "photo": null,
            "imageId": null,
            "faceId": null,
            "email": null
        },
        "summary": {
            "address_check": "IN_PROGRESS"
        },
        "address": {
            "verificationTypeCode": "address",
            "organisationId": 164295,
            "requestedAt": "2024-06-20T15:07:46.000Z",
            "requestSource": "api",
            "archived": false,
            "stateId": 25,
            "stateName": "Lagos",
            "lgaId": 519,
            "lgaName": "Surulere",
            "applicationId": 5209,
            "countryName": "Nigeria",
            "location": {
                "city": "lagos",
                "initialLatitude": 6.4920043,
                "initialLongitude": 3.3789529,
                "landmark": "Beside GTbank",
                "latitude": 6.4920043,
                "lgaName": "Surulere",
                "locationUrl": "https://maps.google.com/?q=6.4920043,3.3789529",
                "longitude": 3.3789529,
                "stateName": "lagos",
                "street": "27 Murtala Muhammed Way, Alagomeji. Yaba"
            },
            "addressBasic": {
                "addressType": ""
            },
            "customerReference": "1630321373727-SPO2UM82-1718896065326-890d7a19-0b65-4141-9f03-a28318ffd237",
            "paymentMethodCode": "standard",
            "status": {
                "status": "IN_PROGRESS",
                "subStatus": "IN PROGRESS",
                "state": "IN_PROGRESS"
            },
            "live": false,
            "duplicate": false,
            "vague": false
        }
    },
    "faceMatch": null,
    "licenseSessionId": null,
    "remainingLicenseSessionRound": null
}

Final Response (Received via Webhook)

{
    "event": "address",
    "event_type": "verification_completed",
    "data": {
        "id": 1,
        "summary": null,
        "customerReference": "1630321373727-SOJZP2Z2-1716208583375-5376c4f7-0c76-4c10-b720-2cfa357bf21b",
        "address": {
            "id": 1,
            "verificationTypeCode": "address",
            "organisationId": 1,
            "userId": null,
            "approvedAt": "2023-08-04T15:57:53.000Z",
            "requestedAt": "2023-08-04T11:42:30.000Z",
            "identityVerificationId": null,
            "requestSource": "api",
            "archived": false,
            "apiReference": null,
            "stateId": 25,
            "stateName": "Lagos",
            "lgaId": 514,
            "lgaName": "Lagos Mainland",
            "applicationId": 1,
            "neighbor": {
                "comment": "The address exists and the applicant lives at the address and this was confirmed by a neighbor living in the compound. The nearest landmark to the address is carwash bus stop",
                "firstname": null,
                "lastname": null,
                "phone": ""
            },
            "countryName": "Nigeria",
            "isLive": true,
            "isDuplicate": false,
            "location": {
                "city": "ADEKUNLE",
                "initialLatitude": 6.4883519,
                "initialLongitude": 3.3820116,
                "landmark": "ADEKUNLE",
                "latitude": 6.4860838,
                "lgaName": "Lagos Mainland",
                "locationUrl": "https://maps.google.com/?q=6.4883519,3.3820116",
                "longitude": 3.3063121,
                "stateName": "Lagos",
                "street": "EBUTE META, GLOVER STREET"
            },
            "addressBasic": {
                "addressType": ""
            },
            "business": {
                "area": "commercial",
                "businessName": null,
                "businessType": null,
                "canContactPoc": null,
                "id": null,
                "isKnown": null,
                "isOwnerKnown": null,
                "name": null,
                "nameFound": "",
                "ownerVisitsFrequently": null,
                "rcNumber": null,
                "type": null
            },
            "isVague": true,
            "customerReference": "1",
            "paymentMethodCode": "standard",
            "applicant": {
                "organisationId": 1,
                "applicantId": null,
                "customerReference": "1",
                "firstname": "John",
                "middlename": null,
                "lastname": "Doe",
                "phone": "+2347030000000",
                "email": null,
                "dob": "1960-10-01",
                "gender": null,
                "maritalStatus": null,
                "photo": null,
                "imageId": null,
                "faceId": null
            },
            "price": 2,
            "agentComment": "Verification completed",
            "agentSubmittedAt": "2023-08-04T15:51:00.000Z",
            "rejectedAt": null,
            "interiorPhotos": {},
            "exteriorPhotos": {
                "photo1": "https://seamfix.com/image/...",
                "photo2": "https://seamfix.com/image/..",
                "photo3": "https://seamfix.com/image/.."
            },
            "extraPhotos": {},
            "status": {
                "status": "VERIFIED",
                "subStatus": "VERIFIED",
                "state": "COMPLETE"
            }
        }
    }
}

Updated 6 months ago