Users API

This is the Users API that provides programmatic access to various resources and services. The API supports the following areas: User Profile, User Onboarding, User Compliance, User Messages. All endpoints require authentication using a Bearer token.

The users model

The users model contains all the information about your users entities.

Properties

Name
firstName
Type
string
Description
The firstName for the users.
Name
lastName
Type
string
Description
The lastName for the users.
Name
email
Type
string
Description
The email for the users.
Name
phoneNumber
Type
string
Description
The phoneNumber for the users.
Name
dateOfBirth
Type
string
Description
The dateOfBirth for the users.
Name
countryCode
Type
string
Description
The countryCode for the users.
Name
preferredLanguage
Type
string
Description
The preferredLanguage for the users.

Onboard New User

Creates new user account with basic profile information and generates unique account identifier for digital banking platform

Request

POST

/v1/users

curl -X POST https://api.adiba.app/v1/users \
  -H "Authorization: Bearer {token}" \
  -d '{
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@email.com",
"phoneNumber": "+2348012345678",
"dateOfBirth": "1990-05-15",
"countryCode": "NG",
"preferredLanguage": "en"
}'

{
"userId": "USR_001_20241201_001",
"status": "PENDING",
"createdAt": "2024-12-01T10:30:00Z",
"message": "User account created successfully. Please complete identity verification."
}

Lookup Existing User

Retrieves comprehensive user profile details and account status using account number identifier for verification and service access

Required attributes

Name
accountNo
Type
string
Description
Accountno parameter specified in the URL path

Request

GET

/v1/users/by/{accountNo}

curl -G https://api.adiba.app/v1/users/by/{accountNo} \
  -H "Authorization: Bearer {token}"

{
}

Onboard Existing User

Completes onboarding process for existing account holders by updating profiles and activating digital banking services

Required attributes

Name
accountNo
Type
string
Description
Accountno parameter specified in the URL path

Request

POST

/v1/users/by/{accountNo}

curl -X POST https://api.adiba.app/v1/users/by/{accountNo} \
  -H "Authorization: Bearer {token}" \
  -d '{
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@email.com",
"phoneNumber": "+2348012345678",
"dateOfBirth": "1990-05-15",
"address": {
    "street": "123 Main Street",
    "city": "Lagos",
    "state": "Lagos",
    "postalCode": "100001",
    "country": "Nigeria"
},
"preferences": {
    "language": "en",
    "timezone": "Africa/Lagos",
    "notifications": {
        "email": true,
        "sms": true,
        "push": false
    }
}
}'

{
"userId": "USR_001_20241201_001",
"accountNumber": "ACC_001_20241201_001",
"status": "ACTIVE",
"updatedAt": "2024-12-01T11:00:00Z",
"message": "User profile updated and services activated successfully."
}

Trigger Identity Verification

Initiates identity verification using country-specific documents like BVN NIN SSN VIN for regulatory compliance

Request

POST

/v1/users/identity/lookup

curl -X POST https://api.adiba.app/v1/users/identity/lookup \
  -H "Authorization: Bearer {token}" \
  -d '{
"identityType": "BVN",
"identityNumber": "12345678901",
"country": "Nigeria",
"firstName": "John",
"lastName": "Doe",
"dateOfBirth": "1990-05-15",
"phoneNumber": "+2348012345678"
}'

{
"verificationId": "VER_001_20241201_001",
"status": "PENDING",
"verificationMethod": "SMS",
"estimatedTime": "5-10 minutes",
"message": "Identity verification initiated. Verification code sent to your phone.",
"nextStep": "Enter the verification code sent to your phone"
}

Resend Verification Code

Sends new verification code via SMS when original code expires or is not received by user

Request

POST

/v1/users/identity/resend-code

curl -X POST https://api.adiba.app/v1/users/identity/resend-code \
  -H "Authorization: Bearer {token}" \
  -d '{
"verificationId": "VER_001_20241201_001",
"phoneNumber": "+2348012345678"
}'

{
"status": "SUCCESS",
"message": "New verification code sent successfully",
"resendCount": 2,
"nextResendTime": "2024-12-01T10:45:00Z",
"expiresAt": "2024-12-01T10:50:00Z"
}

Confirm Identity Verification

Validates verification code and activates user account in core banking systems with security checks

Request

POST

/v1/users/identity/confirm

curl -X POST https://api.adiba.app/v1/users/identity/confirm \
  -H "Authorization: Bearer {token}" \
  -d '{
"verificationId": "VER_001_20241201_001",
"verificationCode": "123456",
"phoneNumber": "+2348012345678"
}'

{
"status": "VERIFIED",
"userId": "USR_001_20241201_001",
"verificationLevel": "FULL",
"verifiedAt": "2024-12-01T10:35:00Z",
"message": "Identity verification completed successfully. Your account is now fully verified."
}

Upload Compliance Document

Handles regulatory compliance document uploads including marriage certificates utility bills and bank statements

Request

POST

/v1/users/compliance/upload

curl -X POST https://api.adiba.app/v1/users/compliance/upload \
  -H "Authorization: Bearer {token}" \
  -d '{
"documentType": "UTILITY_BILL",
"documentName": "Lagos Electricity Bill December 2024",
"fileContent": "JVBERi0xLjQKJcOkw7zDtsO...",
"fileType": "PDF",
"expiryDate": "2025-01-31",
"description": "Monthly electricity bill for address verification"
}'

{
"documentId": "DOC_001_20241201_001",
"status": "UPLOADED",
"processingStatus": "PENDING",
"uploadedAt": "2024-12-01T11:15:00Z",
"fileSize": 245760,
"message": "Compliance document uploaded successfully and queued for processing"
}

Upload Identity Document

Manages government-issued ID document uploads for KYC compliance with fraud detection and validation

Request

POST

/v1/users/identification/upload

curl -X POST https://api.adiba.app/v1/users/identification/upload \
  -H "Authorization: Bearer {token}" \
  -d '{
"documentType": "PASSPORT",
"documentNumber": "A12345678",
"issuingCountry": "Nigeria",
"issueDate": "2020-01-15",
"expiryDate": "2030-01-15",
"fileContent": "iVBORw0KGgoAAAANSUhEUgAA...",
"fileType": "JPG",
"documentSide": "FRONT"
}'

{
"documentId": "ID_001_20241201_001",
"status": "UPLOADED",
"verificationStatus": "PENDING",
"extractedData": {
    "documentNumber": "A12345678",
    "fullName": "John Doe",
    "dateOfBirth": "1990-05-15",
    "expiryDate": "2030-01-15"
},
"uploadedAt": "2024-12-01T11:20:00Z",
"message": "Identity document uploaded successfully. OCR processing completed."
}

View User Avatar

Retrieves user profile picture for display in banking interface with access control

Request

GET

/v1/users/profile/avatar

curl -G https://api.adiba.app/v1/users/profile/avatar \
  -H "Authorization: Bearer {token}"

{
}

Upload Profile Picture

Allows users to upload profile pictures for account personalization and visual identification purposes

Request

POST

/v1/users/profile/avatar

curl -X POST https://api.adiba.app/v1/users/profile/avatar \
  -H "Authorization: Bearer {token}" \
  -d '{
"fileContent": "iVBORw0KGgoAAAANSUhEUgAA...",
"fileType": "JPG",
"fileName": "profile_photo.jpg"
}'

{
"avatarId": "AVT_001_20241201_001",
"status": "UPLOADED",
"imageUrl": "https://cdn.bank.com/avatars/USR_001_20241201_001.jpg",
"thumbnailUrl": "https://cdn.bank.com/avatars/USR_001_20241201_001_thumb.jpg",
"uploadedAt": "2024-12-01T11:25:00Z",
"fileSize": 102400,
"dimensions": {
    "width": 400,
    "height": 400
},
"message": "Profile picture uploaded successfully"
}

Trigger Email Verification

Sends confirmation email with verification link to validate user email address ownership

Request

POST

/v1/users/email/verify

curl -X POST https://api.adiba.app/v1/users/email/verify \
  -H "Authorization: Bearer {token}" \
  -d '{
"email": "john.doe@email.com",
"userId": "USR_001_20241201_001"
}'

{
"verificationId": "EMAIL_VER_001_20241201_001",
"status": "SENT",
"email": "john.doe@email.com",
"expiresAt": "2024-12-02T10:30:00Z",
"message": "Verification email sent successfully",
"resendAvailable": true
}

View User Profile

Retrieves comprehensive user profile information for account management and verification purposes

Request

GET

/v1/users/profile

curl -G https://api.adiba.app/v1/users/profile \
  -H "Authorization: Bearer {token}"

{
}

Change User Password

Allows authenticated users to update passwords with current password verification

Request

POST

/v1/users/password/change

curl -X POST https://api.adiba.app/v1/users/password/change \
  -H "Authorization: Bearer {token}" \
  -d '{
"currentPassword": "SecurePass123!",
"newPassword": "NewSecurePass789!",
"confirmPassword": "NewSecurePass789!"
}'

{
"status": "SUCCESS",
"message": "Password changed successfully",
"passwordChangedAt": "2024-12-01T13:15:00Z",
"sessionsInvalidated": 2,
"nextLoginRequired": false
}

Update User Attributes

Enables users to modify profile information using PATCH semantics for partial updates

Required attributes

Name
userId
Type
string
Description
Unique identifier specified in the URL path

Request

PATCH

/v1/users/{userId}

curl -X PATCH https://api.adiba.app/v1/users/{userId} \
  -H "Authorization: Bearer {token}" \
  -d '{
"firstName": "John",
"lastName": "Smith",
"email": "john.smith@email.com",
"phoneNumber": "+2348012345678",
"address": {
    "street": "456 New Street",
    "city": "Abuja",
    "state": "FCT",
    "postalCode": "900001",
    "country": "Nigeria"
},
"preferences": {
    "language": "en",
    "timezone": "Africa/Lagos",
    "notifications": {
        "email": true,
        "sms": false,
        "push": true
    }
}
}'

{
"userId": "USR_001_20241201_001",
"status": "SUCCESS",
"updatedFields": [
    "firstName",
    "lastName",
    "email",
    "address",
    "preferences"
],
"updatedAt": "2024-12-01T13:20:00Z",
"requiresVerification": [
    "email"
],
"message": "Profile updated successfully. Email verification required for new email address."
}

Read User Messages

Retrieves system notifications and messages with pagination filtering and sorting options

Request

GET

/v1/users/messages

curl -G https://api.adiba.app/v1/users/messages \
  -H "Authorization: Bearer {token}"

{
}

Delete User Message

Allows users to remove specific messages from inbox with soft deletion for audit

Required attributes

Name
messageId
Type
string
Description
Unique identifier specified in the URL path

Request

DELETE

/v1/users/messages/{messageId}

curl -X DELETE https://api.adiba.app/v1/users/messages/{messageId} \
  -H "Authorization: Bearer {token}" \
  -d '{
"example": "data"
}'

{
}